NZ source packages, wave 1: the populace-nz v1 16-margin surface

Lane: ledger-source-ingestor (.github/chronicle-agents.yml) — judges ledger-source-fidelity + ledger-boundary
Depends on: #175 — the R2 country layout blocks every credentialed publish; the tax-year note blocks the IRD batch; the geography rulings block the MSD and MBIE batches. The stats_nz batches (PRs 1–2) can be authored first.

Context

New Zealand has no incumbent target registry to port (unlike the UK waves) — the surface being retrieved is the populace-nz v1 calibration set: 16 margins, all public, declared in docs/nz-take-up-engine-plan.md @ de7451b, with per-source URLs, licences, and fetch-status in the companion docs/nz-calibration-targets.md (every entry live-verified 2026-07-06). All values are published official statistics (Stats NZ / IRD / MSD / MBIE) — no licensed microdata is involved.

Chronicle has zero NZ presence today. This issue authors the wave-1 packages; the nz_national profile issue is drafted and will be filed separately; wave 2 (take-up/validation surface) is #177; local geography is #178.

Sourcing note (NZ-specific): stats.govt.nz's SPA, treasury.govt.nz HTML, and catalogue.data.govt.nz bot-wall scripted clients, but the file CDNs are open (ird.govt.nz, msd.govt.nz, tenancy.govt.nz, Stats NZ /assets/Uploads/…) — pin those. Infoshare and the Aotearoa Data Explorer SPA are aggregator clues, not artifacts: pin the publisher release file, or a curated CSV extract with pinned cell geometry where only the SPA publishes the cut (Statbel precedent). Manual-download registration with the canonical URL recorded is the gov.wales-precedented fallback. Infoshare retires into ADE April 2027 — nothing here may pin an Infoshare URL.

Package inventory (margin → package)

Fifteen packages serve the 16 margins (the minimum-wage half of the earnings margin is not a chronicle fact — a statutory rate has no entity population and no honest aggregation; it is a rules parameter already encoded in rulespec-nz. Stated here so the margin accounting closes: 16 margins = 15 package families + 1 rules-side parameter).

All other packages are provenance_class: administrative except #1–#5 (census) and #15 (survey_aggregate). Units: count, nzd (free-form — no vocabulary change).

Mechanics (all precedented — follow, don't reinvent)

• Per package, the 6-file pattern: SOURCE_PACKAGE_ALIASES line (alias↔directory drift is test-enforced), artifact bytes under db/data/…, manifest.yaml, source_package.yaml, checklist row in docs/pe-nz-source-checklist.md (may be a follow-up commit — docs/** is outside this lane), re-measured tests/test_chronicle_bundle.py with the arithmetic in the commit body.
• Commit rhythm per batch: pin artifacts → author packages → record checklist rows → re-measure bundle expectations. R2 publishes land under raw/nz/… (#175) in a separate credentialed publish-raw commit per batch — designed-red on raw_artifacts_have_r2 until it lands; the credential is a PolicyEngine Cloudflare account membership + wrangler login.
• Multi-geography tables (#1, #3, #5, #14) use the whole-table orientation: one record set per publisher category, rows: carry geometry only, semantics in shared_filters/shared_constraints; declare sheets: on multi-sheet workbooks to cap source-cell cost.
• A country regression test file tests/test_nz_targets.py (Belgium's test_belgium_targets.py precedent), grown per batch.
• Gate per package: chronicle validate-package → chronicle build-suite → reports/agent_acceptance.json all-green (watch for missing_raw_r2_link, missing_concept_alignment_evidence, selected_row_only_source_parse, missing_expected_constraints).

Acceptance

• A consumer artifact built from these packages resolves every one of the 15 package families — each margin matched by period, geography level, and unit against the plan's margin table; the 16-margin accounting closes with the minimum-wage rules-side note.
• Every fact traces to publisher bytes: manifest source_url + sha256 + raw/nz/… R2 URI, cell-geometry guards, concept_evidence_url per measure.
• Deterministic checks green (source-package validation, source-cell preservation, consumer-contract validation, raw-facts boundary validation); both judges green.
• No PolicyEngine-computed values enter the store (facts-only ADR): no uprating, no rate×count, no cross-source composition. Anything computed is a populace-side declaration.

Out of scope

Wave-2 take-up/validation packages (#177); local geography (#178); the nz_national profile (forthcoming issue); all populace-side consumption (tracked under microcosm#343).

Sizing

15 packages ≈ 5 PRs: (1) stats_nz demographic anchor — #1, #2, #15 first, because calibration initializes design weights at destination population scale; (2) census structure — #3–#5, establishing the hub-CSV and ADE-curated-extract patterns; (3) IRD — #6–#9, establishing the NZ tax-year convention in one review; (4) MSD — #10–#13, carrying the W&I-region ruling and the one PDF package; (5) MBIE rents alone — #14, the big multi-geography whole-table.

Start with the .github/chronicle-agents.yml lane, the package inventory, and the existing source-package precedents. Run chronicle validate-package and inspect tests/test_chronicle_bundle.py plus the planned tests/test_nz_targets.py while implementing one sized batch. Done means all 15 package families resolve, publisher provenance and geometry are preserved, and the validation judges are green.