EPIC: populace-nz — New Zealand dollar take-up engine on the Axiom stack

[MaxGhenis]

Goal

Ship a working New Zealand tax-benefit microsimulation — composed as Axiom rules (rulespec-nz) × populace data, with no policyengine-nz country package — scoped first as a dollar benefit take-up engine: for each major transfer, predicted entitlement dollars vs official expenditure/caseload, with the gap decomposed by income percentile and family type. Same recipe as the Belgium pilot under #259: recalibrate the populace-us donor pool to public NZ margins, run the encoded rules through the Frame RulesEngine protocol via the Axiom adapter.

Why New Zealand now

• The rules half already exists. rulespec-nz covers the core surface (income tax, WFF, main benefits, NZ Super, accommodation supplement, WEP, disability allowances, student support, KiwiSaver, ACC, child support), with a 2026-07-06 full value audit and fixes (rulespec-nz#73). Treasury's IncomeExplorer and the AN25-01 companion code are open, maintained, official per-household EMTR oracles — validation needs no permission.
• A quantified public problem with an engaged partner. MSD/IDI research puts Working for Families take-up at ~87% and Best Start at ~97%, but Accommodation Supplement receipt among the potentially eligible at only ~44%. The policy conversation ("social cohesion") wants exactly the dollar-gap-vs-living-income framing this produces. A benefits-access funder now based in Auckland is scouting a MyFriendBen-style NZ deployment and pursuing complementary inside-IDI validation with licensed researchers.
• Unusually good open target surface. PCO legislation XML is uncopyrighted; Stats NZ Census 2023 + population estimates, HES income tables, IRD income-by-band and WfF statistics, MSD quarterly benefit fact sheets (counts) and annual-report expenditure (dollars), and Treasury TAWA published aggregates are all public. Dollar-level program targets exist, which is what a dollar take-up estimate needs.
• No licence-restricted microdata dependency in v0. Unlike BE-SILC/FRS, the v0 build reweights the populace-us donor pool to public NZ margins (the BE v0 pilot recipe; the UK-calibrated-US comparison came out close). HES CURF / IDI access are explicitly out of scope for v0 — IDI requires an NZ-based named investigator and produces confidentiality-checked outputs only; it is the inside validation channel, not the build input.

Binding architecture constraints

1. Spec-first. No nz_runtime/ Python. Country content = spec files + target profiles; anything code-shaped becomes a general operator in the core packages.
2. Rules only via the adapter. Engine access through populace-frame's RulesEngine protocol; the Axiom adapter is the only module importing the engine (shared with EPIC: populace-be — Belgium as the first Axiom-engine country #259/Implement an Axiom-backed RulesEngine adapter #260 — NZ adds no adapter code, only coverage).
3. Licence posture. v0 artifacts are fully public (donor records are US-support-stratum only and are never presented as NZ microdata — support-stratum labels ship with the artifact, as in the BE pilot). Any future HES/IDI-derived artifact gets the private-repo + destination-guard machinery first.
4. Naming. data_build_id convention; no ordinal versioning.

Phases

• Phase 0 — targets. Commit the public calibration-target inventory (docs PR attached to this epic) and pick the ~15 v1 targets: age×sex×region population, household/family composition, IRD income-by-band, benefit recipient counts by program, benefit expenditure dollars by program, AS recipients by area.
• Phase 1 — calibrate. Reweight the populace-us pool to the v1 targets (BE pilot recipe: initialize design weights at destination population scale). Gate: all v1 targets within the BE-pilot tolerance envelope (≤2%).
• Phase 2 — validate. (a) Per-case: rulespec-nz vs Treasury IncomeExplorer on the AN25-01 stylized families; (b) population: reproduce AN25-01's published EMTR distribution (94% of individuals below 50%; ~13% of couple-parent and ~30% of sole-parent families above 50%) within stated tolerance; (c) aggregate: WfF, main-benefit, NZS, and AS totals vs IRD/MSD published dollars.
• Phase 3 — first product cut. Accommodation Supplement dollar take-up gap by income percentile and family type, shown against a living-income threshold, with the ~44% receipt-rate literature as the external anchor. Publication gate: rulespec-nz#73 merged (value fixes) and the phase-2 validation green.

Children

To be filed as work starts (mirroring #259's structure):

• nz target profiles (phase 0/1)
• nz calibration surface — US recipe recalibrated to NZ margins (phase 1)
• Treasury IncomeExplorer / AN25-01 validation harness (phase 2)
• AS dollar take-up first cut (phase 3)
• rulespec-nz#74 (upstream) — child support income-shares re-encode; child support stays out of composed outputs until closed

Out of scope (follow-ups)

• IDI/inside-validation study (requires an NZ-based accredited investigator; complements this from the outside-in).
• HES CURF or any restricted microdata source stage.
• policyengine.py registration for NZ (follows the BE decision under EPIC: populace-be — Belgium as the first Axiom-engine country #259).
• Local-area (TA/SA2) calibration — national first, consistent with the local-area = filter-one-national-dataset doctrine.

Acceptance criteria

• A populace_nz v0 artifact passes calibration gates on the v1 target set (≤2% envelope) with public diagnostics.
• AN25-01 EMTR distribution reproduced within documented tolerance on the calibrated population.
• An AS dollar take-up estimate with explicit caveats (donor-pool provenance banner, program coverage list, validation status) — no take-up number publishes before rulespec-nz#73's fixes are merged and phase-2 checks pass.