Standardize the runtime graph

.github/workflows/test.yml

@@ -298,7 +298,7 @@ jobs:
       - name: Verify clean wheel boundary and import every shard
         run: |
           env -u PYTHONPATH /tmp/wheels-venv/bin/python -I - <<'PY'
-          from importlib import metadata, util
+          from importlib import metadata, resources, util
           from pathlib import Path
           import sys
 
@@ -307,6 +307,7 @@ jobs:
           import microcosm.data
           import microcosm.fit
           import microcosm.frame
+          import microcosm.graph
 
           assert util.find_spec("policyengine_us") is None
           try:
@@ -323,11 +324,18 @@ jobs:
               microcosm.calibrate,
               microcosm.build,
               microcosm.data,
+              microcosm.graph,
           )
           for module in modules:
               path = Path(module.__file__).resolve()
               assert path.is_relative_to(prefix), f"source import escaped wheel venv: {path}"
               print(module.__name__, module.__version__, path)
+
+          graph_schema = resources.files("microcosm.graph").joinpath("schema")
+          assert sorted(path.name for path in graph_schema.iterdir()) == [
+              "graph-module-v1.schema.json",
+              "graph-source-v1.schema.json",
+          ]
           PY
       - name: Spec identity section digests (cross-environment diffing aid)
         run: env -u PYTHONPATH /tmp/wheels-venv/bin/python -I tools/spec_envelope_digests.py be uk

changelog.d/standardize-runtime-graph.added.md

@@ -0,0 +1 @@
+Added authoritative Graph YAML composition, explicit population-state transitions, graph-bound run manifests, saved-run reconstruction, and post-run local materialization.

docs/graph-acceptance.md

@@ -315,6 +315,22 @@ Amendments so far (each re-locked):
     records the interface amendment for owner review, not a claim of code
     approval or release certification.
 
+20. **Authored runtime graph and named state semantics.** `Graph.products`
+    gives stable names to population states, coordinates, weight states, typed
+    artifacts, validation outcomes, and post-run exports. `SourceRef` declares
+    its content type, access classification, expected content identities, and
+    authoritative decoder. `Node.requires_success` expresses required
+    validation dependencies. `StructuralDelta.REVISION` creates a new
+    unchanged-row population state with declared rewrites, and
+    `StructuralDelta.UNION` combines two or more compatible population states
+    with deterministic identifiers and stored lineage. `WeightTransition.anchor`
+    names the earlier weight state used for ratio and mass validation. Nested
+    parameters are recursively immutable finite JSON values. These declaration
+    changes are serialized losslessly, compiled into dependency order, and
+    included in semantic graph and affected node identities. Adopted by the
+    independently owned `standardize-runtime-graph` child of PR #873 on
+    2026-09-08; the country migrations remain separate changes.
+
 Adding a normative field with a default changes the canonical projection
 of every node that carries it, so node keys moved with amendments 11 and
 13's sibling field `entrants`; no released artifact pins a graph key yet.

docs/graph-explorer.md

@@ -26,15 +26,18 @@ Two invocations with the same code produce byte-identical HTML.
 
 ## Render any saved run
 
-Save both sides of the review contract:
+Use the authoritative YAML root and save the manifest. If the run also emits
+optional Graph JSON evidence, write the versioned generated document:
 
 ```python
 from pathlib import Path
 
-from microcosm.graph import graph_to_json
+from microcosm.graph import graph_document_to_json
 
 manifest.save(Path("run/manifest.json"))
-Path("run/graph.json").write_text(graph_to_json(graph), encoding="utf-8")
+Path("run/graph.json").write_text(
+    graph_document_to_json(graph), encoding="utf-8"
+)
 ```
 
 By default, put the run's `ContentStore` at `run/store`, beside the manifest.
@@ -43,12 +46,14 @@ Then render it with:
 ```bash
 uv run python tools/graph_explain.py \
   --manifest run/manifest.json \
-  --graph run/graph.json \
+  --graph path/to/graph.yaml \
   --out run/explain.html
 ```
 
 If the store is elsewhere, add `--store /path/to/store`. The renderer uses
-`graph_from_json`, compiles the graph again, validates the manifest and every
+the authoritative YAML by default; it also accepts generated versioned Graph
+JSON and older unversioned Graph JSON evidence. It compiles the graph again,
+requires the saved manifest's semantic graph identity to match, validates every
 referenced artifact through `RunManifest.load`, and reloads structural frames
 from each receipt's `frame_key`. A missing or corrupt store is an error, not an
 unverified page.
@@ -76,7 +81,7 @@ not read or write files.
 The large SVG is laid out from `CompiledGraph.order` and `predecessors`.
 Horizontal position is topological depth. Dashed background groups are the
 population versions from `CompiledGraph.versions`, including structural
-`create`, `filter`, `expand`, and `reweight` boundaries.
+`create`, `filter`, `expand`, `reweight`, `revision`, and `union` boundaries.
 
 Every node shows its id, kernel reference, role, structural delta, abbreviated
 node key, and store hit or miss. Blue fill means a store miss and green fill
@@ -174,9 +179,11 @@ downstream node is not executed after the owning boundary rejects the dtype.
 ## Portable evidence boundaries
 
 Portable manifest JSON intentionally omits attached populations and transient
-mass ledgers. Structural frame artifacts let the CLI recover weights, strata,
-and before/after totals, but the current receipt exposes only the realized
-maximum weight ratio, not the distribution's samples or bins. The immediate
-post-run demo therefore carries richer attached evidence than a manifest copied
-without its store. Missing evidence is identified in the page wherever it cannot
-be reconstructed faithfully.
+mass-ledger objects. A matching semantic Graph, manifest, and content store can
+now reconstruct any named population product exactly: structural frame
+artifacts restore row states and ordinary or value-revision column artifacts
+restore later changes. The current HTML renderer attaches structural frames for
+its weight and mass views; it does not embed complete reconstructed data values.
+The current receipt exposes only the realized maximum weight ratio, not the
+distribution's samples or bins. Missing evidence is identified in the page
+wherever it cannot be reconstructed faithfully.

docs/graph-interface.lock

@@ -1,2 +1,2 @@
-8229270f3328f537c8f8e83d6c81af39aa75d4ca5aa6a7bd3d37ecfc25aee2fe  decl.py
-07691fb5cf45ae700a258713ebdc9aa845891a432ec9107e223b8c943b5f3cb6  kernel.py
+16830aab3e480802f086ec00367a08a0bd75e4c823dae3b3e9646207311026be  decl.py
+a078a8e94a900b9405e13f3646d891e0f42c45a2a998ef6937979865ff678036  kernel.py

docs/graph-storage-benchmark.md

@@ -0,0 +1,34 @@
+# Graph value-storage benchmark
+
+This benchmark measures the content-store payloads produced by the synthetic
+US post-transfer parity fixture. The fixture uses the US entity schema and
+executes the US graph kernels over a small, reviewable population.
+
+Run it with:
+
+```shell
+uv run --package microcosm-graph pytest \
+  packages/microcosm-graph/tests/test_acceptance_h_parity.py::test_h3_us_post_transfer_parity
+```
+
+The 2026-09-08 result on `codex/standardize-runtime-graph` is:
+
+| Stored values | Payload bytes |
+|---|---:|
+| Structural frame | 110,180 |
+| Duplicate standalone copies of its coordinates (comparison) | 120,176 |
+| Metadata-only coordinate references (implemented) | 0 |
+| Ordinary value patches retained for reconstruction | 11,221 |
+
+The earlier representation wrote both the 110,180-byte structural frame and
+120,176 bytes of standalone coordinate payloads. The new representation keeps
+the frame once and stores each coordinate artifact key as a checked reference
+to that frame. This removes 52.2% of the structural value payload while
+preserving the coordinate keys used by manifests and investigation tools.
+
+The test constructs the comparison objects from the same values and codec, so
+the measurement includes repeated entity-ID arrays and nullable-value storage.
+It also verifies that ordinary and value-revision outputs remain standalone,
+content-validated patches. Reference loading checks the coordinate identity,
+structural-frame identity, node identity, dtype, length, and entity IDs before
+returning values.

docs/runtime-graph-stack.md

@@ -0,0 +1,84 @@
+# Runtime graph stack ownership and source identity
+
+This document records the development boundary for the
+`standardize-runtime-graph` change. It is an implementation note for the
+stacked pull request, not a second graph specification.
+
+## Stack ownership
+
+The child branch was created from draft PR #873 at commit
+`ee617ea672a7a81b4a86b3c03091a29f084682d4`. Its pull request base is Max
+Ghenis's `model-artifact-graph-20260904` branch. The child branch is
+`codex/standardize-runtime-graph` and its push upstream must be
+`origin/codex/standardize-runtime-graph`.
+
+No push command for this change may name or force-update
+`model-artifact-graph-20260904`. That branch is an immutable dependency of the
+child changes.
+
+When PR #873 changes:
+
+1. fetch `origin/model-artifact-graph-20260904` and record its new commit;
+2. rebase the independently owned child branch onto that commit;
+3. resolve only conflicts in the child changes, leaving upstream conflicts
+   with `main` for PR #873's owner;
+4. update the recorded commit in this document and the child pull request;
+5. rerun typed-artifact characterization and the complete child validation
+   suite; and
+6. push the rebased child branch with a lease that names only
+   `origin/codex/standardize-runtime-graph`.
+
+After PR #873 merges, rebase the child branch onto the resulting `main`
+commit, confirm that the semantic diff relative to #873 is unchanged, rerun
+validation, and change the child pull request base to `main`. The child branch
+remains the only branch that this work pushes.
+
+## Typed-artifact baseline supplied by PR #873
+
+The recorded PR #873 commit supplies the following interfaces:
+
+- `ArtifactType`, `ArtifactInput`, and `ArtifactOutput` declarations;
+- compiler-validated typed byte dependencies between nodes, including nodes
+  attached to different population states;
+- typed input identities in consuming node keys;
+- immutable `ArtifactValue` objects in the kernel context;
+- typed input and output descriptors in node receipts and schema-version 3
+  manifests;
+- content-store loading and integrity verification before a consumer runs;
+- lossless Graph JSON serialization of typed declarations;
+- separate QRF training and application kernels; and
+- stable keyed randomness based on entity identifiers and draw coordinates.
+
+The focused tests in `test_artifact_edges.py`, `test_graph_models.py`, and
+`test_keyed_randomness.py` characterize these behaviors. The runtime-graph
+change builds on those interfaces rather than replacing them.
+
+## Reviewed source identities and runtime content identities
+
+PR #853 defines reviewed identities for the exact file or archive boundary
+named by a source manifest and, where applicable, a Chronicle registration.
+Those reviewed records are repository configuration. The graph runtime must
+refer to them without copying their digest values into graph YAML.
+
+The graph runtime calculates a separate path-independent identity for the
+bytes supplied to a `SourceRef`. A regular file is identified by its complete
+byte sequence. A directory source is identified by the deterministic sequence
+of relative file names and file bytes accepted by its declared codec. The
+calculated identity is an execution fact and is recorded in the run manifest.
+
+The two identities have different purposes and may cover different byte
+boundaries:
+
+| Record | Byte boundary | Authority | Runtime action |
+| --- | --- | --- | --- |
+| Reviewed expected identity | The file, archive, or archive member declared by the source manifest | PR #853 source metadata | Verify before the first consumer runs |
+| Calculated graph identity | The complete file or deterministic directory payload bound to `SourceRef` | `microcosm.graph` source codec | Use in node identity and record in the run manifest |
+| Codec implementation identity | The implementation that decodes the bound payload | Registered graph codec | Use in every consuming node identity |
+
+A source binding therefore records the reviewed expectation and the calculated
+execution identity as distinct fields. If their boundaries are the same, the
+runtime compares the digests directly. If a reviewed archive contains the
+runtime member or extracted directory, the source metadata must declare that
+relationship explicitly; the runtime must not treat unrelated hashes as equal.
+Graph YAML references the reviewed source record by stable identifier and does
+not maintain an independent copy of its digest.