Skip to content

Put the release contract on paper and freeze C1 and C5 as golden fixtures (M0) - #1285

Merged
MaxGhenis merged 18 commits into
mainfrom
release-contract-m0
Nov 13, 2026
Merged

MaxGhenis merged 18 commits into
mainfrom
release-contract-m0

Conversation

@MaxGhenis

@MaxGhenis MaxGhenis commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Max adopted the ARCH-1 end state on 2026-10-15 (cos d1160). This pull request delivers milestone M0 of the 2026-10-09 systems report's plan to reach it: it puts the release contract on paper, freezes C1 and C5 as golden fixtures, and works through the report's retire-now list. It turns no refusal on and changes neither what publishes nor any published number.

Main now publishes every UK and US build into its own folder, releases/<release>/<build>/, through microcosm-publish-release-build, and records it in the repository's releases.json (#1537 for the UK, #1571 for the US). The document describes that shape as C5 today, and C5 version 1 takes it for every country and line. The fixtures freeze one build folder's manifests for each country's national release, and each repository's releases.json, from the writers a real build calls.

In the end state, publishing refuses non-conforming releases from 2026-11-06. On 2026-11-12 main holds none of the M2 or M3 work that version 1's refusals need, and Max decides when they start. The document's enforcement timeline records what main holds for each milestone.

Closes #378.

What changes

  • docs/release-contract.md (new). It describes main at 6c64038 (2026-11-12) and cites the function that does each piece of work. It covers:

    • the end state, and the releases in service on 2026-10-15;
    • contracts C1 to C5, each as main enforces it today and each one's version 1;
    • C5 today, where both countries' releases publish into build folders and the latest*.json pointer files survive as read-only legacy, and C5 version 1, which takes that shape for every country and line and names the gaps main still has;
    • how C1 version 1 dispatches on the manifest's declared country instead of the release name, with the bump to release manifest schema 2 as the trigger;
    • what each kind of derived build (annual projection, source enrichment, compatibility recertification) ships today, and what version 1 asks of it;
    • Build K epic: transactional country executor via strangler extraction from the US release monolith #378's parity rule, the enforcement timeline, the golden fixtures and the retire list.

    It replaces docs/us-uk-release-path.md, a planning snapshot that never reached main.

  • tools/assemble_uk_release_dir.py. The two manifest dictionaries move into uk_national_release_manifests, a pure function of its inputs, and the list of the six evidence files into the module constant _EVIDENCE. _stage_and_finalize keeps main's signature: it calls the function, writes both documents with _write_json and copies the evidence. The assembler writes the same bytes as main's. A scratch test ran main's assembler and this branch's on main's green fixture with a fixed clock, once with an SPI-dependent stage and once without. Both runs gave the same release directory (the two manifests and the six evidence files), calibration NPZ and printed summary, byte for byte.

  • tools/generate_release_contract_fixtures.py writes the golden fixtures under packages/microcosm-data/tests/fixtures/release_contract/v1/. Each golden comes from the writer that produces the same file in a real build:

    File Writer
    c1/microcosm-uk-2024-25-national/build_manifest.json and release_manifest.json uk_national_release_manifests, then _write_json, in the UK assembler
    c1/microcosm-us-2024-national/build_manifest.json and release_manifest.json _build_manifests, then _finish_build_folder_release, in the US fiscal-refresh builder; the second calls microcosm.data.build_folder_manifests.rewrite_release_dir
    c5/uk/releases.json and c5/us/releases.json the emitter interface's add_build (a publication) and make_current (a promotion), then dataclasses.replace to set default, then ReleasesRecord.serialize
    c1/inventory.json the generator's _c1_inventory, from the constants of microcosm.data.contract
    c5/registry.json the generator's _c5_registry, a snapshot of REGISTRY
    writers.json the generator's _writers

    writers.json names these writers for every file SHA256SUMS lists, and SHA256SUMS pins every byte. --check regenerates into a temporary folder and fails, naming each file that differs.

    • The interface has no function that sets default, so the generator takes the step build_folder_switch._switch_record takes: dataclasses.replace. Both records name the national release as the default.
    • The UK writer needs no seam, since the clock, the runtime versions and each certification part's census arrive as arguments. For the US builder, the generator replaces four module globals and nothing else: _runtime_versions, _git_output, datetime (a fixed clock) and _release_gate_failures. The last returns no failures, so the US golden records a passing calibration gate.
    • Each golden holds its two manifests and no other file. The UK golden leaves out the dataset, the weights and the six evidence files. Among those, the signed certification and the gate reports carry the live UK gate-spec digests, and UK November event data, PR3: the carer link, the severe disability flag and part B (#1095) #1583 moved five of those digest literals in contract.py. The US golden leaves out the dataset, the weights, calibration_diagnostics.json, us_source_coverage.json, us_ssi_take_up.json and the stored-input verdict, which carries a digest of the live stored-column register. No fixture holds a signed certification or a pointer file.
    • The US golden holds what _build_manifests writes when it gets only its required arguments and a staging block, in the layout rewrite_release_dir gives it. Its build manifest carries an empty timing, a null ledger_artifact and only the four gate entries that the function always writes. It embeds the live constants the builder writes into every build: the gate-evidence keys (US_RELEASE_GATE_EVIDENCE_FILES), the documented-absent inputs (US_DOCUMENTED_ABSENT_INPUTS), the calibration diagnostics' schema version, and the dataset and calibration file names. A real build adds its timing, the ledger artifact's provenance and its optional gate blocks, and the golden freezes none of them. A pull request that changes what _build_manifests always writes, one of those constants or rewrite_release_dir's layout regenerates the fixtures.
  • uk_runtime/release_identity.py drops format_uk_release_id, UKReleaseIdentity and apply_uk_release_identity, and uk_runtime drops their re-export. On main, none has a caller outside their own module, their tests and that re-export, and GitHub code search across the PolicyEngine organization's default branches finds them nowhere else. The tier vocabulary and the two constant UK release names stay, and the contract still validates existing exact-k ids.

  • README.md and docs/agent-guide.md point to the document, and two changelog fragments record what this pull request adds and removes.

Invariants the tests hold

  • Freeze. tools/generate_release_contract_fixtures.py --check reproduces every committed byte and fails on any difference (test_release_contract_fixtures_are_reproducible). SHA256SUMS lists every fixture file and no other, and each digest matches its file (test_every_fixture_byte_is_pinned_by_sha256sums).
  • Each golden names its writer. writers.json names a writer for every file SHA256SUMS lists and for no other, and no golden names the generator among its writers (test_writers_json_names_a_writer_for_exactly_the_pinned_files). Every writer it names exists (test_every_writer_the_fixtures_name_exists). The real build paths still call those writers: the UK assembler's _stage_and_finalize calls the pure function and _write_json, the US builder's _main calls _build_manifests and _finish_build_folder_release, and that function calls rewrite_release_dir (test_each_manifest_golden_names_the_writers_its_real_build_calls).
  • No signed certification. No fixture file takes the certification's file name or kind, and no fixture document carries an attestation or a signature key at any depth (test_no_fixture_holds_a_signed_certification).
  • C1, the goldens. For both countries, _check_build_manifest, _check_release_manifest and the cross-manifest check return no failure (test_golden_manifests_pass_the_manifest_checks_directly). Both manifests name the release and the same build as two strings, carry none of RETIRED_BUILD_FIELDS, and give each artifact its role and no revision (test_golden_manifests_have_the_build_folder_layout).
  • C1, the refusals the omissions cause. validate_release_dir refuses the UK golden for its two missing required files, calibration_diagnostics.json and release_certification.json, and nothing else (test_uk_national_golden_is_refused_only_for_the_files_it_omits). It refuses the US golden for five things and nothing else: the missing calibration_diagnostics.json and us_source_coverage.json, each manifest's not_evaluated stored-input entry, and the stored-input artifact the release manifest lacks (test_us_national_golden_is_refused_only_for_the_files_it_omits).
  • C1, gates and inventory. The UK build manifest copies each certification part's census (test_uk_national_gates_are_the_certifications_part_censuses). The US build manifest records a calibration gate that passed with no failures, and every gate-evidence entry in both US manifests reads not_evaluated (test_us_national_golden_records_a_passing_calibration_gate). inventory.json equals the live contract's constants (test_inventory_matches_the_live_contract) and lists the files the UK manifests ship and no others (test_inventory_files_are_the_files_the_manifests_ship).
  • C1 over generated inputs. On up to 60 generated valid inputs each run, a Hypothesis property checks that the two manifests uk_national_release_manifests returns pass the contract's manifest checks and name the national release and one build. They give every artifact its role and no revision, and ship the signed evidence as their only diagnostics. After one publication and one promotion, the loader selects the build through releases.json inside its own folder, at no revision, with the digest and package versions the inputs gave. The manifests also restate the SPI Public Use Tape marker, copy each part's census, and depend on the inputs alone, key order included (test_national_manifests_satisfy_the_release_contract).
  • Golden shape against a real assembly. A real assembly's manifests match the UK golden key for key and type for type, and its directory holds the inventory's files and no others (test_assembled_release_has_the_release_contract_golden_shape).
  • C5, producer against consumer. Each releases.json equals the emitter interface's serialization of one publication and one promotion, default apart, and this repository's reader parses the same record (test_each_releases_record_is_the_interface_writers_serialization). Each lists the C1 golden build as its release's current build, gives the release the role its manifest's dataset_role maps to, and names it as the default (test_releases_record_lists_the_golden_build_as_its_releases_current_build). The loader selects each golden build through its record (test_loader_selects_each_golden_build_through_its_releases_record) and refuses it under the other role (test_loader_refuses_a_golden_build_under_the_other_role). registry.json equals REGISTRY (test_registry_snapshot_matches_the_live_registry).
  • Executable gap pins. test_release_contract_keying.py pins today's name-keyed contract, which C1 version 1 replaces at M3. An unlisted name gets the base file set and no model package, and the US requirements apply to the five names in US_RELEASES and to the populace-us- prefix. publishes_to_build_folder admits the UK national and dense releases, any microcosm-uk-2024-25-local-k<N> and the five US releases, and no unlisted name; the local-k case pins the gap Admit a UK local-area release to build folders only when the registry names its k #1586 tracks. In one test, a release that validates under microcosm-nz-2025-national fails under a populace-us- name with nothing else changed.
  • Retired helpers. Neither release_identity nor uk_runtime exports any of the three helpers (test_exact_k_id_minting_is_retired).

Gaps the document names

C5 version 1 and the other contracts list what main still lacks on 2026-11-12:

  • A new country's tagged publish. Nothing refuses it, and M3's refusal of unknown countries closes the gap. The tagged publisher (microcosm-publish-release and tools/publish_release.sh) joins the retire list and leaves once that refusal lands.
  • NZ, AM and BE. Each country's release_contract.json names latest.json, and each country's owner changes its file before that country's first publication.
  • UK local-area releases. Version 1 names a release microcosm-uk-2024-25-local-k<N> for each N the registry names, and the pull request that authorizes a k's first publication adds its registry entry. Today publishes_to_build_folder admits every positive N through _UK_LOCAL_LINE_RELEASE_ID_RE, while the registry names no UK local-area release. Admit a UK local-area release to build folders only when the registry names its k #1586 tracks the fix, under which the function admits a local-area release only when the registry names its k.
  • Pointer readers. The loader's fallback (latest_release, latest_line_release) and latest_evidence_release still resolve through latest*.json, and the plan names no owner or milestone for removing them.
  • The UK cut runner. tools/run_uk_cut.py still builds the tagged publisher's arguments for the UK national release, which prepare_release refuses. Moving it to microcosm-publish-release-build falls to the UK cut's owner.
  • policyengine.py. At 5b6d7901c (2026-11-11), its bundle pins builds by tag, and version 1 pins each by release and build. C2 version 1's rules have no case for its qualified_exact_pair basis, and M2 settles whether version 1 names that basis or policyengine.py drops it.
  • The default release. The loader takes each country's default from the registry, and no check at publication confirms that releases.json's default agrees with it.
  • The registry. It has no entry for microcosm-us-2024-local (M2) or for any UK local-area release.
  • C2. _check_local_area_release_manifest checks no compatible-package list on local-area and dense builds, and C2 version 1 adds that check at M2 (owner: anth-volk). The recertification lane (Recertify a published US release for a newer policyengine-us without a rebuild #1366) writes entries that C2 version 1's rules 2 and 3 refuse. Once RELEASE_MANIFEST_SCHEMA_VERSION becomes 2, no source enrichment and no recertification of a schema-1 parent passes its lane's validator. The plan does not yet say whether the rules exempt those lanes or the lanes change.
  • Derived builds. microcosm-publish-release-build has no C3 or C4 rule for a derived build. At M3, version 1 adds the refusal: a derived build carries a pinned reference to its parent and its own step's outcome record, and no staging or Logbook record that another run wrote.
  • The UK dense line. It ships its gate report, uk_local_gates.json, and no release_certification.json. The plan does not yet say whether that report counts as the dense line's certification.
  • The evidence release. Version 1 neither admits microcosm-us-2024-evidence to the contract nor retires it, and the retire list names it as an exception.

Merges with main

Retire list

The document's table records each retire-now item of the 2026-10-09 report as GitHub and main showed it on 2026-10-15, and what a second reading found on 2026-11-11:

Tests

On 2026-11-12, at 06407f2 (this branch with main 6c64038 merged), unless an item says otherwise:

  • One pytest process over this branch's five test files and main's test_release.py, test_loader.py, test_registry.py and test_uk_release_publication.py: 401 passed and 2 skipped of 403. Both skips come from main's live-Hub test, which needs credentials. This branch's five files hold 106 of those tests, and all of them pass.
  • tools/generate_release_contract_fixtures.py --check exits 0 three times, with nothing regenerated.
  • tools/ci_test_plan.py verify reports ok for 942 test files.
  • ruff check and ruff format --check pass on the nine Python files this branch changes.
  • Mutation checks ran before the merge of 6c64038, in scratch copies with the committed fixtures in place, and that merge changed none of the code they mutate. Each of these nine single changes makes --check exit 1:
    • a UK manifest key, built_at or publisher_labels, and the UK description's wording;
    • rewrite_release_dir's artifact key role, and its indent;
    • the US national release's role in US_RELEASES, and the role the interface's add_build records;
    • the US registry entry's build_folder_filename;
    • the removal of the generator's _release_gate_failures seam.
  • The three commits after 06407f2 (1fc1f97, e3cff13 and f1a456a) change only Markdown files and one module docstring. At e3cff13, test_ci_integration_job.py -k agent_entrypoints, the one test that reads docs/agent-guide.md, passes, and at f1a456a --check exits 0 again.
  • All 12 CI checks pass on f1a456a, the seven that main's ruleset requires among them.
  • Report each QRF output's largest single record in the US tail-concentration evidence #1268 and Name the build for the collector in UK staged-bundle hand-overs #1588 landed on main (89e12fb) after that CI run started. Git merges this branch with that main without conflict, and all 106 tests in this branch's five files pass on the merged tree.

Review

An independent review of the code, fixtures and tests made 18 single changes to the fixture writers, their serializers, the live constants they embed and the generator, and --check failed on each. It then broke what each of 27 test checks guards, one check at a time, and each of those tests failed. A second review opened the code behind 57 of the document's mechanism sentences and behind the eight sentences an earlier review had found unsupported, and each one held. A third review checked every sentence that the two later wording commits (e3cff13 and f1a456a) changed against the code, and found each one supported.

axiom: n/a: release contract documentation and fixtures; no policy rule changes.

🤖 Generated with Claude Code

MaxGhenis and others added 4 commits October 15, 2026 06:01
Extract the UK national assembler's two manifest documents into
uk_national_release_manifests, a pure function the assembler and the new
golden generator both call (byte-for-byte unchanged output, checked against
the previous assembler on the green fixture).

tools/generate_release_contract_fixtures.py writes version 1 of the release
contract's golden fixtures, following the staging-fixture pattern: the UK
national line's build and release manifests (C1), an inventory of the files
and certification fields the contract requires of that line, the two pointer
payloads the publisher writes and a registry snapshot (C5), with SHA256SUMS.
--check regenerates and compares bytes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs/release-contract.md states the ARCH-1 end state Max ruled on
2026-10-15 (d1160), what is served today, and contracts C1 to C5: what the
code enforces now, cited to the function that does it, and what it will
enforce from 2026-11-06. It says how C1 keys by declared country instead of
release-id strings, carries microcosm#378's parity rule, documents the
golden fixtures, and records the retire list's state. It replaces the
branch-only docs/us-uk-release-path.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The data shard holds every fixture byte to SHA256SUMS and proves each file is
what the contract's own code accepts or writes: the C1 manifests pass every
release-contract check except the two files the fixture omits on purpose, the
loader selects the national artifact from them through the registry, the
inventory equals the live constants, both pointers equal the publisher's
payloads and read back, and the registry snapshot equals the registry.

test_release_contract_keying.py turns the C1 keying gap into executable
statements, including that the same release bytes validate under an NZ id
and fail under a US id. The build shard checks the generator reproduces the
fixtures, and a property test holds uk_national_release_manifests to the
contract for every valid input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
format_uk_release_id, UKReleaseIdentity and apply_uk_release_identity minted
populace-uk-<year>-<tier>-k<N> ids and had no caller outside their own tests
and the uk_runtime re-export. The 10-09 systems report listed the two
functions as retire-now; UKReleaseIdentity goes with them because it is
built on format_uk_release_id and is equally unused. New releases take their
id from C1's declared identity (docs/release-contract.md).

The module keeps the national and dense line ids and the tier vocabulary,
which the release assemblers and input-coverage checks import. The contract
still validates existing exact-k ids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis and others added 3 commits October 15, 2026 06:13
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add changelog fragments for the contract, its fixtures and the retired UK
id-minting helpers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis
MaxGhenis marked this pull request as ready for review October 15, 2026 10:16
- The C1 golden's gates now carry each certification part's status census
  ({"passed": N}), the shape the certifier writes and the contract requires;
  the property strategy draws the same shape, and a new assembler test holds
  a real assembly's manifests and directory to the golden key for key.
- uk_national_release_manifests copies runtime instead of aliasing it, and
  the property compares serialized bytes so key order is covered.
- docs/release-contract.md: correct the US Logbook writers; qualify the
  model-package checks by id; describe the source-enrichment compatibility
  rule and make C2 v1 generalize it (Core pinned exactly, claims bounded,
  PEP 440 equality, first matching claim); grandfather by published
  revision, not id; route every id-keyed check and the pointer readers
  through the declared country; keep remote staging delivery required with a
  re-delivery path and move the gate into prepare_release; ship the staging
  terminal document and Logbook row in the release directory; smaller
  wording fixes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis

Copy link
Copy Markdown
Contributor Author

Opus 5.5 review of c2d50d8: REQUEST_CHANGES (0 blockers, 3 majors, 16 minors and nits). All 19 are addressed at 47389ec.

Majors:

  1. US Logbook writers. The doc wrongly listed tools/us_bundle_generation/core.py as a writer; it only reads and verifies logbook/us.jsonl. Corrected.
  2. Required lists. The "whatever the id" list overstated the compatible_model_packages requirement for ids the contract does not recognise. Now qualified.
  3. gates shape. The C1 golden carried a gates shape the national line never ships: a map from gate id to status, where the certifier writes a status census, {"passed": N}. Fixed in the generator and the property strategy. A new assembler test, test_assembled_release_has_the_release_contract_golden_shape, now holds a real assembly to the golden key for key and type for type, and holds its directory to the inventory's file list.

Design points, now settled in the doc:

  • C2 v1 generalizes the source-enrichment rule. Core stays exactly pinned, claims are bounded, admission uses PEP 440 equality, and the basis is attributed to the first matching claim.
  • Grandfathering is by published (release id, revision), not by id alone, because the UK lines keep constant ids across cuts.
  • Every id-keyed check (about 35 sites) and the pointer readers move to the declared country.
  • Remote staging delivery stays required as the pre-publication review, with a re-delivery path so an outage doesn't force a rebuild. The delivery gate moves into prepare_release.
  • The staging terminal document and the Logbook row ship inside the release directory, because the publisher can't see the build host.

Also: runtime is now copied rather than aliased, and the determinism property compares serialized bytes.

Local runs: 67 tests pass across the touched files, and generate_release_contract_fixtures.py --check passes. The review is at _reviews/microcosm-1285/opus-review-c2d50d8.md.

The independent GPT-6.1 Sol review is re-queued on 47389ec (Subfleet job 20261015-063645-m0-1285-review-b) and starts when the Codex lanes reopen, about 14:53Z. It will check each of these fixes and then review independently.

The live-tree guard (test_no_incumbent_data_package_references_in_live_tree)
refuses the retired package's full name outside frozen references; the
contract document is live text, not a frozen reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis and others added 5 commits November 3, 2026 07:55
Brings in main at 4a36edc. One conflict, in
tools/assemble_uk_release_dir.py: main's SPI Public Use Tape marker
(49c4bcb) edited the manifest construction this branch moves into
uk_national_release_manifests. The pure function now takes spi_marker and
writes main's two additions, the microdata entry's
spi_public_use_tape_dependent flag and licensed_data, in main's key order;
_stage_and_finalize passes the marker through.

Two main changes reach the release-contract fixtures and tests:

- The SPI marker changes what the national assembler writes, so the
  generator passes a marker built by uk_spi_public_use_tape_marker from one
  synthetic stage that reads the tape, and the C1 release_manifest.json
  golden gains the flag and licensed_data.
- microcosm#823 (003dbd0) made the national line the UK 2025 default
  load: its registry key is ("uk", 2025, "compact") now, not
  ("uk", 2025, "national"). The C5 registry.json snapshot is regenerated, and
  the three tests that looked the spec up by the old key use
  DEFAULT_VARIANT, as main's own assembler test does.

The Hypothesis property draws the marker and checks that the manifest
restates it. The golden-shape test no longer treats a list's length as
shape, because the golden's marker names one stage and an assembly from
the packaged spec names every stage that reads the tape.

inventory.json, build_manifest.json and both pointer payloads regenerate
byte for byte. same_edit.py flags no identical edit on both sides.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… findings

docs/release-contract.md now reads each "today" statement from origin/main
4a36edc and states each version-1 requirement as the plan's, with a dated
column for how far each milestone had got. When refusal starts stays Max's
call.

Sol's review of fda37a7:
- 1: rules 2 and 3 tighten the validator for calibration releases; rule 4
  tightens both loaders.
- 2: C2 v1 rule 6 keeps today's rule for schema-1 manifests in both loaders.
- 3: the certification needs every scoped gate passed, shippable: true and
  the full-spec digests; one HMAC covers the whole document.
- 4: the failed-diagnostics exception, in the validator and the pointers.
- 5: an exact pin compares Version(V) == Version(built).
- 6: present-tense M3 wording in agent-guide.md, README.md, both changelog
  fragments, release_identity.py and two test docstrings.
- 7: the re-delivery command writes staging_redelivery.json and never
  rewrites the build manifest.
- 8: the producer copies its Logbook row when record_build_attempt returns.
- 9: the dense line's signed verdict is uk_local_gates.json; whether it
  composes a certification stays open.
- 10: the publish order names publish_cli's gates and
  require_parent_publication.

Main moved under the document: the compatibility_recertification release
type (#1366), the emitter behind microcosm-emitter-interface with the
staging hand-over (#1410), and the UK registry flip (#1432). The document
covers each and records one new open item: the recertification lane writes
two entries that C2 v1 rules 2 and 3, as written, refuse.

The retire list's #873 row records that #873 closed unmerged later on
2026-10-15. The prose uses active voice throughout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main moved the UK releases (#1537) and every US build (#1571) to build
folders, releases/<release>/<build>/, published through the emitter and
recorded in releases.json.

One conflict, tools/assemble_uk_release_dir.py. Both sides rewrote the
manifest-writing part of _stage_and_finalize: main gave both manifests the
build-folder shape (release and build as two strings, the build's details
at the release manifest's top level, a role and no revision on each
artifact, score_vs_reference.json) and deleted the cut tag; this branch had
extracted the manifests into the pure uk_national_release_manifests.

Resolution: take main's file whole, then extract again. The pure function
holds main's two documents and takes no cut_tag, _EVIDENCE lists the six
evidence files with score_vs_reference last, and _stage_and_finalize keeps
main's signature, calls the function and copies the evidence from a dict
keyed like _EVIDENCE.

A scratch test ran main's assembler and this one on main's green fixture
with a fixed clock, with and without an SPI-dependent stage: the eight
release files, the NPZ and stdout match byte for byte.

The golden fixtures, their generator and the tests that read them still
describe the tagged shape after this commit; the next commit restates
them, so tests that read them fail between the two.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Main at 27e305d publishes every UK and US build into its own folder,
releases/<release>/<build>/, and records it in releases.json (#1537,
#1571). The goldens this branch froze at a2cc084 held the tagged layout
and two pointer files, and the merged contract's manifest checks refuse the
UK pair 26 times.

The generator, tools/generate_release_contract_fixtures.py, now writes
these files under
packages/microcosm-data/tests/fixtures/release_contract/v1, each with the
writer a real build uses:

- c1/microcosm-uk-2024-25-national/{build,release}_manifest.json:
  uk_national_release_manifests and _write_json, in the UK assembler.
- c1/microcosm-us-2024-national/{build,release}_manifest.json:
  _build_manifests and _finish_build_folder_release, in the US builder.
  The second calls rewrite_release_dir, in
  microcosm.data.build_folder_manifests, whose serialization the fixture
  freezes.
- c1/inventory.json: what the contract requires of the UK national
  release, now with the releases.json role, the build-folder flag and the
  retired build fields.
- c5/uk/releases.json and c5/us/releases.json: the emitter interface's
  add_build (a publication), make_current (a promotion) and
  ReleasesRecord.serialize. The interface sets no default, so the generator
  sets it with dataclasses.replace, as build_folder_switch._switch_record
  does; both records name the national release.
- c5/registry.json: the registry snapshot, whose entries now carry release
  and build_folder_filename.
- writers.json: the writer of every file SHA256SUMS lists, as module and
  function. The release owner asked that each golden name the writer whose
  bytes it freezes.

The generator drops c5/latest.json and c5/latest-national.json. The tagged
publisher, which writes pointer files, refuses every build-folder release,
and main's own tests cover the pointer reader that remains.

Seams. The UK writer is a pure function and needs none. The US builder
reads the clock, the checkout and the installed packages through module
globals and computes the calibration gate itself, so the generator replaces
four globals of the builder's module: _runtime_versions, _git_output,
datetime and _release_gate_failures. The last returns no failures: the US
golden records a passing calibration gate, as the UK inputs give each
certification part a passing census. A scratch copy without that seam, given
one synthetic diagnostic row, wrote a failed gate with 19 sentences, 18 of
them naming critical fiscal targets, so the golden would move with that
list.

What the goldens omit. No fixture holds a signed certification, a gate
report, calibration diagnostics, a source-coverage file or a stored-input
verdict: those bind digests of live registers. The tests pin the refusals
each omission causes, two for the UK folder and five for the US folder.

The US manifests carry live values on purpose: the builder's layout, the
gate-evidence keys (US_RELEASE_GATE_EVIDENCE_FILES), the documented-absent
inputs (US_DOCUMENTED_ABSENT_INPUTS), the calibration diagnostics' schema
version, and the dataset, calibration and repository names. A pull request
that changes one of them regenerates the fixtures.

Tests.

- test_release_contract_fixtures.py (data shard; it imports only
  microcosm.data): SHA256SUMS pins every byte; writers.json covers exactly
  the pinned files and no golden names the generator as its writer; no
  fixture holds a certification, an attestation or a signature; both pairs
  of manifests pass the manifest checks, have the build-folder layout, and
  draw exactly the refusals their omitted files cause; each releases.json
  lists the golden build as the national release's current build; the
  loader selects each build through its record's entry and refuses it under
  the other role.
- test_release_contract_keying.py: the US release names form a closed list
  of five, the US requirements key on those names and on the populace-us-
  prefix, and an unlisted name publishes into no build folder. It no longer
  pins line_pointer_payload, which nothing under packages/*/src or tools
  calls; main's test_release.py and test_loader.py still test that helper.
- test_release_contract_fixture_generation.py (build shard): --check
  reproduces the bytes; every writer writers.json names exists, and the real
  build paths call them; each releases.json equals the interface's
  serialization of one publication and one promotion, default apart; and
  the Hypothesis property now states the build-folder invariant for the UK
  assembler's manifests, loader selection through releases.json included.

Run on 2026-11-12, one pytest process over these three files, the two UK
files this branch also touches, and main's test_release.py, test_loader.py,
test_registry.py and test_uk_release_publication.py: 401 passed and 2
skipped (main's live-Hub test, which lacks credentials here). --check
passed twice in a row.

Mutation checks, in scratch copies with the committed fixtures left as they
are. Each of these makes --check exit 1 and name the file it moves:

- a key of the UK pure function, built_at or publisher_labels (the UK
  release manifest; the assembler's golden-shape test fails too);
- the UK description's wording (the UK release manifest; --check alone);
- rewrite_release_dir's artifact key role, and its indent (the US
  manifests; --check alone);
- the US national release's role in contract.US_RELEASES (the US
  releases.json; the record test and the closed-list test fail too);
- the role the interface's add_build records, in a scratch copy of the
  interface (both releases.json; the serialization test fails too);
- the US registry entry's build_folder_filename (registry.json; the
  snapshot test and the loader test fail too).

Regenerating with each mutant and reading the result with the data shard's
tests fails the manifest, record or loader tests for the five changes a
contract check reads, and passes for the other three: the description, the
publisher_labels key and the indent.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
release_identity.py's docstring, the retired-helpers test's docstring and
the two changelog fragments described releases the way the tagged layout
worked: one constant id "across cuts", and a version 1 that "derives a new
release's id".

Main publishes each build into its own folder under a constant release
name, and the release owner ruled on 2026-11-11 that version 1 names
releases microcosm-<country>-<vintage>-<line> and fixes no grammar for a
build's name. The texts now say that:

- release_identity.py: the national and dense releases each keep one
  constant name, and each of their builds publishes into its own folder
  under it; version 1 renders a new release's name from the identity its
  manifest declares.
- test_uk_release_identity.py: the same sentence in the retired-helpers
  test's docstring. No code changes in either file.
- changelog.d/1285-release-contract.added.md: the document describes the
  code on 2026-11-11, C5 version 1 takes the build-folder shape, and the
  fixture list names what the generator freezes now (UK and US build-folder
  manifests, the inventory, one releases.json for each repository, the
  registry snapshot, writers.json, SHA256SUMS).
- changelog.d/1285-uk-exact-k-id-minting.removed.md: "renders a new
  release's name" in place of "derives a new release's id".

None of these texts says that a pointer file, a cut tag or
latest-<line>.json publishes a release.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
MaxGhenis and others added 4 commits November 12, 2026 09:52
Main moved 58 commits past 27e305d, the main this branch last merged:
#1579 (NZ walk pins), #1553 (review follow-ups), #1311 (ACS local
artifact writer binding) and #1583 (UK event data, PR3). They change 136
files, and this branch changes none of them, so git merged without a
conflict: the tree takes each of main's files whole and keeps this
branch's 24 files byte for byte.

Two of main's changed files feed the fixture writers.
microcosm.data.contract moves five SHA-256 literals (the UK gate
battery's policy, gates manifest and spec fingerprint, and the release-cut
part's two digests), and tools/build_us_fiscal_refresh_release.py rewords
one entry of US_EXPORT_INPUT_MASS_REVIEWED_EXCLUSIONS. No golden reads
either, so no fixture byte moves:
tools/generate_release_contract_fixtures.py --check passes on the merged
tree, with nothing regenerated.

On the merged tree, one pytest process over this branch's five test files
and main's release, loader, registry and releases-record tests gives 401
passed and 2 skipped (main's live-Hub test, which needs credentials), the
counts the branch had before the merge. tools/ci_test_plan.py verify
reports ok for 942 test files, and ruff passes on the Python files this
branch changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ures

- docs/release-contract.md describes main at 6c64038 (2026-11-12):
  every UK and US release that publishes_to_build_folder names publishes
  into build folders and releases.json, and C5 version 1 takes that shape.
  No behaviour the document cites changed between 27e305d and 6c64038.
- C5 version 1 names a UK local-area release
  microcosm-uk-2024-25-local-k<N> for each N the registry names; the pull
  request that authorizes a k's first publication adds its registry entry.
  A new gap records that publishes_to_build_folder admits every N through
  _UK_LOCAL_LINE_RELEASE_ID_RE today (microcosm#1586).
- The golden-fixtures section describes the committed generator: the ten
  files and the writers writers.json names, the four globals it replaces
  in the US builder, what each golden omits and the refusals its test
  pins, the tests, and what forces a regeneration.
- README.md and docs/agent-guide.md say what the release validator, the
  publication commands and the loaders enforce today; the guide adds that
  a change to the US builder's manifest layout or its two embedded
  constants regenerates the fixtures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The US national golden holds what `_build_manifests` writes for the
generator's call, which passes only the function's required arguments and
a staging block. A real build's `_main` also passes its timing, the ledger
artifact's provenance and its optional gate results, which the golden does
not freeze. Sentences in three places said the golden froze what the tool
writes for every build, or a real build's bytes; they now say this:

- docs/agent-guide.md, "The PR-CI / certification boundary": the golden
  freezes the manifests `_build_manifests` writes when it gets only its
  required arguments and a staging block (an empty `timing`, a null
  `ledger_artifact` and the four gate entries it always writes); a real
  build adds blocks the golden does not freeze; a change to what
  `_build_manifests` always writes, such as `US_RELEASE_GATE_EVIDENCE_FILES`
  or `US_DOCUMENTED_ABSENT_INPUTS`, or to the layout `rewrite_release_dir`
  gives it, regenerates the fixtures.
- docs/release-contract.md, C1 "The frozen shape": the US golden freezes
  the manifests for a run that passes `_build_manifests` only its required
  arguments and a staging block, and a real build adds blocks it does not
  freeze.
- docs/release-contract.md, "Golden fixtures": each golden holds its
  writer's bytes for the generator's synthetic inputs; the list of live
  constants the builder writes into every build no longer holds the
  defaults, which a new paragraph gives as what the generator's call
  produces, beside what a real `_main` adds; the regeneration bullet names
  what the US builder writes for the generator's call and says a change to
  a block only a real build produces leaves `--check` green.

The other changes:

- docs/release-contract.md, M3 row: `required_release_files` names
  `release_certification.json` for `microcosm-uk-2024-25-national` alone,
  and C1's other certification rule keys on the gate files a directory
  carries, not on a declared country.
- docs/release-contract.md, the UK local-area gap: Max's session owns
  microcosm#1586's change as a code pull request.
- docs/release-contract.md, the tests: on up to 60 generated inputs each
  run, the Hypothesis property checks that for any valid input
  `uk_national_release_manifests` meets the contract.
- docs/release-contract.md, opening: the document read main's 6c64038.
- changelog.d/1285-release-contract.added.md: the document states each
  contract as the code enforces it on 2026-11-12, and `writers.json` names
  the writer of every file `SHA256SUMS` lists.

Wording only: no code, test or fixture changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The module docstring said writers.json names a writer "for every fixture
file" and that the US manifests carry what the US builder writes "into
every build". writers.json names the files SHA256SUMS lists. The US
golden holds what _build_manifests writes for this generator's call,
which passes only the required arguments and a staging block; a real
build also writes its timing, its ledger provenance and its optional gate
blocks, and the fixtures freeze none of those.

Docstring only: the module's syntax tree with docstrings stripped is
unchanged, and --check still passes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@MaxGhenis
MaxGhenis merged commit 7b93dae into main Nov 13, 2026
12 checks passed
@MaxGhenis

Copy link
Copy Markdown
Contributor Author

This landed as 7b93dae on 2026-11-13 at 11:55 UTC, at the reviewed head f1a456a. Main's tree equals the tree git computes for merging f1a456a into 89e12fb (4c77e1d96), and #378 closed with it.

Main gained #1588 after the last CI run here. On the tree merged with it, all 106 tests in this branch's five files pass.

The last review left two wording nits. docs/agent-guide.md and the generator's docstring name three things a real US build adds beyond the golden: its timing, its ledger provenance and its optional gate blocks. A real build also adds optional receipts (base_pool and post_export_scoring, for example) and the blocks its gate-evidence files bind. The agent guide's sentence also leaves out the four builder globals that the generator replaces. The pull request for #1586 will carry both fixes.

@MaxGhenis
MaxGhenis deleted the release-contract-m0 branch November 13, 2026 11:55
MaxGhenis added a commit that referenced this pull request Nov 13, 2026
Main moved 122 commits past 27e305d, among them #1311 (the ACS local
artifact's writer binding) and #1285 (the release contract). Git merged
every file with no conflict. Three files changed on both sides:
README.md, tools/build_us_acs_local_release.py and its test.

Checks on the merged tree:
- For each of the PR's 25 files, the added and removed lines against main
  match those of 27e305d..9761bb8, and for each of main's 231 files
  they match those of 27e305d..origin/main, so neither side lost a line.
- tools/build_us_target_parity_manifest.py on the pinned feed
  (consumer_facts_us_e86a83b.jsonl, sha256 24c64c99...) regenerates both
  manifest files byte for byte.
- No line main added names the previous pin (41b2fb2, 1d45a89c) or a
  US feed, parity or population-target field.
- ruff check, ruff format --check on the PR's Python files, and
  tools/ci_test_plan.py verify pass.

#1311's writer binding touches do_calibrate, _write_calibrated_artifact and
do_package; the PR changes none of those lines and calls neither function
directly from its tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis added a commit that referenced this pull request Nov 13, 2026
…and #1600

Main gained #1588, #1285, #1582, #1532 and #1600 since the last merge
(c93419c). One file conflicts, tools/build_us_fiscal_refresh_release.py,
in its import block: #1532 widened the input_mass import to four names,
right below this branch's immigration import. The merge keeps both.

No function is changed by both sides in that tool or in
test_us_fiscal_refresh_builder.py (syntax-tree comparison against the merge
base), and each side's changed functions carry over whole. Neither
tools/repin_us_spec_engine_contracts.py --check nor
tools/spec_engine_coverage.py --check moves a pin on the merged tree.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@MaxGhenis

Copy link
Copy Markdown
Contributor Author

Review pending after merge: Subfleet job 20261113-140800-pr1285-review-after-merge (review, hard tier) is queued for this pull request's whole change, git diff 89e12fb5a 7b93dae1e. It merged on in-session reviews, which the review-by-class rule does not count as the independent review. P2 and P3 findings from the job go into one follow-up issue; a P0 or P1 means a fix or a revert within 24 hours of its return.

@MaxGhenis

MaxGhenis commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor Author

The independent review of this change ran after the merge and approved it with no finding that calls for a fix or a revert. #1616 lists the seven smaller gaps it found in the fixture generator, two tests and the contract document. #1603 has since closed part of one of them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Build K epic: transactional country executor via strangler extraction from the US release monolith

1 participant