[MaxGhenis]

G8-w1 for Microcosm NZ v0: receipt contract v2 and selection-aware reference preflight. Targets main and lands after #1395. The commit message has the full description.

What changes

• Receipt contract v2 (transport/receipt_contract.py). It is opt-in: a contract without contract_version runs the v1 validator and assignment bodies unchanged.
  • v2 is closed at every level.
  • It adds disjoint strata, each with its own rate, and knob-selected assignment profiles (draw key suffix and exclusion order).
  • exclude_columns keeps v1's semantics, and it runs before group exclusions.
  • Overlap and weighted Hall feasibility diagnostics never refuse.
  • Each stratum records its realized weighted count beside its target.
  • The reserved unit fields (entitlement_entity, payee, draw_unit, projection) admit only "person", and every read goes through them.
• Shared calibration predicates (calibration_predicates.py): preparation and receipt strata use the same validated predicate evaluation.
• Reference selection (transport/reference_selection.py): opt-in per-resource exemptions for parked references. They are validated against the full effective document before any row is filtered. A spec without a selection resource compiles as before.

Invariants

Invariant 1 covers v1 contracts, 2–7 cover v2 contracts, and 8 covers specs with or without a selection resource. Each holds for every input of its kind, not just the examples:

1. v1 is unchanged on success. For a valid contract without contract_version, the flags and audits are byte-identical to the pre-v2 code. Refusals are in the notes below: one fault refuses as before, but two at once may refuse on a different one first. test_transport_receipt_v2.py freezes the baseline assignment and compares toy and Hypothesis-generated v1 cases.
2. Strata are disjoint on the data. Overlapping filters refuse, and nobody outside the strata is assigned.
3. Mutual exclusion. Within an exclusion group, no unit gets two outputs: each output's pool drops units already assigned to an earlier member.
4. Assignment is bounded. Assigned ⊆ judgments ∧ payment > 0 ∧ ¬exclude_columns ∧ stratum.
5. Draws are deterministic, and draw keys are injective across (program, suffix) pairs, including adversarial delimiters.
6. Expected mass. For every completed v2 assignment, each stratum's rate × remaining eligible mass equals its target within a relative 1e-12. Each stratum's audit records the check. A failed check, or a target above the remaining mass, refuses with the audit attached (the failed-check refusal is new in 5108046).
7. Diagnostics never gate. The overlap and Hall diagnostics only report.
   • Since 5108046 the Hall check is an exact max-flow, not a loop over every subset. Since 2f2f704 it runs Dinic on integer capacities, so at most one routing phase per demand carries flow.
   • One limit remains, as before: a reported cut whose total exceeds the float range can't be written as a float.
8. No selection, no change. Without a reference_selection resource, node parameters, surfaces and keys match the legacy path. A differential test runs against the reference_selection_legacy.py.txt fixture.

Notes

• v1 refusal order (from Belgium's review): on v1, _document(receipt_contract) now runs before the v1-only require_params and before _whole_tables.
  • A v1 node with a single fault refuses exactly as before v2. The review's kernel differential found that 14 of 15 single-fault kinds match.
    • The fifteenth isn't a v1 node: a contract carrying a contract_version key, whatever its value, now refuses with the v2 message ("Receipt v2 contract has missing or unknown fields.").
  • With two faults at once, 22 of the 91 pairs get a different first refusal:
    • a bad contract document plus a v2-only parameter;
    • a bad contract document plus missing tables, node sources or an undeclared artifact alias;
    • a contract_version key plus any other fault;
    • a missing contract or sha plus a v2-only parameter, which now refuses as "missing required parameter(s)" rather than "unknown parameter(s)";
    • an unknown parameter plus a v2-only parameter, where the message now names only the unknown one.
  • Every refusal stays a ValueError, except a non-string contract, which is a TypeError before and after.
• Cache keys change for every country.
  • The new modules join the implementation hashes of takeup.assign@1, calibration.prepare@1 and the target compilers, and target_kernels.py itself changes.
  • Since 5108046, reference_profiles and reference_selection also join the hashes of the five kernels that decode the target surface but hashed neither: takeup.assign@1, targets.problem@1, the gate battery, diagnostics.calibration and geography support.
  • In all, 18 of the 31 registered kernel implementation hashes moved at 5108046 (Belgium's count), not only those five. Nothing pins them. 2f2f704 moves 2 of the 31 again: takeup.assign@1 and calibration.prepare@1.
  • Under the UK hub's Budget-window rule, this PR does not merge before 2026-10-29 12:00Z (8am ET).
• Belgium transport protocol. Belgium cleared the src hunks in the hub's hunk file c2, unconditionally.
  • The c2 file's sha256 is 11b7eadc3e6951c1…. Its file order (modified files, then new ones) differs from git diff's, so a fresh diff hashes differently.
  • Applying c2 to 4f333f2 gives the same eight src blobs as 2f220f7, d8425ae and f5e75f8: calibration_columns.py c41ee074, calibration_predicates.py 13d38162, column_kernels.py bfa7eadf, compose.py a4184747, receipt_contract.py 9227d880, reference_selection.py f8334344, takeup_kernels.py b1d110a2 and target_kernels.py 2b95a01d.
  • The S5 (Let transport specs declare pre-calibration stages #1392) merge check gives 0 conflicts against 9959390.

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

• At 2f220f7, 13 of 14 files passed. Those are the receipt v2 files, the column, takeup, target and money kernels, the composed graph, the transport graph, reference profiles, the NZ spec package, the country spec, the spec-engine bundles and the UK target references.

• test_transport_reference_selection.py failed 3 tests there, all fixture faults:

  • one comparison node passed a single entity where the kernel needs a person entity plus a group entity;
  • one fixture graph had a CREATE node with no sources.

  The build lane had not run the file, and draft CI doesn't run. d8425ae fixes both fixtures, and the file now passes: 33 tests.

• Mutants: all 18 are RED and restored byte for byte. One of them, legacy_selection_path_changed, was red at 2f220f7 only because its test already failed. Rerun at d8425ae, it fails on the frozen-params assertion, so that kill is now real. A 19th mutant, which skips the takeup.compare exemption check, makes the direct-comparison test fail.

• Static checks pass: the CI test plan, the burndown, git diff --check, and Ruff check and format.

• At f5e75f8, after the fix4 merge: test_country_spec.py 136, test_nz_spec_package.py 1,201, test_transport_reference_selection.py 33, test_transport_money_kernels.py 40 and test_transport_composed_graph.py 172 pass.

• At 5108046 and 84c2082, one file per process at -n 0: test_transport_receipt_v2.py 97, test_transport_receipt_v2_kernel.py 14, test_transport_reference_selection.py 51, test_calibration_columns.py 91, test_transport_column_kernels.py 30, test_transport_takeup_kernels.py 38, test_transport_target_kernels.py 67, test_transport_composed_graph.py 172, test_transport_graph.py 15, test_reference_profiles.py 123, test_nz_spec_package.py 1,201, test_country_spec.py 136, test_spec_engine_country_bundles.py 21, test_uk_target_references.py 30 (5 skipped), test_transport_money_kernels.py 40, test_transport_gate_kernels.py 31, test_transport_terminal_kernels.py 18, test_gate_battery_contract_pins.py 20, test_gate_battery_replay.py 2, test_nz_joint_geography.py 22 (11 skipped) and test_transport_codecs_geography.py 22 pass.

  • The run used the uncommitted tree on f5e75f8. git diff f5e75f8b 84c2082b is byte-identical to it (sha256 1ca0bcc5…).
  • The two refusals the hub added (an unresolved assignment knob and a missing entity table) each have a test and a mutant that fails it.

• At 2f2f704, one file per process at -n 0: the same 21 files pass, with test_transport_receipt_v2.py at 117 and test_transport_reference_selection.py at 60; the other 19 match the 84c2082 counts above.

  • 16 mutants each fail a test that guards their line, and each file is restored byte for byte. Review r4's pattern-index mutant fails the new witness.
  • The plan ran on the uncommitted tree; the commit adds only that witness test (src sha256 20baf6fa… against 97c08e0 either way).

Status

• Review, round 1 (Claude Opus 5.5, at d8425ae; Codex was at capacity): APPROVE_WITH_NITS, nothing blocking.
  • v1 is unchanged on success: 4,500 generated contracts against the base commit's own code gave 0 differences. v2 and reference selection are dormant, since no packaged spec declares them.
  • Fixed in this body: the Belgium hash (F1; see Notes) and the refusal-order classes (F5).
  • Fixed in code at 5108046 (a GPT-6.1 Sol build lane, plus two hub additions):
    • The Hall diagnostic is an exact rational max-flow (F2). A Hypothesis test checks it against an exact brute force. The 0.11 s for 24 demands on 20,000 people came from a fixture with only 6 distinct patterns; round 2 (F-A) found the general case unbounded.
    • A failed numerical check refuses (F6).
    • The two surface-decode guards and the resolution filter have tests (F3).
    • reference_selection and reference_profiles join the implementation hashes of the kernels that decode the surface (F4).
    • Activation validates binding domains, and validation refuses exclusion cycles (F7).
    • takeup.assign's node key reads only its knob (F8).
    • The two property tests catch their mutants on every run (F9).
    • Four v2 edge cases are handled (F10).
    • The lane's 17 mutants and the hub's 2 are all RED. v1 still matches the base on 1,500 mixed and 3,000 valid contracts, and calibration.prepare on 300 cases.
  • Belgium OK'd the src hunks (sha256 0a6d4d16…) before the commit. It found no pinned hashes or keys in B1's golden or S5's tests. Merged with S5 91d46e1 and B1 dc157a7, 1,955 of 1,955 tests passed.
  • 84c2082, test-only: it suppresses Hypothesis's too_slow check on NZ's hold-out property test, which failed once on a stalled host.
  • Hub provenance (F11): reruns no longer overwrite earlier logs, and each record names its HEAD.
• The fix4 merge: f5e75f8 merges Normalize donor money with exact declared factors #1395's head (db02ae8), which carries Add feed-derived NZ reference ageing factors (G8-r2a) #1382's fix4 (Belgium OK'd it 10/26). It merged clean, the merged transport/cli.py is c4ddcb4's blob, and the NZ golden regenerates byte for byte. The batch delta review (GPT-6.1 Sol, at db02ae8) approved the batch with no findings. It rebuilt this merge with git merge-tree, and the result matches exactly.
• Review, round 2 (Claude Opus 5.5, at 84c2082): REQUEST_CHANGES.
  • F-A, blocking: the Hall max-flow was still unbounded with distinct patterns. On the hub, 84c2082 took 16.5 s for 12 demands on 20,000 people, and 24 demands were killed at 300 s.
  • F-B, blocking: Belgium's OK had become conditional on its F10 follow-up.
  • F-C: _node raised a bare KeyError: 'assignment_knob' for a malformed v2 node contract.
  • F-D: activation raised AttributeError for a non-mapping input_domains[entity].
  • Everything else checked out: v1 unchanged, the predicates refactor, the F4 hash closure, and 13 of 13 mutants.
• 97c08e0 (F-B): Belgium's f10-followup.diff, committed unchanged (diff sha256 de15bc7a…).
  • The receipt unit check now reads the [BE] dispatch seam and matches ids through person_household_id-style membership columns.
  • Hub run at -n 0: test_transport_receipt_v2.py 99, test_transport_receipt_v2_kernel.py 14. Belgium's r1 OK is unconditional.
• 2f2f704: the round-2 fix (F-A, F-C, F-D; Belgium's (a), (b), (c)). It was committed after three hard-tier reviews and Belgium's OK.

  • Hall: each eligibility pattern's weights are summed as exact integers over one power-of-two denominator, 65,536 people at a time. Capacities are integers over the lcm of that denominator and the targets' denominators. Dinic replaces Edmonds–Karp. People eligible for no demand are skipped, as at 84c2082. The record and the reported set are unchanged.

    • Same host, 84c2082 → 2f2f704: 20,000 people × 12 demands, 16.5 s → 0.027 s. 4,000 × 24, 44.3 s → 0.029 s. 20,000 × 24, killed at 300 s → 0.17 s. Belgium's 100,000 × 4 shape, 0.10 s → 0.044 s.
    • Exhaustive oracle: 25,000 small and 1,200 medium cases, checked against brute force over every demand subset, give 0 failures. All 1,643 disagreements with 84c2082 are its own NumPy-integer target overflows.

  • _node validates a node's own v2 contract before it reads assignment_knob.

  • Activation and calibration inputs: a non-mapping input_domains[entity] gets the existing "needs a domain" ValueError.

  • Reviews r3a and r3b (GPT-6.1 Sol, two lenses, on the first draft): REQUEST_CHANGES. They found:

    • a test fixture that refused before its guard;
    • medium cases that were only checked differentially;
    • four wrong implementations that passed every Hall test;
    • NaN and infinite weights on ineligible people, which now raised;
    • a theorem that needed a short-flow qualifier;
    • several claims to tighten.

    All are fixed: the four witnesses are now tests, the oracle covers the medium cases, and the claims are restated.

  • Review r4 (GPT-6.1 Sol, on the fixed tree): APPROVE_WITH_NITS. It verified 281 tests, 26,200 oracle cases and all 16 mutants. Its one nit (P3) was a fifth wrong implementation, with pattern labels restarting at each chunk. test_hall_keeps_pattern_indices_aligned_across_chunks now kills it.

  • Belgium OK'd the src (sha256 20baf6fa… against 97c08e0). The commit merges cleanly with S5 6197d74 and B1 dc157a7. Receipt v2, reference selection and receipt v2 kernel pass 190/190 at -n 2.

• 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.
  • 5697584 merges main (fddbc70) through update-branch; c682c29 and 8b1f936 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.
  • CI then failed test_every_dotted_microcosm_symbol_resolves[nz] on a citation this PR inherits from Normalize donor money with exact declared factors #1395, through a bug in the shared resolve_dotted_symbol (see Normalize donor money with exact declared factors #1395). 9d699ba merges Normalize donor money with exact declared factors #1395's fix (f09ad72). With CI's import path, the hub ran test_spec_source_citations.py at 9d699ba: 139 of 139 pass.
  • Delta review of the resolver fix (GPT-6.1 Sol, job 20261029-091411): APPROVE, no blocking findings (see Normalize donor money with exact declared factors #1395); it ran the 139 citation tests at 9d699ba with CI's import path, and all pass.
  • 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; d1b513c merges it through Normalize donor money with exact declared factors #1395.
  • fea719d 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); d67f9c1 merges it through Normalize donor money with exact declared factors #1395.
  • 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 d67f9c1: every job passed (gh pr checks exit 0; run 40897573795): 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 d67f9c1, 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.

🤖 Generated with Claude Code

[MaxGhenis]

Merged by the NZ hub (session local_e407a527) at d67f9c1 with --merge. Gates: gh pr checks exit 0; MERGEABLE; not draft; no CHANGES_REQUESTED review. Reviewed head: d67f9c1. Independent delta review of the ledger_artifact listing across all five stack heads: APPROVE_WITH_NITS (Opus 5.5 in session), jobs/review-microcosm-fix5list/out-opus.md. BE re-clear clean at this head (jobs/be-reclear-1029e).