[MaxGhenis]

Targets main and lands after #1394. The UK Budget hold on shared compile-module hashes, which applied because implementation hashes that cover the edited modules move, ended at 2026-10-29 12:00Z. Review round 1 asked for changes; they are in b675b7a and 4f333f2, and the delta review approved them with wording nits (see Review). Head db02ae8: 044f179 merges #1394's head, which carries #1382's fix4 (Belgium OK'd it 10/26), and db02ae8 applies the two wording nits.

What this does (G8-w2a)

Adds exact, declared normalization of donor money: the USD-to-NZD conversion and the ageing of donor-period amounts, applied once per lineage. No NZ graph node runs it yet; G8-w3 wires it.

• Shared module, money_normalization.py. It validates a complete declaration with no defaults:
  • a cited decimal-text rate, or a feed-replayed rate with its expected decimal, and an explicit quote direction;
  • half-even rounding at both stages, and the donor money period with its basis and evidence;
  • the one target_period every applied factor must age money to;
  • every transported money concept in exactly one roster (normalized, quantile-mapped or pending). A concept dropped in transport can't be normalized, though a quantile-mapped or pending row may name one;
  • per-family factors for each profile, or an explicit identity with a reason.
  • It applies the declaration with exact fractions for both rounding stages and the receipt sums. Non-finite amounts refuse, and every cents companion is checked against int64 bounds at both stages.
• Transport kernel, money.normalize@1 (transport/money_kernels.py):
  • replays its selected factors against the authenticated feed;
  • refuses a donor money period that differs from CREATE's, or is null;
  • writes exactly its declared columns, each with an integer-cents companion and an exact receipt;
  • the profile knob selects each variant's factor explicitly. An absent knob selects the declared central profile; an unknown profile, or a family missing a profile's factor, refuses.
  • Its implementation hash binds the pure module and reference_factors. It is registered with the population kernels and admitted to SKELETON_KERNELS.
• CREATE and the donor reader.
  • DonorBank.time_period reads the donor H5's _time_period: a one-row integer series, as the exporter writes it, or absent. A malformed value refuses.
  • CREATE records it as donor_time_period in its metadata and receipt, in every country (Belgium's ruling: general, not opt-in).
• Producer checks (opt-in). Only a spec that declares a money_normalization resource is checked:
  • activation names every consumed money column without exactly one producer;
  • after each graph pass of the ancestry guard, compose refuses a second normalization along structural population inheritance, including a currency conversion followed by normalization;
  • cross-population evidence edges don't change money ownership, and new destination outputs count as derived money.
• Factors. reference_factors gains the additive money_normalization_input purpose, and a public resolve_feed_operand, which resolves the feed-selected money rate. Its validity rules are untouched.
• NZ.
  • money_normalization.json is the single source of the USD-to-NZD rate; currency_bridge.json points to it.
  • The generator adds three calendar-2024 donor factors (central, high, low), with the existing factors' validity. The existing factor records and the v1/v2 reference receipts are unchanged.
  • Ten columns are normalized and three are quantile-mapped. The declared target_period is 2027 (tax year 2026-27), the target of the donor factors and of every reference-profile factor. The scenarios' default aging_index is the declaration's central profile. The declaration is inactive: no NZ graph node reads it yet.
  • Ageing non-wage money by AWE growth is disclosed per family as provisional, pending a methodology decision. The factors use Stats NZ QES observations through June 2026, then Treasury PREFU 2026 forecast AWE growth (2.7%, 0.5 points lower and higher for low and high).
  • Ruled 2026-10-26 (d1981, option A): AWE ageing of the listed non-wage donor columns is adopted as a disclosed interim convention, with hold-fixed (factor 1) run beside it as a pre-declared sensitivity. This PR's code already applies A. A follow-up after the stack lands changes the "provisional pending Max's ruling on non-wage ageing (H3)" disclosure strings in nz/money_normalization.json (and the test that pins them) to cite d1981, and checks that the hold-fixed sensitivity is wired.
  • The golden changes only identity fields: the fingerprint, the resource list and four resource hashes.

Invariants (tested)

1. Exact arithmetic. Normalization equals an independent Fraction oracle over random amounts, rates, factors and quote directions (property), plus hand cases for half-even rounding at each step. Decimal context never rounds products, quotients or receipt sums.
2. Bounded two-step rounding. For a factor f, two-step rounding differs from one-step by at most floor(1 + f/2) cents, so by at most one cent for every factor below 2 (property). The three declared factors are all below 2, and their difference is at most one cent (property). The four-cent hand case gives 7 FX cents, then 8 indexed cents.
3. Order. Permuting rows commutes with normalization (property).
4. Exact receipts. Receipts record exact sums, residuals and identities. Identity families name their reason and carry no factor residual.
5. Refusals. Non-finite amounts, int64 overflow at either step, negative amounts in unsigned columns, rates given as JSON numbers, unknown or unmapped families, and normalizing twice (property) all refuse.
6. One producer per money column. With the resource declared:
   • a raw donor read without its normalizer is a gap;
   • a second normalization in one lineage, or currency then normalization, refuses;
   • variant lineages are independent;
   • S0 and V1 each normalize once, despite a cross-population baseline artifact.
7. Opt-in is byte-stable. For a spec without the resource, the preflight reads nothing, and composition and activation are byte-identical with the hooks removed.
8. Factors are authenticated. A self-consistent tampered factor refuses on feed replay. Without a feed pin, the factor source commit must be authenticated. A profile-input or tax-year factor is never applied to donor money.
9. The donor period is consistent. A mismatched or null donor_time_period refuses at the normalizer. The reader returns the exporter's value and refuses a malformed one.
10. One destination period. Every factor applied by money.normalize@1 has target_period equal to the declaration's, so no two families age money to different periods; a non-integer target_period refuses. The public arithmetic helper takes factors as given; its one production caller, the kernel, checks every selected factor first.
11. Dropped concepts are never normalized. Listing one as normalized refuses at validation, not at run time.

Cross-country

• Belgium OK'd every transport hunk (10/24), with two rulings: donor_time_period is general, and the _time_period refusal is fine for BE, which pins the same donor file as NZ (sha256 48b9d479…; the hub read _time_period as a one-row int64 series, value 2024).
• CREATE runs nowhere in production yet. No packaged country spec declares a transport_graph resource, so CREATE and the normalizer run only in test fixtures today. The new receipt key and the CREATE node-key change reach a country when its graph lands.
• Elsewhere, a one-time cache miss. Edited modules move any implementation hash that covers them (CREATE's covers population_kernels.py and frame/transport.py), under the same 10/29 hold.

Review

• Round 1 (Claude Opus 5.5, at 7a2aa81): REQUEST_CHANGES. It ran as the review fallback; no Codex lane had capacity.
  • It found no defect in the arithmetic, factor authentication, donor period, producer checks, S5 placement, profile selection or NZ data. Its own Fraction oracle matched the module on 21,420 values.
  • B1–B3: three tests went stale in the rebases. B1: a planted rulespec revision targeted the moved IRS source record. B2: money_normalization.json cited repository line numbers. B3: the receipt digests predated Add exact income-band intervals and boundary diagnostics #1394's interval document. The hub's validation had found the same three. Fixed in b675b7a: the evidence names symbols, and a new AST test checks the cited constant and call expressions against the code.
  • m1 (a dropped concept validated as normalized) and m4 (nothing bound the destination period) are fixed in 4f333f2, along with the n1–n4 wording.
  • m2 is fixed in part: the scenario default/central profile check is added. Lineage completeness is owed by w3 (below), as is m3's run-entry extension.
• Round 2 (GPT-6.1 Sol, at 4f333f2): APPROVE_WITH_NITS.
  • B1–B3, m1, m4 and the m2 check are fixed. The three receipt digests equal round 1's.
  • DROP refuses only in the normalized roster.
  • Every donor and profile factor targets 2027, meaning tax year 2026-27, and no other declaration needed the new field.
  • Its Fraction oracle matches on 21,420 values, all 11 producer outcomes are unchanged, and the rebase is a replay.
  • Its two nits were wording, fixed above. The AST test checks the cited constant and call expressions, not every fact. Invariant 10 is scoped to the kernel, because the arithmetic helper takes factors as given. The module docstring and the AST test's comment get the same wording in db02ae8.
• BE re-clear on the landing head (see Landing).

Verification

• Lane (GPT-6.1 Sol, before the rebases onto fix3 and r2b): 5 files passed; 4 mutants killed (double_normalize, float_round, ty2024_factor_on_donor, ancestor_count_check).
• Hub, at 7a2aa81 with Add exact income-band intervals and boundary diagnostics #1394's dtype fix, one file per process at -n 0: 22 files.
  • 20 pass, including test_money_normalization.py 113, test_transport_money_kernels.py 40, test_transport_donor.py 94 (2 skipped), test_transport_composed_graph.py 166 and test_transport_entitlement_graph.py 67.
  • test_nz_spec_package.py (2 failed) and test_reference_profiles.py (3 failed) failed on B1–B3.
  • 13 of 13 mutants were killed with passing controls and verified restoration: the lane's four, rerun, and fx_on_quantile_column, skip_factor_replay, omit_module_from_hash, ignore_donor_period, rate_as_float, preinverted_rate, silent_identity_family, drop_rule_in_producer_check and preflight_without_optin.
  • ci_test_plan.py verify, graph_acceptance_burndown.py --verify and both generators' --check pass.
• Hub, after b675b7a: the eight affected files pass: test_nz_spec_package.py 1,201, test_reference_profiles.py 123, test_country_spec.py 136, test_money_normalization.py 113, test_transport_money_kernels.py 40, test_nz_money_normalization.py 15, test_spec_only_country_packages.py 18 and test_spec_engine_country_bundles.py 21. Three source mutants of the facts the new AST test cites (a different PERIOD, a literal time_period, no int cast) each fail it.
• Hub, after 4f333f2: a fleet disk hold blocked pytest, so the new and affected tests were called in-process: 29 calls pass. In-memory mutants removing the DROP refusal, the target-period check or the target-period validation each fail their test. ruff, format and git diff --check are clean, and the golden diff is identity fields only.
• Round 2 reviewer, at 4f333f2:
  • Under pytest: test_money_normalization.py 123, test_nz_money_normalization.py 17 and test_reference_profiles.py 123 pass.
  • Then disk fell below 50 GB. Called directly, these pass: test_transport_money_kernels.py (40), test_country_spec.py (136), and the RulespecPin and SourceCitations classes of test_nz_spec_package.py (1,123).
• Rerun test_transport_money_kernels.py, test_country_spec.py and test_nz_spec_package.py under pytest once disk allows. CI runs the whole suite when the PR targets main.
  • The hub ran them at 4f333f2 on 2026-10-25, each in full at -n 0: 40, 136 and 1,201 passed.
• Hub at db02ae8, after the fix4 merge, one file per process at -n 0: test_country_spec.py 136, test_nz_spec_package.py 1,201, test_transport_money_kernels.py 40, test_money_normalization.py 123, test_nz_money_normalization.py 17, test_transport_composed_graph.py 172 and test_spec_engine_country_bundles.py 21 passed.
• Merge Add exact income-band intervals and boundary diagnostics #1394's head (044f179). Belgium OK'd it; the merged transport/cli.py is c4ddcb4's blob (6f42b3b0) 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.
• Batch delta review of the fix4 merges (GPT-6.1 Sol, at this head, db02ae8): APPROVE, no findings. It rebuilt each merge with git merge-tree (only the conflicted NZ golden differs), attributed the golden key by key, checked Belgium's two conditions and the wording commits, and ran test_country_spec.py 136, test_nz_money_normalization.py 17 and the 12 currency-check tests of test_transport_composed_graph.py.

Owed by G8-w3

When w3 wires money.normalize@1 into the NZ graph:

• it extends cli._require_current_run_factors to the selected money factors, with an expiry test. The kernel is shared and admitted to SKELETON_KERNELS, so the run-entry extension should be country-neutral (review m3);
• it adds a differential test that the node's profile_selection equals the scenario knobs;
• it checks lineage completeness: each scenario's lineage has a normalizer carrying that scenario's knobs, so a normalizer only in the shared version can't age V1/V2 at the central factor (review m2);
• it budgets for the exact path's cost, about 144 µs per value under load, once per lineage (review n5).
• it adds a test that every NZ V1–V5 variant node id appears in entitlement._rows(spec)[0], so no variant can bypass S5's extension-row checks (promised to Belgium for Let transport specs declare pre-calibration stages #1392).

Until then, the donor factors carry the same validity window as the IRD factors the run-entry check already covers.

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.
• c203c16 merges main (fddbc70) through update-branch; 4a27e00 and 0912537 merge Add feed-derived NZ reference ageing factors (G8-r2a) #1382's CI import fix (two test files imported microcosm_build.reference_factors, a path CI doesn't provide). 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 one test. test_every_dotted_microcosm_symbol_resolves[nz] could not resolve this PR's citation microcosm.frame.adapters.policyengine_us.PolicyEngineUSEngine._write_and_verify in nz/money_normalization.json, the first citation in any package that reaches through a class. The shared resolve_dotted_symbol (test_support/microcosm_build/spec_source_citations.py, from Cite US and UK spec sources by symbol or at a commit, never by a drifting line #1407) imports the longest module prefix and walks the rest with getattr. Importing ...policyengine_us.PolicyEngineUSEngine fails with the class path as the missing module's name, and the resolver re-raised any error that didn't name the exact prefix it tried.
• f09ad72 lets the resolver fall back past a parent that isn't a module, as NZ's own package-test resolver already did, and still re-raises a missing dependency of a module that exists. A citation whose only importable prefix is the top-level package still raises ModuleNotFoundError, as the existing microcosm.no_such_shard... case requires. A new test resolves an enum member and a method through their classes. Restoring the old check makes the nz case fail; two mutants of the new check each fail a test.
• Delta review of f09ad72 (GPT-6.1 Sol, job 20261029-091411): APPROVE, no blocking findings. Both new cases resolve to the expected objects; a module that exists but imports a missing dependency still re-raises that error; all 39 unique country citations resolve to the same objects as pydoc.locate; and restoring the old check fails both new cases and the nz citation test.
• 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; e35612f merges it through Add exact income-band intervals and boundary diagnostics #1394.
• 3ee4752 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); 3f10e53 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 3f10e53: every job passed (gh pr checks exit 0; run 40897190314): 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 3f10e53, 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.

Merge order

#1375 → #1382 → #1394 → this → w1 → S5 (#1392) → w2b.

🤖 Generated with Claude Code

[MaxGhenis]

Merged by the NZ hub (session local_e407a527) at 3f10e53 with --merge. Gates: gh pr checks exit 0; MERGEABLE; not draft; no CHANGES_REQUESTED review. Reviewed head: 3f10e53. 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).