Skip to content

Bind the ACS local artifact to the code that wrote it - #1311

Merged
MaxGhenis merged 7 commits into
mainfrom
us-acs-local-live-inputs-followup-1263
Nov 11, 2026
Merged

MaxGhenis merged 7 commits into
mainfrom
us-acs-local-live-inputs-followup-1263

Conversation

@MaxGhenis

@MaxGhenis MaxGhenis commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Part of #1263. Follow-up to #1309's review.

Change

  • Writer binding. Calibrate records its code identity in consumer_export.json (code). The build's ID names the packaging code, so package (_require_artifact_written_by) gives a build an ID only when the checkpoint names the packaging checkout's full commit as its writer. It refuses a checkpoint that records no writer, and one whose record does not say "dirty": false unless the operator passes --allow-dirty. Before this, a build's ID could name packaging code that never wrote the artifact.
  • The identity calibrate records. Calibrate reads the checkout's commit and dirty state as its first step, before it loads or solves anything. Just before it writes the calibrated H5 it reads them again (_require_unchanged_code) and refuses if either differs, so it writes neither the H5 nor consumer_export.json from a checkout that changed during the solve. The record holds the identity from the first read.
  • Exact disclosure. acs_wic_takeup_assumed_interim now says the assumption covers "every person without one (N, all on the ACS spine, of M ACS-spine people)". The receipt records people_allowed_without_decision, so a reader can check N = M. For a receipt without that count, the sentence leaves out the "of M" clause.
  • Coverage.
    • Every stored Boolean dtype reads alike: pandas BooleanDtype with pd.NA, numpy bool, float 0/1/NaN, and object.
    • The tool refuses, and does not fill, when person_spine is absent, NaN, None, bytes or another label.
    • The module tests build their mask from person_spine, as the tool does.
    • The test module's docstring points at the engine-contract test that pins the live input as a Person Boolean defaulting to True.
  • Nits.
    • _booleans accepts only bool and int/float 0/1, so it refuses Fraction(1).
    • consumer_ready's gate summary carries live_stored_inputs and code.
    • The spine-blindness register entry sits in alphabetical order, with an exact comment.

Package refuses a checkpoint that calibrate wrote before this PR, because that checkpoint records no writer. Re-run calibrate, qa and finalize with this code to package it.

This PR changes no dataset value and no gate threshold. It adds code to the published consumer_export.json and to gate_summary.json's consumer_ready block, changes the text of the WIC limitation, and lets a dirty writer set build_dirty.

Invariants

  1. For any writer record, package gives a build an ID only when the record names, as a non-empty string, the full commit of the packaging checkout. Otherwise it raises SystemExit before it creates a release directory. A Hypothesis property (200 examples) and example rows pin this.
  2. Package reads a writer as clean only when its record says "dirty": false. Any other record needs --allow-dirty, and the build manifest then records build_dirty: true even when the packaging tree is clean.
  3. Calibrate records the code identity it read as its first step, before the solve.
  4. Calibrate writes neither the calibrated H5 nor consumer_export.json unless the checkout's commit and dirty state, read again just before the H5, equal the ones it started with. A git failure at either read stops the stage before the H5 exists. A branch rename alone refuses nothing.

#1581 lists three cases outside the binding: --stage all reads the identity after materialize, a resumed run records the resuming commit, and a git failure prints a traceback.

Merges with main

The branch merges main twice. The first merge (30cce76cd) kept both sides of two package fixtures in test_us_acs_local_release_tool.py and made the fixture of main's district ESS gate test record its writer. The second (241bd4a33) took #1571, which fixed the local release's name and left the build's ID to name the packaging code; the binding's messages, the runbook paragraph and the changelog fragment say "build's ID" for that reason.

Tests

  • CI on d3c4c46f8: lint, wheels, select-countries, installed-emitter, engine-free (3.13, 3.14) and engine-us (3.13, 3.14) pass. engine-uk and integration-uk skip, because the country selector leaves the UK out.
  • Mutation checks: removing the binding call from do_package fails two tests. Five mutants of the binding's rules (the wording, a missing dirty key read as clean, any truthy commit, an inverted dirty rule, the WIC count always rendered) each fail a named test.

Review

axiom: n/a: release tooling; no policy rule changes.

🤖 Generated with Claude Code

MaxGhenis and others added 5 commits October 18, 2026 14:30
Follow-up to #1309's review (GPT-6.1 Sol, approve with minors):

- calibrate records its code identity in consumer_export.json; package
  refuses to name a release after any other commit, a dirty writer
  without --allow-dirty, or a checkpoint that records no writer.
- The interim WIC limitation states whom the assumption covers (the people
  without a stored decision, all on the ACS spine), and the receipt records
  how many people were allowed to lack one.
- _booleans accepts only bools and int/float 0/1, as policyengine.py's
  reader does (a Fraction is refused).
- consumer_ready's gate summary carries the live-input receipt and the
  writer's code.
- Tests: every stored Boolean dtype (pandas BooleanDtype with NA, numpy
  bool, float 0/1/NaN, object), an unreadable or absent spine tag refuses
  rather than fills, the writer binding, a mask built from person_spine;
  the spine-blindness entry is in order with an exact comment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The abbreviated sha's length depends on the checkout: Modal's shallow clone
abbreviates to 7 characters, a full clone to 9 or more, so comparing short
shas could refuse an artifact written by the same commit. Record and compare
the full commit; the release id keeps the abbreviated sha.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review of #1311 (GPT-6.1 Sol r1, approve):

- F1: build_dirty is true when either the packaging tree or the tree that
  wrote the artifact was dirty; _require_artifact_written_by returns the
  writer's flag.
- F2: do_package refuses another writer before any release directory
  exists, and a dirty writer marks a clean-packaged release dirty.
- F3: the spine-tag test builds its frame with the tag instead of editing
  a Frame's stored table.
- F4: nullable Int64/Float64 with NA and int8/uint8 read alike; Decimal and
  complex are refused, and the docstring no longer overstates parity with
  policyengine.py (this rule is stricter about complex).
- F5: the Modal runbook says package runs at the commit calibrate ran at.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review of #1311 round 2 (approve): the two new do_package tests write H5
and need the requires_pytables marker, and the dirty-writer test now
patches a clean packaging identity so it cannot pass on a dirty checkout
without the fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Conflict in test_us_acs_local_release_tool.py: two package fixtures where
this branch adds the writer's code to consumer_export.json and main
reshaped consumer_reviewed_null_fills.json. Both sides kept.

Main's new district ESS gate test (29921fb) packages a checkpoint whose
consumer_export.json names no writer; it now records one, since package
refuses an artifact it cannot bind to the code that wrote it.

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

Copy link
Copy Markdown
Contributor Author

Hand-off to the Microcosm hub

  • Head: 30cce76cd41608637a2c47a2dc7ed3ef044fb955, which merges main at 6255b4adf into b388570c1.
  • Conflict: test_us_acs_local_release_tool.py, two package fixtures. This branch adds code to consumer_export.json and main reshaped consumer_reviewed_null_fills.json to {"columns_filled": 0, "fills": []}. I kept both.
  • One more edit: main's new district ESS gate test (test_the_district_ess_gate_ships_in_both_manifests, from 29921fb) packages a checkpoint whose consumer_export.json names no writer, so this PR's binding would refuse it. Its fixture now records the writer, as the other package fixtures do.
  • Passed locally after uv sync --all-packages --locked, with pytest at 4 workers:
    • the PR's three test files (release tool, retired stored inputs, spine blindness): 812 passed, 1 skipped. The skip is main's chronicle-facts test, which needs MICROCOSM_US_CHRONICLE_FACTS.
    • the 12 other engine-free files that load the release tool: 937 passed, 9 skipped.
    • ruff check and ruff format --check on the changed files.
  • Pending:
    • CI on main's workflow (run 43058497335).
    • The independent review at this head, which the hub runs. Earlier Sol reviews approved b388570c1 in three rounds (~/reviews/microcosm-1263/review-1311-r1.md, -r2.md, -r3.md); they predate the merge.
  • Depends on: nothing. No decision is held, and the change builds no dataset.

MaxGhenis and others added 2 commits November 11, 2026 11:33
Main gained #1571 (US builds publish through the emitter) after this
branch's last merge. Git merged every file without a conflict. Both sides
change do_package in tools/build_us_acs_local_release.py, the release
tool's test file and the Modal stage runbook, in different hunks.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Answers the review of #1311 (findings F1 to F5 and F7).

Calibrate now reads the checkout's code identity as its first step, before
it loads or solves anything, and records that identity in
consumer_export.json. Just before it writes the calibrated H5 it reads the
identity again and refuses if the commit or the tree's dirty state
changed, so a checkout that moves during a solve of hours yields no H5 and
no consumer_export.json. Until now calibrate read the identity after the
H5 existed: a checkout that moved mid-run recorded the new HEAD, packaging
at that HEAD passed although older code wrote the bytes, and a git failure
lost consumer_export.json after the H5 was on disk.

Package reads a writer record as clean only when it says "dirty": false.
A record with no dirty key now refuses without --allow-dirty and marks the
build dirty with it. A writer's commit must be a non-empty string, so
equal values that are not commits (True == 1) bind nothing.

Since #1571 the release is fixed and the build's ID names the packaging
code. The binding's docstring and its three messages, the runbook
paragraph and the changelog fragment now say that package refuses to give
a build an ID that names code other than the code that wrote the artifact.

Finalize no longer renders "of None ACS-spine people" in the WIC
limitation for a consumer export written before the count existed.

Tests drive calibrate through a tiny real solve into the real write: the
record equals the identity read at the start; the second read follows the
last preparation step and precedes the H5; a moved, dirtied or cleaned
checkout, or a git failure at the write, leaves no H5 and no
consumer_export.json; a git failure at the start stops the stage before
the solve. A Hypothesis property (200 examples) states the binding for any
writer record and any packaging identity.

A clean, unchanged run writes the same consumer_export.json as before;
only the time of the read moves.

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

Copy link
Copy Markdown
Contributor Author

Landed by the Microcosm hub as a575057 (merge of d3c4c46 into main b427c0a; main's tree equals the tested merge).

@MaxGhenis
MaxGhenis deleted the us-acs-local-live-inputs-followup-1263 branch November 11, 2026 23:48
MaxGhenis added a commit that referenced this pull request Nov 12, 2026
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>
MaxGhenis added a commit that referenced this pull request Nov 12, 2026
Main 57a32f8 (#1579, #1553, #1311, #1583, #1584) changes two attested
inputs: microcosm.fit.qrf, on the seed protocol's QRF kernel list, and
sources.schema.json. #779 changes the immigration kernel, the US source
stages and the same schema, so every US F0 digest the two sides pinned
moved on both, and four files conflicted. Each conflicted pin was first
replaced by a sentinel, and the repository's tools wrote every value
from the merged tree:

- packages/microcosm-build/src/microcosm/build/spec_engine/inventory_coverage.py:
  EXPECTED_HASHES seed_map, seed_protocol and source_manifest, from
  tools/repin_us_spec_engine_contracts.py (source_manifest comes out at
  the branch's value; main left it alone). The branch's seed groups and
  counts merged cleanly.
- packages/microcosm-build/tests/engine_free/shared/test_spec_engine_loader.py:
  the minimal-loader golden, from the same repinner (it loads
  _rich_minimal through load_bundle exactly as the test does).
- packages/microcosm-build/tests/engine_workflow/us/test_us_multispine_pool_tool.py:
  the US spec_sha256, from the same repinner (load_bundle("us")).
- docs/evidence/spec-engine/us-f0-coverage.json: regenerated whole by
  tools/spec_engine_coverage.py (42781/42781 fields, 41/41 checks).

The repinner ran twice around the coverage regeneration. Its first pass
read the sentinels and wrote covered_item_count 39 into
tests/engine_contract/us/test_spec_engine_coverage_tool.py; the second
pass put it back to 41, so that file is unchanged from the branch.
ruff format changed only quote style on the three Python files.

No pin moved without a conflict:
- repin_us_spec_engine_contracts.py --legacy-only wrote nothing (main
  does not touch us/source_stages.json).
- tools/build_us_release_input_coverage_manifest.py rewrote
  us/release_input_coverage_manifest.json byte for byte.
- Both repinner --check and spec_engine_coverage.py --check exit 0.

The other four files both sides changed merged without conflict and
are git's three-way result: sources.schema.json,
tools/build_us_acs_local_release.py,
tools/build_us_fiscal_refresh_release.py and
tests/engine_free/us/test_us_acs_local_release_tool.py.

tools/generate_us_bundle_from_constants.py --check was not run: it needs
policyengine-us. Main changes no us/spec file and no
tools/us_bundle_generation file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
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.

1 participant