[MaxGhenis]

G8-r3a for Microcosm NZ v0: signed reconciliation of the regional Census family-type counts under Max's ruling d1932. Targets main and lands after #1394; the commit message has the full description.

What changes

• ledger_targets.py: an allocated-residual reference may declare a closed discrepancy_policy. With it, counts are exact integers reconciled in Fractions, within an absolute or relative bound, with an exact receipt. Without it, every path is the legacy one; each new branch is gated on "discrepancy_policy" in operands[2].
• NZ spec: family_reconciliation.json (d1932: max_abs 3, max_relative 0.001), a family_discrepancy profile dimension (central, and the positive-to-type-3 sensitivity), 17 household region indicators, and three parked family-type columns carrying the 51 reference bindings. All 51 regional family-type targets stay parked (requires_census_family_nucleus_standard) until G8-r3b's multiplicity classifier. Nothing enters the fit.

Invariants (for every input of the stated kind)

1. Exact closure: for a reference that declares a policy and whose gap passes its bounds, the reconciled leaves are nonnegative and sum exactly to the published total (test_signed_exact_closure_nonnegativity_and_preserved_shares, Hypothesis).
2. Bounds: a gap passes only within max_abs or max_relative, else it refuses naming region, gap and leaves; a nonzero total over empty leaves refuses. A policy whose max_relative exceeds 1 refuses.
3. Shares preserved under central reconciliation whenever the stated leaves sum to more than zero; the sensitivity changes only positive gaps, sending them wholly to type 3, and matches central for zero and negative gaps (property and example tests).
4. Growth once: with a policy declared, the exact ERP ratio applies once, after reconciliation (test_signed_compiled_erp_bridge_scales_exact_closure_once, Hypothesis).
5. Order-free: permuting regions and fact order changes no value (Hypothesis).
6. Legacy unchanged: a reference without a policy gives byte-identical values and receipts (test_legacy_policy_absent_receipt_is_byte_identical).
7. Deterministic receipts: receipts are exact rationals and byte-deterministic.

Notes

• Shared module: ledger_targets.py is in the target compilers' hash modules, and UK's native target kernels hash it too, so cache keys change for every country. Under the UK hub's Budget-window rule this does not merge before 2026-10-29 12:00Z (8am ET).
• Belgium's interim rule: no holdout reference is added (holdout_references.json is unchanged) and no stage column is rewritten before calibration.
• Region 99: it has no ERP series, so it uses the national pair. Its geography support comes from G8-m2 (Add NZ joint territorial authority, region and AS-area support #1393), which is now in this stack's base through Allocate Census residuals through shared reference profiles #1375's merge of main; b08107d drops the text that said otherwise.

Hub validation (10/25–26, serial -n 0)

• At dcab9bd: 17 files pass, among them test_nz_spec_package.py 1,201, test_ledger_targets.py 451, test_ledger_allocated_residual.py 129, test_transport_composed_graph.py 166 and test_nz_family_reconciliation.py 16. A plugin-inert control passes.
  • 11 of 11 mutants are killed: clip_negative, double_erp_bridge, drop_region_99, regional_growth_for_99, bounds_require_both, sensitivity_on_negative, policy_default_accepts_negative, float_arithmetic, totals_as_fit_rows and rows_activated each fail their test.
  • household_total_as_family_total is refused at fixture setup by the shared-universe check (ledger_targets.py, "total and partition must share one source count universe"), the guard it targets.
• At 2ffc63b: test_ledger_allocated_residual.py 136, test_nz_family_reconciliation.py 16, test_ledger_targets.py 451 and test_nz_target_references.py 50 pass. Ruff, format, git diff --check and the generator's --check pass.
  • The first review's three surviving mutants (relative_strict, max_relative_via_float, exact_reader_accepts_fraction) and a new null_recipient_accepted each fail the new tests.
• At b08107d, after the fix4 merge: test_country_spec.py 136, test_nz_spec_package.py 1,201, test_ledger_allocated_residual.py 136, test_nz_family_reconciliation.py 16, test_nz_target_references.py 50 and test_transport_composed_graph.py 172 pass.
• At 9c7c4a2, on a clean tree: the generator's --check passes, and test_ledger_allocated_residual.py 142, test_nz_family_reconciliation.py 16, test_nz_target_references.py 50, test_reference_profiles.py 122, test_country_spec.py 136, test_nz_spec_package.py 1,201 and test_ledger_targets.py 451 pass. A mutant that drops the cap fails the three above-one refusal cases.

Review

• Round 1 (Claude Opus 5.5, at dcab9bd), cut off. Subfleet's six-hour wall stopped it before a verdict.
  • Its executed results stand: 13 mutants, 10 killed; a byte-identical base-against-head differential on legacy, UK and NZ references; boundary probes; and a Fraction recompute.
  • Its three survivors and an unhandled explicit null recipient are fixed in 2ffc63b, with four tests: the relative bound is inclusive, comparisons are exact rationals, non-integer counts refuse, and a present-but-null recipient refuses.
• Round 2 (Claude Opus 5.5, at 2ffc63b; the Sol attempt failed with the model at capacity): APPROVE_WITH_NITS, no blocker.
  • Its two follow-ups are fixed in 9c7c4a2.
    • A max_relative above 1 now refuses.
    • The disclosure said the base-3-rounded type counts and totals "can differ by up to 3 families". That fails under random rounding: true counts (1, 1, 1) with total 3 can publish as (3, 3, 3) with total 3. It now says their sums need not agree and that the observed regional gaps are at most 3.
  • Its finding 7, that the relative bound divides by the stated leaves, matches the design d1932 adopted ("0.1% of stated leaves").
  • Accepted as is:
    • integer strings such as "41" pass the exact reader, which is no looser than the old float();
    • ledger_value_ratio is written as "109/100", and nothing reads it;
    • 9 of the 16 family tests need the Chronicle artifact, so they skip in CI.
• Batch delta review of the fix4 merges (GPT-6.1 Sol, at db02ae8, covering be27d7e and b08107d): APPROVE, no findings. For this PR it confirmed:
  • Add NZ joint territorial authority, region and AS-area support #1393 is an ancestor;
  • the generated bindings match the committed bytes, and only the two stated golden leaves change;
  • all 51 family rows stay parked, and all 13 region-99 rows keep the national ERP pair.
• Round 3 (GPT-6.1 Sol, a delta review of 9c7c4a2): APPROVE, no findings.
  • The cap: it compares exact rationals. UK declares no max_relative, and NZ's 138 declarations are all 0.001.
  • The disclosure: all 17 regional gaps recompute to −3, 0 or +3. With only the disclosure replaced, the parent's files equal the head's, and the parent's 34 receipts hash to the new pinned digest.
  • The golden: it moves only those three hashes and the fingerprint.
  • Its own runs: test_ledger_allocated_residual.py 142 and test_nz_family_reconciliation.py 16 pass. Four mutants (no cap, a strict cap, a float cap, the old disclosure) each fail.
  • An informational note: the repo cites d1932 but doesn't show its text. The recorded ruling (Max, 2026-10-24) is to reconcile, "signed, at most ±3 families or 0.1%". Its decision record points to the design's §4, which states the relative bound as 0.1% of the stated leaves, as the code computes.

Status

• be27d7e merges Add exact income-band intervals and boundary diagnostics #1394's head, which carries Add feed-derived NZ reference ageing factors (G8-r2a) #1382's fix4 (Belgium OK'd it 10/26). The merged transport/cli.py is c4ddcb4's blob and the only transport file the merge changes. The NZ golden conflicted and was regenerated from the merged tree; per-key attribution shows no mismatches.

• b08107d updates the region-99 support text now that G8-m2 is an ancestor. The generator regenerates calibration_bindings.json, and the golden follows its hash.

• 9c7c4a2 fixes round 2's two follow-ups (see Review). It touches no transport file. The generator regenerates the reference inventory and profiles, which repeat the disclosure; with the text masked they are unchanged. The golden and the pinned receipt digest follow.

• Round 3 approved 9c7c4a2.

• Landing (2026-10-29). The NZ hub retargeted this PR to main on 2026-10-29, so it ran CI for the first time; stacked PRs never ran it.

  • fd70257 merges main (fddbc70) through update-branch; 0df4561 and 215c71c merge Add feed-derived NZ reference ageing factors (G8-r2a) #1382's CI import fix. Delta review of that fix (GPT-6.1 Sol, job 20261029-083505): APPROVE, no findings. Merging the fixed head into main differs from merging the previously reviewed head only in the fixture import lines of test_reference_factors.py and test_reference_profiles.py.
  • A failure the stack hid. test_spec_only_country_packages.py::test__given_country_specs__then_no_python_entrypoints_are_declared fails at the reviewed head 9c7c4a2 too. That test flags any module.path:name string as a Python entrypoint, and this PR's data carries 159 ledger.aggregate_fact.v2:<hex> fact keys in three shapes it didn't admit: signed partition operands, which add discrepancy_policy and may name one positive_allocation_member_keys recipient; that positive roster; and raw_fact_keys on each regional reconciliation receipt. The hub's r3a validation plan didn't include that file, and the stack had no CI.
  • a97a155 widens the test's admission to these shapes and no further. The partition rule takes its field sets from ledger_targets._validate_allocation_reference: discrepancy_policy opens the signed fields, and a positive roster needs it and names exactly one partition member. It checks field sets and key shapes, not the compiler's full validation; the compiler still refuses a bad policy or recipient set, and the scan still reads every selector and policy. Raw fact keys pass only as exact copies of the receipt's own leaf_selectors and total_selector pins, which all 34 receipts are. Any other shape still falls through to the entrypoint scan. Seven new rejection cases cover it, and five mutants of the new rules each fail a test. No source or data file changes.
  • Delta review of a97a155 (GPT-6.1 Sol, job 20261029-091411): APPROVE, no blocking findings. The scan caught all 185 adversarial callable strings the review injected through these shapes, in synthetic and real receipts and partitions; all 34 receipts meet the copy rule; and nine mutants of the new rules fail all ten new cases. It noted the field-set scope described above.
  • CI then failed test_uk_target_compile_modules.py::test_every_direct_import_of_a_listed_module_is_listed_or_excluded: Add feed-derived NZ reference ageing factors (G8-r2a) #1382's 1d5fff4 made ledger_targets, a UK target compile module, import LexicalFloat from ledger_artifact. Add feed-derived NZ reference ageing factors (G8-r2a) #1382's b36c702 first added ledger_artifact to EXCLUDED_DIRECT_IMPORTS; 8853469 merges it through Add exact income-band intervals and boundary diagnostics #1394.
  • b1c1f5e merges main after Allocate Census residuals through shared reference profiles #1375's landing. It changes no file, but Allocate Census residuals through shared reference profiles #1375 landed as 6af97bf, so this branch had two merge bases with main; GitHub marked the PR conflicting and ran no CI until this merge gave it one.
  • The Sol delta review of that exclusion (job 20261029-095750) asked to list ledger_artifact instead: both UK target kernels decode their facts through it, so an edit to its decoder could move a UK target value without moving either kernel's implementation hash. Add feed-derived NZ reference ageing factors (G8-r2a) #1382's 7cd1d26 lists it in UK_TARGET_COMPILE_MODULE_NAMES (see Add feed-derived NZ reference ageing factors (G8-r2a) #1382); 0a8568b merges it through Add exact income-band intervals and boundary diagnostics #1394.
  • Delta review of the listing across all five heads (Opus 5.5 in session, since every Codex lane was held): APPROVE_WITH_NITS, no blocking findings (see Add feed-derived NZ reference ageing factors (G8-r2a) #1382).
  • CI stops at the first failure, so about 358 of the 22,000-plus engine-free tests never ran in the failed rounds. They sit in the 29 files after the failing one in CI's list; the hub ran all 29 (711 tests) with CI's import path at the two stack tips, Add receipt contract v2 and selection-aware reference preflight #1397 and Reconcile regional Census family-type counts under d1932 #1398: 705 passed and 6 skipped at each.
  • CI at 0a8568b: every job passed (gh pr checks exit 0; run 40897375644): engine-free, engine-uk and engine-us on Python 3.13 and 3.14, integration-uk, lint, select-countries and wheels.
  • BE re-clear: Belgium's hub is away until 2026-10-31, so the NZ hub ran Belgium's own dump_be.py and its three BE suites (test_spec_engine_country_bundles.py, test_country_spec.py, test_spec_only_country_packages.py) at 0a8568b, alone and merged with Belgium's open Rewrite the Belgian country package for donor transport #1369 (dc157a7). The BE dump matches main's byte for byte; with Rewrite the Belgian country package for donor transport #1369 merged in, it matches main plus Rewrite the Belgian country package for donor transport #1369. The BE golden comparison holds in both, and all three suites pass with Rewrite the Belgian country package for donor transport #1369 merged in.

• Sibling merge (2026-10-29, after Normalize donor money with exact declared factors #1395 and Add receipt contract v2 and selection-aware reference preflight #1397 landed). This PR and Normalize donor money with exact declared factors #1395 both branched from Add exact income-band intervals and boundary diagnostics #1394, so neither line's CI ever saw the other.

  • 30edef9 merges main (41f9a8c). Both lines add a resource to nz/country_package.json, so tests/golden/nz_country_spec.json conflicted. Git merged the package (it now lists both family_reconciliation.json and money_normalization.json), test_reference_profiles.py and test_spec_engine_country_bundles.py cleanly; each test file's diff against main equals this PR's own change. The hub regenerated the golden from the merged spec with the golden test's own _loaded_spec_summary and canonical_json_bytes. Against main's golden it changes this PR's five resource hashes, the package's own hash, the resource list and the fingerprint, and nothing else.
  • The hub then ran the 38 engine-free test files that either line changed or that load the NZ spec at 30edef9, with CI's import path. Two pinned digests failed on the combination. Each passes at main and at 0a8568b alone, because each pins output over NZ data both lines touch. abc0243 re-pins both, and only both:
    • test_prepare_matches_pinned_legacy_output_digest hashes prepare_calibration_columns over nz/calibration_bindings.json, which this PR extends. On the merged bindings, Add receipt contract v2 and selection-aware reference preflight #1397's pre-refactor implementation (4f333f2), main's code and this head's code all give 1b22f4e1. On main's bindings the pre-refactor implementation still gives the old pin, dca0e085. So the refactor stays byte-equivalent.
    • test_nz_factor_receipts_are_byte_identical_after_additive_factors pins the v2 receipts from before Normalize donor money with exact declared factors #1395's donor factors, over target_references.json and reference_profiles.json, which this PR changes. The three receipts at 0a8568b (this PR's data, no donor factors) equal the merged tree's (b0f8648d, 8989fa75, e246f615), so the donor factors still leave them byte-identical.
    • The other 35 files passed: 3,064 tests, 17 skipped. At abc0243 the two re-pinned files pass all 216 tests. The one other failure, test_spec_engine_reemission.py::test_normative_mutation_changes_hash_and_names_legacy_payload_field, came from the hub's own environment: its QRF worker venv declares Python 3.14.4 and the hub runs 3.14.7. CI passed that test at every earlier head.
  • Delta review of the sibling merge and abc0243 (Opus 5.5 in session, since every Codex lane was held; jobs/review-microcosm-1398-merge): APPROVE_WITH_NITS, no blocking findings; Needs Max: no. The merge. Every main-only file equals main's blob and every file only this PR touches equals 0a8568b's, and git merge-file reproduces the three overlap files byte for byte. The golden. Its own regeneration gives the same bytes. The pins. It found the two stale pins on its own (GitHub CI on 30edef9 also failed first on the receipts test), and it checked abc0243's re-pins against 4f333f2's own code and against 0a8568b's receipts. Tests. It ran 39 test files in CI mode, plus, with the pinned feed, the six NZ files that skip without an artifact, and it confirmed the reemission failure comes from the hub's environment. Nits for a follow-up. The two re-pinned tests still hash live NZ data, so the next NZ data change will move them again, and their inputs could be frozen as reference_selection_legacy.py.txt is; and a substring check in test_nz_money_normalization is fragile.
  • CI at abc0243: every job passed (gh pr checks exit 0; run 40922086707): engine-free, engine-uk and engine-us on Python 3.13 and 3.14, integration-uk, lint, select-countries and wheels.
  • BE re-clear at 30edef9, against main at 41f9a8c, alone and merged with Rewrite the Belgian country package for donor transport #1369 (dc157a7): the BE dump matches main's byte for byte, and main plus Rewrite the Belgian country package for donor transport #1369's with Rewrite the Belgian country package for donor transport #1369 merged in; the golden comparison holds in both; and all three BE suites pass with Rewrite the Belgian country package for donor transport #1369 merged in. abc0243 changes only two NZ test files, which neither dump_be.py nor the BE suites read.

🤖 Generated with Claude Code

[MaxGhenis]

Merged by the NZ hub (session local_e407a527) at abc0243 with --merge. Gates: gh pr checks exit 0; MERGEABLE; not draft; no CHANGES_REQUESTED review. Reviewed head: abc0243. Independent delta review (Opus 5.5 in session, jobs/review-microcosm-1398-merge) approved abc0243 with non-blocking nits; gh pr checks exit 0 on run 40922086707; BE re-clear at 30edef9 clean (abc0243 changes only two NZ test files).