Add country-neutral Orrery execution evidence and UK contracts

[juaristi22]

UK graph exports currently show the declared graph without enough evidence to explain a recorded build or connect it to upstream checkpoints. This builds on #888 by adding country-neutral presentation and execution contracts, then supplying UK metadata and aggregate artifact providers through adapters.

Changes

• Add validated presentation groups, scope boundaries, composite descriptions, and checkpoint references with digests. Preserve the existing graph schema and node IDs.
• Save native run bindings and phase history alongside UK build artifacts. Offline export verifies the matching graph, manifest, source identities, and content store without executing kernels.
• Populate Orrery's Record, Sources, and Activity views with independent execution, cache, and gate outcomes, artifact references, and aggregate calibration and size-search diagnostics. Exclude record-level arrays.
• Preserve immutable upstream checkpoint files and include the final national/dense readback in the saved graph and operation inventory.
• Extend the existing exporter with optional --evidence and --store inputs. Orrery JSON and HTML remain explicit exports; builds save native evidence, not automatic viewer snapshots.
• Allow serialized operation contracts up to 131,072 characters so the maintained UK gate manifests survive schema, native-evidence, and Orrery round trips. Keep the existing document, complexity, node, and edge limits.

Country details enter through presentation metadata and registered artifact-summary providers; the shared schema and execution code do not dispatch on UK-specific names. Detailed value lineage (#865), new visualizer features, and published demonstrations remain separate work.

Validation

• Production declaration export through both spine/full gate batteries, holdout and export preparation: 77 operations, 5,156 presentation nodes, 19,593 edges, accepted by Orrery 0.6.1. The actual 65,971-character full gate contract now round-trips; focused schema, Orrery and UK presentation tests: 45 passed. CI for e0ba98a is pending.

• Prior 10 GitHub Actions checks passed on 383fe76: engine-free, UK, and US suites on Python 3.13 and 3.14; UK integration; lint; wheel packaging; and country-test selection. Each engine-free suite reports 14,892 passed, 140 skipped.

• Registered engine-free suite: 14,888 passed, 142 skipped, with Hugging Face offline mode. Final focused checks after the last changes: executor/evidence 111 passed, dense driver 44 passed, and UK calibration/national evidence 56 passed.

• Ruff, test-plan registration, graph acceptance registry, and diff checks pass. Frozen graph declarations and kernel interfaces are unchanged.

• Orrery 0.6.1 public parser and browser checks cover groups, Record, Sources, Activity, and independent status badges. A synthetic export retains all 22,053 calibration targets; maintained UK dense and size graphs remain within exporter limits.

• A separate online run reproduces an existing live-loader mismatch: uk-2025-national expects a microcosm-uk-2025- release, while the current pointer resolves to microcosm-uk-2024-25-national. The loader and its test are unchanged.

• UK staging smoke integration: 2 passed, including export of the saved native evidence with the full gate declarations. Country-engine suites and a licensed population build were not run locally; UK driver tests use synthetic fixtures.

Closes #1079
Closes #1080

[vahid-ahmadi]

Automated review pass (Claude Code, high effort) — round 1 at 2b5149b4

Verdict: changes needed, for one reason. The last commit changed what the Orrery export puts in metadata.microcosm, and an existing UK test still expects the old shape, so the engine-free lane will fail. The design itself holds up: the shared code is country-neutral, IDs are unchanged and offline export fails closed.

What checks out

• Country neutrality: graph/evidence.py, presentation.py, orrery_evidence.py, orrery.py and calibrate/graph_evidence.py don't name the UK, the FRS or the spine, and test_shared_contract_modules_have_no_country_dispatch_or_imports enforces this. UK labels, groups and summary providers enter only through uk_runtime/orrery_contract.py.

• Node IDs: presentation_id is byte-for-byte the old _id (json.dumps(parts, ensure_ascii=False, separators=(",", ":"))), so existing node and edge IDs don't change.

• Offline export fails closed. It checks:

  • the graph digest and manifest bytes against the binding;
  • every receipt key, re-derived from the declaration and the recorded platform;
  • typed input and output identities;
  • every store object's payload SHA-256 and size (re-hashed in _verified_meta);
  • every evidence file against its index digest, with paths and symlinks kept inside the bundle.

  test_corrupt_evidence_and_store_payloads_fail_closed and test_artifact_producer_metadata_must_match_the_receipt cover the mismatch cases.

• Aggregate-only:

  • raw receipt fields are excluded (test_incomplete_history_is_explicit_and_raw_receipts_are_excluded);
  • the size summary emits counts and ranges instead of IDs, masks and draws, and the dense and size test asserts that household_ids, pool_row_indices and inclusion_probabilities never appear.

• CLI: --evidence and --store must come as a pair. The store is opened read-only (ContentStore(..., create=False)), and without them the export follows the existing static path.

• Upstream checkpoints: copied files are re-hashed before they are written and relinked relatively. Missing bytes are named with their digest rather than linked.

Blocking

1. test_uk_spine_exports_complete_orrery_document fails at this head (packages/microcosm-build/tests/engine_free/uk/test_uk_graph.py:275).
   • The test still asserts document["metadata"]["microcosm"] == schema.
   • 2b5149b4 replaced the embedded transport schema with a bounded summary (orrery.py:183-203).
   • The engine-free lane runs with --maxfail=1, so CI stops there.
   • Fix: assert the summary instead, as test_graph_orrery.py now does: schema_sha256 == sha256(canonical_json(schema)), the counts, and no graph key.

Should

2. Evidence capture can now fail a good build (full_build_cli.py:978, spine_build.py:1914).
   • _persist_checkpoint calls persist_uk_run_evidence on the main path after every phase. It runs the summary providers, and result_summary loads the full saved frame for each result artifact.
   • A provider error would therefore abort a build after a successful solve. Examples are "Conflicting recorded target specifications" (orrery_contract.py:72) and the axis checks in calibrate/graph_evidence.py:160-175.
   • The description says no licensed build was run, so neither the time nor the memory cost at f10/f100 has been measured.
   • Fix: decide whether evidence capture should fail closed or be diagnostic. If diagnostic, record a summary_failed status and carry on. Either way, measure one real rung before merge.
3. Checkpoint paths in the sidecar are absolute (spine_build.py:2048-2062).
   • They're written as str(path.resolve()). A checkpoint built on one machine and used on another therefore always shows "bytes unavailable" in checkpoint_references, even when the evidence travelled with it.
   • The sidecar also records the producing machine's home path.
   • checkpoint_references already resolves relative paths against the sidecar, so record os.path.relpath(path, checkpoint_root) instead.
4. The docs should say how to treat execution exports from licensed runs.
   • Execution exports carry the achieved value for every target (local-area targets included) and the weight minimum, maximum and quantiles (calibrate/graph_evidence.py:20-46, :96-134).
   • That's fine in the private bundle, but docs/orrery-adapter.md:188 calls these plain aggregates. Add a line that an execution export from a licensed run needs the same output clearance as the diagnostics before it's posted publicly.
   • Separately, the result_summary_data docstring says "never ... individual weights", but minimum, maximum, p0 and p100 are individual weights. Reword it.

Nits

5. The string-length increase is global (schema.py:47, orrery.py:63): it applies to every scalar string, not only operation contracts as the description says. Either say so in the description and changelog, or scope it to operation parameters.
6. composite isn't shape-checked (presentation.py:95-99): any value is copied into node data (orrery_evidence.py:43). A small shape check would stop a malformed roster reaching the viewer.
7. spine.graph-declaration.json is written but never referenced (spine_build.py:1911-1912): it goes into checkpoint_root, then graph_declaration_path is repointed at the evidence copy. Drop the first write or reference it.
8. Two writes aren't atomic: save_graph_schema (upstream-*.json) and publish_run_evidence (the flattened copies) use plain write_bytes. Use temp-and-replace, as _atomic_json does.

Tests

• Local run at 2b5149b4: the 12 changed or related test files collect 396 tests. 393 pass and 3 fail:
  • the UK test in item 1;
  • test_public_orrery_parser_accepts_generated_document and test_public_orrery_parser_accepts_groups_and_execution, which need Node. Node isn't installed here, so the local failure says nothing about the PR.
• At the base (de80da34): the new evidence modules don't exist, so the new tests can't pass there.
• CI on this head: all five jobs were still pending.

[vahid-ahmadi]

Automated review pass (Claude Code, high effort) — round 2 at 5fa47f42

Verdict: round 1 is addressed. One small should-fix on the new capture-cost record, then it's good to merge once CI is green.

Three commits on top of 2b5149b4. I copied the updated test files onto 2b5149b4, where 6 new cases fail (the composite shape check ×4, diagnostic provider failure, relative sidecar links). At the head, the five affected suites pass (193; the Orrery parser test needs Node, which I don't have locally), and ruff is clean.

Round 1

#	Item	Status
1	test_uk_graph.py expected the full schema	Fixed: it now checks the digest-bound summary.
2	Evidence capture could fail a good build	Fixed for providers: in-build capture records provider_failed with the error and carries on, while the explicit export stays strict (evidence.py _summaries(strict=False)). Tested. Non-provider failures in capture, such as the 32 MiB evidence cap or publish verification, can still abort a build; that's fine as is.
3	Absolute paths in the spine sidecar	Fixed: graph, manifest, schema and evidence links are relative to the sidecar (spine_build.py _checkpoint_link). The tests resolve them from the sidecar's folder.
4	Disclosure guidance and the weights docstring	Fixed: docs/orrery-adapter.md says licensed-run exports need output clearance before anything public, and the docstring now says the extremes and quantiles are individual weight values.
5	String limit applies to every string	Documented.
6	Composite records not shape-checked	Fixed, with tests (presentation.py).
7	Orphaned spine.graph-declaration.json	Removed; the sidecar now points at the declaration inside the evidence bundle.
8	Non-atomic writes	Fixed: checkpoint bytes and published evidence go through _atomic_bytes.

New

1. Should: the capture-cost numbers are in the wrong unit on Linux, and don't measure capture (full_build_cli.py _record_capture_cost, spine_build.py:~1912-1942).
   • ru_maxrss is kilobytes on Linux and bytes on macOS. The fields are named *_bytes and the log divides by 2**30, so on a Linux build host a 10 GiB peak prints as about 0.01 GiB.
   • It's also the process's lifetime peak, so after a solve the "before" and "after" values will usually be identical, and the record won't show what capture itself costs.
   • Fix: normalise the unit by platform (multiply by 1024 on Linux), and record a measure that reflects capture. For example, take the current RSS before and after (psutil, or /proc/self/statm), or use tracemalloc peak during capture.
   • Smaller point: the jsonl append isn't guarded, so a write error there would fail the build, even though the docstring calls it "a measurement, not a gate". Wrapping it in try/except OSError with a warning would match the intent.
2. Nit: provider error text goes into the export unbounded (evidence.py record["error"] = f"{type(error).__name__}: {error}"). An exception message can carry values from the frame. Truncating it, say to 500 characters, and keeping the type name keeps record-level values out of an export.
3. Nit: an errored summary is cached and reused for later phases without a retry. That's probably intended, but worth a line in the docstring.

CI

Lint, wheels, select-countries, both engine-uk lanes and integration-uk pass. engine-free and engine-us were still running. 5fa47f42 restamps the two spool adoption tests relative to now, so the date-dependent failure that also hits main shouldn't recur here. Main still needs the same fix until this merges.