Add the New Zealand spec package for the graph build (NZ v0, G2)

changelog.d/nz-spec-package-graph.added.md

@@ -0,0 +1 @@
+Add the New Zealand spec package (`build/nz/`) laid out for the graph build: the populace-us Build P donor pin, region-layer geography contract, gates (thresholds await D1), release and export contracts, three separate reference sets (calibration, pre-calibration, hold-out; every row an unactivated placeholder), and `legacy_json` resources for the Axiom rules bindings at a rulespec-nz main commit, the scenario grid, the reg 17/18 rate bridge, the benefit-unit rule, the USD to NZD bridge and the territorial-authority to Accommodation Supplement area crosswalk (shares still a harvest item). Salvaged from #821 without its WFF Budget-transport stage or its pins to an unmerged rulespec-nz commit; `assign_nz_regions` and `nz_region_geography_gate` join the F0 contract-only kernel ids.

docs/nz-calibration-targets.md

@@ -24,7 +24,7 @@ Ranked by calibration value for a dollar-level take-up estimate. **$** = enables
 | 2 | **Benefit expenditure by program, in dollars** | MSD *Annual Report 2025* — *Benefits or Related Expenses* schedule | $ | The dollar control totals: NZS $23.19B, Jobseeker+Emergency $4.64B, Accommodation Assistance $2.23B, SLP $2.67B, Sole Parent $2.26B, Hardship $0.75B, WEP $0.56B (2024/25). Explicit CC BY 4.0. [FETCH-OK] |
 | 3 | **Benefit recipient counts by benefit × age × ethnicity × duration × region** | MSD *Quarterly Benefit Fact Sheets* (Mar 2026) | # | Recipient marginals for every main benefit + supplementary (AS, DA, TAS). National→region→TA→service-centre. Count-only. [FETCH-OK] |
 | 4 | **Working for Families: expenditure, families, average claim by credit type** | IRD *Working for Families statistics Sept 2025* | $ / # | WfF dollar + count margins by FTC/IWTC/MFTC, family size (2020+), recipient income distribution (2020+). [FETCH-OK] |
-| 5 | **Modelled dollar amounts per program by income position** | Treasury *DistributionExplorer* data CSVs (HES24 + BEFU25, TY25–29) | $ / # | TAWA-modelled $ per program (AS, Core Benefits, FTC, IWTC, MFTC, BestStart, WFF, WEP, FamilyBoost, NZ Super, Income Tax) × Household/Family/Individual × income quantile/band, with weighted population per cell. The **full-entitlement denominator** for the take-up gap. MIT. [FETCH-OK] |
+| 5 | **Modelled dollar amounts per program by income position** | Treasury *DistributionExplorer* data CSVs (HES24 + BEFU25, TY25–29) | $ / # | TAWA-modelled $ per program (AS, Core Benefits, FTC, IWTC, MFTC, BestStart, WFF, WEP, FamilyBoost, NZ Super, Income Tax) × Household/Family/Individual × income quantile/band, with weighted population per cell. AS values are assigned by TAWA's take-up model, so for AS this is an independent comparison, not full entitlement; TAWA assumes full take-up for the WFF credits ([TAWA methodology](https://treasury.govt.nz/sites/default/files/2024-08/tawa-model-methodology.pdf), "Modelling take-up"). A validation comparator only, never a calibration target (Gaps / risks, item 6). MIT. [FETCH-OK] |
 | 6 | **Age × sex × region / territorial authority population** | Stats NZ *Subnational population estimates at 30 June 2025* (2023-base) | # | Primary demographic reweighting frame: 16 regions / 67 TAs / 21 Auckland boards by age×sex. [SNIPPET; prior-quarter direct xlsx FETCH-OK] |
 | 7 | **Accommodation Supplement recipients + average payment** | MSD Fact Sheets (counts, by W&I region/TA) + Annual Report (Accommodation Assistance $2.23B) | $ / # | AS is the take-up wedge (~44% receipt among potentially eligible). Count × implied average payment = AS dollar base. [FETCH-OK] |
 | 8 | **Household composition / family type** | Stats NZ 2023 Census — families, households and housing | # | Household/family-type marginals (1-family 67.7%; 1,780,527 total households). [SNIPPET] + ArcGIS/DataFinder [FETCH-OK for hub] |
@@ -37,7 +37,7 @@ Ranked by calibration value for a dollar-level take-up estimate. **$** = enables
 | 15 | **Minimum wage series + average weekly earnings** | MBIE minimum wage ($23.95 from Apr 2026) + Stats NZ QES/LEED | $ | Anchors the bottom of the earnings distribution and the national/TA earnings margin. [FETCH-OK min wage; SNIPPET QES/LEED] |
 
 **Dollar-level calibration design (numerator/denominator):**
-- **Denominator (full-entitlement modelled $):** Treasury DistributionExplorer CSVs (#5) — dollars per program by income position, assuming full take-up.
+- **Denominator (full-entitlement modelled $):** our own rules × calibrated population. Treasury DistributionExplorer CSVs (#5) are TAWA-modelled; AS values assigned by TAWA's take-up model; an independent comparison, not full entitlement, for AS; TAWA assumes full take-up for the WFF credits ([TAWA methodology](https://treasury.govt.nz/sites/default/files/2024-08/tawa-model-methodology.pdf), "Modelling take-up").
 - **Numerator (actual $ paid):** MSD Annual Report expenditure schedule (#2) and AN24/01 fiscal totals (#10); IRD WfF expenditure (#4) for in-work credits.
 - **Average payment** = program expenditure (#2) ÷ recipient count (#3) distributes dollars across the calibrated population.
 - **Take-up gap** = actual paid vs full-entitlement modelled, anchored empirically by the WfF ~87% and AS ~44% take-up studies (M5/M6 below).
@@ -101,7 +101,7 @@ Notes: **I1, I3, I4 are the load-bearing IRD targets.** IRD income tables are **
 
 ## 4. Treasury
 
-Public analysis ships as **code + data on GitHub** and interactive tools. **Treasury outputs assume full take-up** — they are the **denominator** of the take-up gap, not actuals.
+Public analysis ships as **code + data on GitHub** and interactive tools. DistributionExplorer (T1) outputs are TAWA-modelled; AS values assigned by TAWA's take-up model; an independent comparison, not full entitlement, for AS and for core benefits (paid only to administrative recipients); TAWA assumes full take-up for the WFF credits ([TAWA methodology](https://treasury.govt.nz/sites/default/files/2024-08/tawa-model-methodology.pdf), "Modelling take-up"). They are not actuals.
 
 | # | Dataset | Access | Contents | Period | Licence | Status |
 |---|---|---|---|---|---|---|
@@ -144,7 +144,7 @@ Also: `github.com/Treasury-Analytics-and-Insights/Calibration` (MIT, 2018) — "
 3. **AS by Area 1–4 is not a standing series** — need TA→Area crosswalk (H4) or OIA; known break at 2027-04-01 (H4c redraw).
 4. **IRRS dollars unconfirmed in open dashboard** — source from Kāinga Ora/Vote Housing.
 5. **Benefit expenditure is annual + national only** — regional dollars must assume uniform average payment within benefit (flag as modelling assumption).
-6. **Treasury distributional outputs assume full take-up** — denominator, not actuals; never calibrate to them as actuals.
+6. **Treasury DistributionExplorer is TAWA-modelled; AS values assigned by TAWA's take-up model; an independent comparison, not full entitlement.** Its WFF credits assume full take-up. Never actuals, never a calibration target.
 7. **FamilyBoost unvalidatable** against admin data today.
 8. **Household/family projections stale (2013-base)** — use census counts.
 9. **Portal migration risk**: Infoshare → ADE Time Series (April 2027) will change URLs/schemas; pin to file CDNs.