◇ Open Values Standardfor builders

Spec / ovs-node-runtime-states

Open Values Node Runtime States v0.1

The states the app can be in while loading the generated files, such as loading, unavailable or offline, with what the app must and must not do in each. The data build writes them as tests for the app. It is an internal file used while building the site.

Used while building the sites. Not meant for other apps. Data kept for tests, not for use.

Who writes it and who reads it

Written by pipeline/build_nodes.js. Read by app-lane integration, runtime QA.

Fields

FieldWhat it meansType
format requiredNames this file's format, so a reader can check it before reading the rest of the file.always "ovs-node-runtime-states"
version requiredThe version of the format this file follows, such as "0.1".see version
built requiredThe date of the source data this file was built from, as YYYY-MM-DD.see date
source requiredThe script and files this file was built from, as paths in the repository.see source
purpose requiredOne sentence on what this file is for.see nonEmptyString
appLaneNote requiredA note on which choices this file leaves to the app code that reads it, such as fetching, layout and wording.see nonEmptyString
caseFields requiredThe names of the fields each case carries.list
qaContract requiredHow the cases are grouped for testing, and when this part of H4 can close.see qaContract
cases requiredOne case per state the app can be in while loading generated files, such as loading, unavailable or offline.list
totals requiredHow many cases there are, overall and by family.object

A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.

A file that passes

Runtime-state fixtures define required behaviors, must-not boundaries, copy intent, and source files.

{
  "format": "ovs-node-runtime-states",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/node-load-plan.json"
  ],
  "purpose": "Runtime state and failure-mode fixtures.",
  "appLaneNote": "State contract only.",
  "caseFields": [
    "id",
    "family",
    "stage"
  ],
  "qaContract": {
    "purpose": "App-owned runtime QA contract for generated node states.",
    "status": "pending-app-integration",
    "h4DrainableFromDataAlone": false,
    "drainRule": "H4 drains only after app-owned behavior is checked.",
    "modes": [
      {
        "id": "startup-smoke",
        "owner": "app/design",
        "caseIds": [
          "metadata-loading"
        ],
        "sourceFiles": [
          "manifest.json"
        ],
        "passWhen": [
          "Base app stays usable."
        ],
        "mustNot": [
          "Do not block browsing."
        ]
      }
    ],
    "loadStageCoverage": {
      "bootstrap-metadata": {
        "loadHint": "eager-metadata",
        "runtime": true,
        "sourceFiles": [
          "manifest.json"
        ],
        "caseIds": [
          "metadata-loading"
        ]
      }
    },
    "coverage": {
      "caseCount": 1,
      "modeCount": 1,
      "stagesCovered": 1,
      "allCasesCovered": true,
      "runtimeModeIds": [
        "startup-smoke"
      ],
      "manualReviewModeIds": [
        "startup-smoke"
      ]
    }
  },
  "cases": [
    {
      "id": "metadata-loading",
      "family": "loading",
      "stage": "bootstrap-metadata",
      "trigger": "Metadata is loading.",
      "requiredBehavior": [
        "Keep the base app usable."
      ],
      "mustNot": [
        "Do not block category browsing."
      ],
      "appOwnedCopyIntent": "Use calm, honest copy.",
      "sourceFiles": [
        "manifest.json"
      ]
    }
  ],
  "totals": {
    "cases": 1
  }
}

A file that must be rejected

Runtime-state fixtures must name at least one must-not boundary.

{
  "format": "ovs-node-runtime-states",
  "version": "0.1",
  "built": "2026-07-07",
  "source": [
    "app/data/nodes/node-load-plan.json"
  ],
  "purpose": "Runtime state and failure-mode fixtures.",
  "appLaneNote": "State contract only.",
  "caseFields": [
    "id",
    "family",
    "stage"
  ],
  "qaContract": {
    "purpose": "App-owned runtime QA contract for generated node states.",
    "status": "pending-app-integration",
    "h4DrainableFromDataAlone": false,
    "drainRule": "H4 drains only after app-owned behavior is checked.",
    "modes": [
      {
        "id": "startup-smoke",
        "owner": "app/design",
        "caseIds": [
          "metadata-loading"
        ],
        "sourceFiles": [
          "manifest.json"
        ],
        "passWhen": [
          "Base app stays usable."
        ],
        "mustNot": [
          "Do not block browsing."
        ]
      }
    ],
    "loadStageCoverage": {
      "bootstrap-metadata": {
        "loadHint": "eager-metadata",
        "runtime": true,
        "sourceFiles": [
          "manifest.json"
        ],
        "caseIds": [
          "metadata-loading"
        ]
      }
    },
    "coverage": {
      "caseCount": 1,
      "modeCount": 1,
      "stagesCovered": 1,
      "allCasesCovered": true,
      "runtimeModeIds": [
        "startup-smoke"
      ],
      "manualReviewModeIds": [
        "startup-smoke"
      ]
    }
  },
  "cases": [
    {
      "id": "metadata-loading",
      "family": "loading",
      "stage": "bootstrap-metadata",
      "trigger": "Metadata is loading.",
      "requiredBehavior": [
        "Keep the base app usable."
      ],
      "mustNot": [],
      "appOwnedCopyIntent": "Use calm, honest copy.",
      "sourceFiles": [
        "manifest.json"
      ]
    }
  ],
  "totals": {
    "cases": 1
  }
}

The schema

Its address is https://openvaluesstandard.org/schema/node-runtime-states-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/node-runtime-states.schema.json.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.