Make Build O's state SOI contract the ACS local default; totals and full are opt-in

[MaxGhenis]

What this does

Makes state the default SOI target surface of the US ACS local-area chain (tools/build_us_acs_local_release.py --soi-mode); totals and full become explicit opt-ins.

state keeps every state-bearing irs_soi spec at ledger_geography_level == "state" whose ledger_layout_record_set_spec_id is not a congressional-district file, of any target_role (soi_surface_predicate). A spec missing either key is not selected. On the pinned feed (consumer_facts_us_c5e5bf8.jsonl, sha256 b8543739…) it selects exactly Build P's 3,972 admin specs — 102 SNAP, 51 Medicaid and 3,819 SOI from the three TY2022 Historic Table 2 state tables (state broad totals 2,397; AGI-band taxable interest 912; EITC by qualifying children 510) — or 4,459 targets with the 487 population marginals. That is the contract every earlier ACS local-area release was calibrated to: Build O selected it as full while state_admin_specs compiled with include_congressional_district_targets=False (populace 77e2061), and Build O's 4,461 is this set plus the Vermont under-$1 taxable-interest pair the compiler now excludes. Commit b7922b089 (2026-08-21) removed that switch, so no mode reproduced the contract until this one.

Why (Max's ruling, 2026-09-22)

The first version of this PR made totals the default on a description that turned out wrong. Measured on the pinned feed: totals keeps 607 SOI specs, all ACA premium tax credit rows, and no state AGI, income-tax or EITC total; full (31,066 admin specs) adds mostly all-income-range rows — 23,886 congressional-district and 5,508 state rows, the latter duplicating the Historic Table 2 state concepts from the TY2023 district file — and only 912 AGI-band rows, and its 183.9 GiB dense matrix does not fit one 128 GB machine. state is the only surface that keeps the state income targets and fits (23.5 GiB dense; Build P recorded a 93.9 GB materialize peak on it), and it lets a new local build be scored against the published Build O on the same targets. Max chose it on 2026-09-22. Full measurements: docs/us-acs-local-soi-target-surface.md.

state needs #969's restated-filter support, now merged: on this branch after merging main, the materializer's _assert_supported_ledger_filter_metadata accepts all 3,972 state specs (without #969 it refused 1,014).

Also in this PR (from the first version)

• One definition of the modes (SOI_MODES, DEFAULT_SOI_MODE); an unknown mode is refused before the feed is read (the old predicate silently treated any value other than full as totals).
• --stage package reads the mode materialize recorded (materialize_rss.json), not the package invocation's flag, and refuses a checkpoint that records no known mode before any release directory exists.
• The mode is recorded in build_manifest.json (materialize.soi_mode) and the release refresh recipe names --soi-mode <mode>.
• The national release is unchanged: tools/build_us_fiscal_refresh_release.py has no SOI mode and does not call state_admin_specs.

Tests

packages/microcosm-build/tests/test_us_acs_local_release_tool.py: 45 pass with MICROCOSM_US_CHRONICLE_FACTS set to the pinned feed, including test_pinned_feed_soi_surfaces_match_their_contracts (the 3,972-spec state contract by family and record set, all at state geography; totals holds no soi_fiscal_distribution spec; full adds exactly those to totals and contains state) and test_state_soi_surface_is_build_o_contract_by_record_set_and_geography. Negative control: with the default flipped back to totals and the geography check disabled, 5 tests fail. ruff check . clean; tools/ci_test_groups.py --verify ok. The feed-gated test skips in CI (no lane carries the 164 MB feed).

Operating note

A full-scale run on state needs the supervisor RSS cap above Build P's 93.9 GB peak and room for a 23.5 GiB memmap. To reproduce the 2026-09-22 hours rebuild (#974), pass --soi-mode totals.

🤖 Generated with Claude Code