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).

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: validate-package and the build-suite acceptance gates (source-cell preservation, consumer contract, raw-facts boundary) pass for all 36 members inside the test file.
• 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. chronicle verify-raw (Add chronicle verify-raw to read back R2 artifacts against manifests #334) will let anyone with read access regenerate it.

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. An independent review follows before merge.

🤖 Generated with Claude Code