Add Stats NZ 2023 Census household and family counts by regional council

[MaxGhenis]

Fills the two Census 2023 rows of the NZ source checklist (#176 packages 3–4): stats_nz/census_2023_households_by_region and stats_nz/census_2023_family_type. This is B5 of the NZ v0 plan and the last NZ source the population build was waiting on.

What this adds

288 published 2023 Census counts from Stats NZ's Place Summaries tool: 16 per place, for New Zealand, the 16 regional councils, and the publisher's separate "Area Outside Region" entry (code 99).

Section	Categories	Facts per place
Number of families and households	Families, Households	2
Tenure of household	Owned, Not owned, In family trust	3
Family type	Couple Without Children, Couple With Child(ren), One Parent With Child(ren)	3
Number of usual residents in household	One usual resident … Eight or more usual residents	8

Not emitted, but preserved in the pinned files: the Percent rows, the 2013 and 2018 periods, the Māori-ethnic-group sections and every other section.

Two things the plan asked for are not in this product, and nothing approximates them: a household-composition table (it publishes household size instead) and a social-renting split (tenure has three categories).

This departs from #176's row 3, which named the S2 ArcGIS hub regional-council layer and regc_2023 boundaries. The published ArcGIS household and family layers are SA1 and SA2 only, and this product doesn't state its boundary vintage, so the package records it as unstated. The households checklist row is therefore marked Partial, with its package box unchecked, as the population row is. Regional household composition stays open; it needs the Aotearoa Data Explorer table CEN23_FHH_038 (an API key or a manual export).

Source

• Stats NZ's Place Summaries tool, "Download data", one CSV per place: https://tools.summaries.stats.govt.nz/api/export-csv/<classification identifier>/<code>/. Each manifest records its exact URL.
• The endpoint generates the CSV on request, and the download filename carries a timestamp. The hub fetched the Auckland file twice and got identical bytes, so the content is pinned by SHA-256. Each manifest records the fetch time, HTTP status and the publisher's download filename.
• 18 files, about 400 KB each, fetched 2026-10-10. .gitattributes marks them binary, so their CRLF line endings stay byte-exact.
• Licence CC BY 4.0, per the Stats NZ copyright page, checked 2026-10-10.
• All 18 objects are published under raw/nz/stats_nz/census_2023_place_summaries/2023/…. The hub verified each by streaming it back (SHA-256 matches).

Package structure, and a question for review

Chronicle's SourceArtifactSpec selects one manifest per declarative package, and this source is 18 files. The lane kept the checklist's two package ids as roots. Each root's YAML describes New Zealand, and each rc_XX/source_package.yaml child describes one regional-council entry: 36 package members in all. Both families read the same 18 files, committed once in db/data/stats_nz/census_2023_place_summaries/ with one manifest per place.

Costs of that shape, flagged for the reviewer:

• Nested package members have no precedent in this repo. discover_source_package_dirs globs two levels, so nested members are covered by the alias map but not by discovery.
• It adds 36 packages for 288 facts.
• The two families give the same file different virtual sheet names, to keep their source-cell keys apart.

The alternative is 18 flat packages, one per place, each emitting all 16 facts: half the package count, the standard two-level layout, and no virtual sheet names, with both checklist rows pointing at the one family. The hub will restructure if review prefers that.

Invariants and how they're checked

These are scoped to this PR's 288 facts:

• One CSV row per fact. Every fact reads one row's value, with no sums. The New Zealand rows are their own facts, never a sum of regions. Households is never the sum of its categories: nationally the three tenure counts sum to 1,780,101 against 1,780,527 households, and both stand.
• Exact selection. The test declares every expected fact (place code, section, category and row identity) from literal lists, not from the package YAML, and requires the packages to select exactly that set.
• Status lineage. confidentiality_indicator and final_indicator travel with each fact. A flagged row is never emitted as a number.
• Labels as published, including Couple Without Children. Every dimension and value is labelled (Dimension labels are only checked for the UK suite: 68 of 79 other packages fail the consumer_fact.v2 rules #265).
• Reference date 7 March 2023. The product does not state its regional boundary vintage, and the package records that it is unstated.
• Area Outside Region is its own geography (region:99) and is folded into no region.

Mutants that fail the tests: a Percent row in place of a Count row, a 2018 row in place of 2023, one region's row read from another region's file, and a Māori-ethnic-group row in place of the total-population row. Byte-level CRLF mutants fail too.

Spot values, checked against the files:

• New Zealand: Households 1,780,527; Families 1,294,503; Not owned 604,884; One Parent With Child(ren) 213,534.
• Auckland Region: Households 539,490; Not owned 218,220.

Tests

• tests/test_chronicle_nz_census_households.py: 186 passed. The build lane ran it, and the hub re-ran it on the final tree.
• All 36 members pass validate-package and single-source build-suite.
• The full-bundle node is left to CI.

Bundle pins

Measured against main 244a1281:

• facts +288 (1,002,783 → 1,003,071);
• packages +36 (321 → 357);
• tables +1;
• geographies +1 (the new region:99);
• stats_nz +288, household +216, family +72, country:NZ +16, each of the 16 regions +16;
• no new sources, periods, entities or warnings.

Chronicle governance

• Agent role: ledger-source-ingestor. As in the other package PRs, the per-package files outside its allowed_paths are the alias entries in chronicle/source_package.py, db/data/**, docs/pe-nz-source-checklist.md, the changelog fragment and the bundle pins. chronicle/source_package.py changes by alias entries only.
• Deterministic checks:
  • The test file runs validate-package for all 36 members, and the source build-suite (source-cell preservation, consumer contract, raw-facts boundary) for the two national roots.
  • CI's bundle job builds every member's suite and fails on any invalid one.
  • The build lane also ran all 36 single-source suites.
• Judge verdicts: the build lane's own ledger-source-fidelity and ledger-boundary checks passed. The independent review that follows is asked to give both as named verdicts.
• Receipts: the R2 read-back is the hub's attestation. Since Add chronicle verify-raw to read back R2 artifacts against manifests #334 merged, anyone with read access can regenerate it with chronicle verify-raw --root db/data/stats_nz/census_2023_place_summaries --manifest 'manifest-*.yaml'. The pattern is needed because these manifests aren't named manifest.yaml.

Built by a GPT-6.1 Sol lane from the NZ hub's brief. The hub verified the test run, the 18 artifact hashes and the 18 R2 objects.

Review

An independent GPT-6.1 Sol review at 88770acf returned APPROVE_WITH_NITS, with "Needs Max: no", ledger-source-fidelity: PASS and ledger-boundary: PASS:

• Its own read of the 18 CSVs found all 288 facts, with 0 missing, 0 extra and 0 mismatches. All 18 files are byte-exact.
• New mutants it wrote all fail the tests: a Māori-section row with the same category, the Number of families quick-stat (which has the identical value 1,294,503), and region 99 relabelled as Canterbury.
• On the structure question, it judged nested members sound everywhere except the alias-drift guard, and flat packages "somewhat better, not clearly". It recommended merging this head and fixing discovery separately.

Fixed in f4bebe8a, with no fact, value, selector or pin change:

• the households row marked Partial, with the NZ source packages, wave 1: the populace-nz v1 16-margin surface #176 departure stated;
• the build-suite claim corrected;
• the verify-raw pattern documented;
• the stale family-README sentence replaced;
• two capitals after semicolons fixed;
• the 90 period notes now cite NZ source packages, wave 1: the populace-nz v1 16-margin surface #176 instead of the hub's brief.

Follow-up, a separate small PR:

• discover_source_package_dirs will search recursively, so the alias-drift guard (build-bundle silently skips packages whose aliases drifted from the db/data layout #78) sees nested members. The review checked this finds exactly the 367 alias targets today.
• The raw-artifact scans will match manifest*.yaml by default.

🤖 Generated with Claude Code

[MaxGhenis]

Merged by the NZ hub (session local_e407a527) at ed49432 with --merge. Gates: gh pr checks exit 0; MERGEABLE; not draft; no CHANGES_REQUESTED review. Reviewed head: ed49432. Independent GPT-6.1 Sol reviews: r1 at 88770ac APPROVE_WITH_NITS (Needs Max: no; ledger-source-fidelity PASS, ledger-boundary PASS); r2 at f4bebe8 APPROVE_WITH_NITS (judges PASS; it marked Needs Max: yes for republishing Stats NZ coverage and R2-verification notes, which the hub overrides: unchanged CC BY 4.0 republication of official counts with provenance recorded, per the precedent of the earlier NZ source packages; no estimate, number of ours or outside send); r3 at ed49432, the exact merged head, APPROVE_WITH_NITS, Needs Max: no, both judges PASS, merge-only diff equal to main plus this PR, 186 passed. Remaining nits are tracked: nested-package discovery in #338, the manifest-name scan default in #337. Reports: ~/reviews/nz-hub/jobs/review-chronicle-335/.