Bind NZS co-residence from household composition (H2)

docs/concept-coverage/axiom-nz.md

@@ -3,16 +3,16 @@
 Engine version `6fe181fc4c65763150fe97501ef3443774e64869`; concept schema `5a55669d0447`. Generated by `tools/refresh_concept_coverage.py`; do not edit by hand.
 
 - Engine inputs: 668
-- Fed by a concept: 89
+- Fed by a concept: 90
 - Structural: 0
-- Uncovered: 579
+- Uncovered: 578
 - Mapped but missing from the engine: 0
 
 ## Inputs each concept feeds
 
 | Concept | Engine inputs |
 |---|---|
-| `fact:person.age` | `accommodation_supplement_has_dependent_children` (Family)<br>`accommodation_supplement_has_two_or_more_dependent_children` (Family)<br>`accommodation_supplement_sole_parent` (Family)<br>`caregiver_age_years` (Person)<br>`childcare_assistance_dependent_children_count` (Person)<br>`community_services_card_dependent_children_count` (Person)<br>`community_services_card_person_age_years` (Person)<br>`disability_allowance_dependent_children_count` (Person)<br>`disability_allowance_person_age_years` (Person)<br>`disability_allowance_person_is_sole_parent` (Person)<br>`in_work_tax_credit_allowed_children_count` (Family)<br>`in_work_tax_credit_person_age` (Family)<br>`jobseeker_applicant_age` (Person)<br>`jobseeker_has_dependent_child` (Person)<br>`jobseeker_support_applicant_age` (Person)<br>`jobseeker_support_dependent_children_count` (Person)<br>`nz_super_has_dependent_children` (Person)<br>`nz_super_person_age` (Person)<br>`sole_parent_applicant_age` (Person)<br>`sole_parent_caring_for_dependent_children_under_age_limit` (Person)<br>`sole_parent_is_mother_or_father_or_child_regarded_as_child` (Person)<br>`student_allowance_has_children` (Person)<br>`student_allowance_student_age` (Person)<br>`supported_living_applicant_age` (Person)<br>`supported_living_caring_applicant_age` (Person)<br>`supported_living_caring_applicant_has_dependent_child` (Person)<br>`supported_living_payment_applicant_age` (Person)<br>`supported_living_payment_dependent_children_count` (Person)<br>`wff_dependent_children_principal_caregiver_count` (Family)<br>`wff_person_age` (Family)<br>`winter_energy_payment_has_dependent_children` (Person)<br>`winter_energy_payment_person_age` (Person)<br>`young_person_age_years` (Person)<br>`young_person_has_dependent_child` (Person)<br>`young_person_has_dependent_child_for_part6_rates` (Person)<br>`young_person_is_parent_or_step_parent_of_dependent_child` (Person) |
+| `fact:person.age` | `accommodation_supplement_has_dependent_children` (Family)<br>`accommodation_supplement_has_two_or_more_dependent_children` (Family)<br>`accommodation_supplement_sole_parent` (Family)<br>`caregiver_age_years` (Person)<br>`childcare_assistance_dependent_children_count` (Person)<br>`community_services_card_dependent_children_count` (Person)<br>`community_services_card_person_age_years` (Person)<br>`disability_allowance_dependent_children_count` (Person)<br>`disability_allowance_person_age_years` (Person)<br>`disability_allowance_person_is_sole_parent` (Person)<br>`in_work_tax_credit_allowed_children_count` (Family)<br>`in_work_tax_credit_person_age` (Family)<br>`jobseeker_applicant_age` (Person)<br>`jobseeker_has_dependent_child` (Person)<br>`jobseeker_support_applicant_age` (Person)<br>`jobseeker_support_dependent_children_count` (Person)<br>`nz_super_has_dependent_children` (Person)<br>`nz_super_person_age` (Person)<br>`nz_super_shares_residence_with_person_at_least_adult_age` (Person)<br>`sole_parent_applicant_age` (Person)<br>`sole_parent_caring_for_dependent_children_under_age_limit` (Person)<br>`sole_parent_is_mother_or_father_or_child_regarded_as_child` (Person)<br>`student_allowance_has_children` (Person)<br>`student_allowance_student_age` (Person)<br>`supported_living_applicant_age` (Person)<br>`supported_living_caring_applicant_age` (Person)<br>`supported_living_caring_applicant_has_dependent_child` (Person)<br>`supported_living_payment_applicant_age` (Person)<br>`supported_living_payment_dependent_children_count` (Person)<br>`wff_dependent_children_principal_caregiver_count` (Family)<br>`wff_person_age` (Family)<br>`winter_energy_payment_has_dependent_children` (Person)<br>`winter_energy_payment_person_age` (Person)<br>`young_person_age_years` (Person)<br>`young_person_has_dependent_child` (Person)<br>`young_person_has_dependent_child_for_part6_rates` (Person)<br>`young_person_is_parent_or_step_parent_of_dependent_child` (Person) |
 | `fact:person.legal_marital_status` | `sole_parent_marriage_or_civil_union_dissolved` (Person)<br>`sole_parent_spouse_or_partner_died` (Person) |
 | `fact:person.partner_person_id` | `accommodation_supplement_has_dependent_children` (Family)<br>`accommodation_supplement_has_two_or_more_dependent_children` (Family)<br>`accommodation_supplement_in_relationship` (Family)<br>`accommodation_supplement_sole_parent` (Family)<br>`community_services_card_person_married_or_partnered` (Person)<br>`disability_allowance_person_in_relationship` (Person)<br>`has_relationship_partner` (Person)<br>`jobseeker_support_single` (Person)<br>`nz_super_in_relationship` (Person)<br>`nz_super_single` (Person)<br>`nz_super_single` (Person)<br>`sole_parent_is_single` (Person)<br>`student_allowance_has_partner` (Person)<br>`student_allowance_lives_with_partner` (Person)<br>`supported_living_payment_single` (Person)<br>`winter_energy_payment_single` (Person)<br>`young_person_is_in_relationship` (Person) |
 | `fact:person.parent_1_person_id` | `accommodation_supplement_has_dependent_children` (Family)<br>`accommodation_supplement_has_two_or_more_dependent_children` (Family)<br>`accommodation_supplement_sole_parent` (Family)<br>`childcare_assistance_dependent_children_count` (Person)<br>`community_services_card_dependent_children_count` (Person)<br>`disability_allowance_dependent_children_count` (Person)<br>`disability_allowance_person_is_sole_parent` (Person)<br>`in_work_tax_credit_allowed_children_count` (Family)<br>`jobseeker_has_dependent_child` (Person)<br>`jobseeker_support_dependent_children_count` (Person)<br>`nz_super_has_dependent_children` (Person)<br>`sole_parent_caring_for_dependent_children_under_age_limit` (Person)<br>`sole_parent_is_mother_or_father_or_child_regarded_as_child` (Person)<br>`student_allowance_has_children` (Person)<br>`supported_living_caring_applicant_has_dependent_child` (Person)<br>`supported_living_payment_dependent_children_count` (Person)<br>`wff_dependent_children_principal_caregiver_count` (Family)<br>`winter_energy_payment_has_dependent_children` (Person)<br>`young_person_has_dependent_child` (Person)<br>`young_person_has_dependent_child_for_part6_rates` (Person)<br>`young_person_is_parent_or_step_parent_of_dependent_child` (Person) |
@@ -138,9 +138,9 @@ Engine version `6fe181fc4c65763150fe97501ef3443774e64869`; concept schema `5a556
 
 `kiwisaver_selected_employee_contribution_rate (Person)`
 
-### nz/statutes/new_zealand_superannuation/core.yaml (11)
+### nz/statutes/new_zealand_superannuation/core.yaml (10)
 
-`nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors (Person)`, `nz_super_birth_year (Person)`, `nz_super_born_on_or_before_30_june_of_birth_year (Person)`, `nz_super_elected_weekly_compensation_instead_of_superannuation (Person)`, `nz_super_ordinarily_resident_in_new_zealand_on_application (Person)`, `nz_super_overseas_application_residence_exception_applies (Person)`, `nz_super_principal_residence_is_qualifying_accommodation (Person)`, `nz_super_resident_present_since_age_20_new_zealand_years (Person)`, `nz_super_resident_present_since_age_20_total_years (Person)`, `nz_super_resident_present_since_age_50_total_years (Person)`, `nz_super_shares_residence_with_person_at_least_adult_age (Person)`
+`nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors (Person)`, `nz_super_birth_year (Person)`, `nz_super_born_on_or_before_30_june_of_birth_year (Person)`, `nz_super_elected_weekly_compensation_instead_of_superannuation (Person)`, `nz_super_ordinarily_resident_in_new_zealand_on_application (Person)`, `nz_super_overseas_application_residence_exception_applies (Person)`, `nz_super_principal_residence_is_qualifying_accommodation (Person)`, `nz_super_resident_present_since_age_20_new_zealand_years (Person)`, `nz_super_resident_present_since_age_20_total_years (Person)`, `nz_super_resident_present_since_age_50_total_years (Person)`
 
 ### nz/statutes/new_zealand_superannuation/special_rates.yaml (13)
 

docs/nz-reporting-classifiers-method.md

@@ -63,9 +63,12 @@ weighted share of every fixed cell must be reported for every scenario and
 variant. These fixed memberships preserve comparisons even when variant cells
 are no longer weighted tenths.
 
-The disclosure on New Zealand Superannuation remains material: the current
-shared-residence input defaults false, overstating payments to single people
-who share a home and moving those units upward in the income ranking.
+The disclosure on New Zealand Superannuation records an understatement. The
+shared-residence input reads household composition, and the input for exempt
+co-resident adults defaults false, so a single person whose only co-resident
+adults are exempt dependent children or temporary visitors gets the sharing
+rate. That understates their payments and moves those units downward in the
+income ranking.
 
 ## A2 Receipt group
 

packages/microcosm-build/src/microcosm/build/nz/axiom_input_closure.json

@@ -943,7 +943,7 @@
    "input": "nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors",
    "class": "defaulted",
    "value": false,
-   "reason": "Read only when the residence is shared, which is defaulted false.",
+   "reason": "nz_super_living_alone (s 4A) reads this input only when nz_super_shares_residence_with_person_at_least_adult_age is true, and the axiom:nz concept binding now derives that input from household composition: another person in the same household is aged 18 or over. With this input false, every person who has no partner (nz_super_single) and shares a home with an adult gets the sharing rate, nz_super_single_not_living_alone_weekly_rate_before_tax (Schedule 1 Part 1 clause 1(b)). That includes a person whose only co-resident adults are exempt dependent children or temporary visitors. Section 4A counts that person as living alone, so this default understates NZS for that group. S5's reg 17 superannuitant base rate (as_rate_bridge.json) adds the same weekly amount for a single superannuitant unit, so the default lowers that base rate for the group too.",
    "citation": "New Zealand Superannuation and Retirement Income Act 2001 s 4A (nz_super_living_alone)",
    "new_default": true
   },
@@ -1048,11 +1048,8 @@
    "rulespec_path": "nz/statutes/new_zealand_superannuation/core.yaml",
    "entity": "Person",
    "input": "nz_super_shares_residence_with_person_at_least_adult_age",
-   "class": "defaulted",
-   "value": false,
-   "reason": "Household composition is not read into this person-level input in v0 (no mapping transform flags another adult in the household), so every single person gets the s 4A living-alone rate; this overstates NZS for singles who share a home. The receipt layer reads NZS eligibility, not the amount; if the reg 17 superannuitant bridge reads the amount (method card MC11), this default matters there too.",
-   "citation": "New Zealand Superannuation and Retirement Income Act 2001 s 4A (nz_super_living_alone)",
-   "new_default": true
+   "class": "encoded",
+   "encoded_by": "concept_binding"
   },
   {
    "rulespec_path": "nz/statutes/new_zealand_superannuation/core.yaml",

packages/microcosm-build/src/microcosm/build/nz/concept_mapping.json

@@ -411,6 +411,21 @@
         "kind": "identity"
       }
     },
+    {
+      "canonical_input": "nz:statutes/new_zealand_superannuation/core#input.nz_super_shares_residence_with_person_at_least_adult_age",
+      "concepts": [
+        "fact:person.age"
+      ],
+      "engine_entity": "Person",
+      "engine_input": "nz_super_shares_residence_with_person_at_least_adult_age",
+      "module": "nz/statutes/new_zealand_superannuation/core.yaml",
+      "note": "nz/statutes/new_zealand_superannuation/core.yaml rule nz_super_living_alone (New Zealand Superannuation and Retirement Income Act 2001 s 4A): 'nz_super_single and nz_super_principal_residence_is_qualifying_accommodation and (not nz_super_shares_residence_with_person_at_least_adult_age or nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors)'. The binding returns true when at least one other person with the same frame household id is aged min_age or over. min_age 18 copies parameter nz_super_living_alone_adult_age in the same module (18 from 2026-04-01, source s 4A(3) and (4)) by hand: no RuleSpec formula reads that parameter, so nothing checks min_age against it, and a change to the parameter needs a matching edit here. Differences: the frame's household stands in for the statute's residence, so the binding counts every other person aged 18 or over who carries the person's household id, and misses an adult who shares the residence under another household id; it counts a partner, but nz_super_living_alone requires nz_super_single and nz_super_ordinary_weekly_rate_before_tax branches on nz_super_single first, so the rate never reads a partnered person's value; it counts adult dependent children and temporary visitors, whom nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors carves out, and the input closure defaults that input to false; ages are completed years at the survey reference date, so a co-resident who turns 18 between that date and the assessment reads differently; a person with no household id reads false.",
+      "relation": "approximate",
+      "transform": {
+        "kind": "coresident_adult",
+        "min_age": 18
+      }
+    },
     {
       "canonical_input": "nz:statutes/new_zealand_superannuation/core#input.nz_super_single",
       "concepts": [

packages/microcosm-build/src/microcosm/build/nz/export_replay_bindings.json

@@ -1,4 +1,4 @@
 {
   "export_contract_sha256": "0000fbc98cec95bc8216dc968ffc09fd9a3a07455697275ba7cf67dec54f17b2",
-  "axiom_input_closure_sha256": "791c1cd420de8eddde8af6f9bc8a9aa5627d517f90ffed9b0012a36734071058"
+  "axiom_input_closure_sha256": "d2694200e0191803f1fdfa231106ed35fb9de3bbb0594e87bff87fed19849ce6"
 }

packages/microcosm-build/src/microcosm/build/nz/reporting_classifiers.json

@@ -209,8 +209,8 @@
   ],
   "disclosures": [
     {
-      "note": "NZ Super is overstated for single people who share a home because the shares-residence input defaults false; this moves their deciles upward.",
-      "evidence": "axiom_input_closure.json#/entries[input=nz_super_shares_residence_with_person_at_least_adult_age]",
+      "note": "The model understates NZ Super for single people whose only co-resident adults are exempt dependent children or temporary visitors: the shares-residence input reads household composition, but the exempt-adults input defaults false, so they get the sharing rate. This moves their deciles downward.",
+      "evidence": "axiom_input_closure.json#/entries[input=nz_super_shares_residence_with_person_at_least_adult_age]; axiom_input_closure.json#/entries[input=nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors]",
       "citation": {
         "item": "A1",
         "source": "docs/nz-reporting-classifiers-method.md#a1-income-decile-provisional"

packages/microcosm-build/src/microcosm/build/nz/transport_graph.json

@@ -4978,7 +4978,7 @@
     ]
   },
   "pending_outputs": [
-    "G8-x income reconciliation evidence: the native-band report, omission-register and identity-receipt artifacts and the VSI, VEX and VPT run evidence that measurement_prefit requires (R2C-18), and the NZS sharing binding (R2C-5)",
+    "G8-x income reconciliation evidence: the native-band report, omission-register and identity-receipt artifacts and the VSI, VEX and VPT run evidence that measurement_prefit requires (R2C-18)",
     "Census rent and liquid-assets quantile producers"
   ]
 }

packages/microcosm-build/tests/engine_free/shared/test_nz_spec_package.py

@@ -3235,24 +3235,30 @@ def test_keyed_citations_survive_a_record_inserted_before_the_target(
                 (_BUILD.repository / file).read_text(encoding="utf-8")
             )
             array, field = "bindings", "canonical_input"
-            expected_key = "nz:statutes/social_security/accommodation_supplement/core#input.accommodation_supplement_relevant_weekly_income"
+            expected_keys = [
+                "nz:statutes/social_security/accommodation_supplement/core#input.accommodation_supplement_relevant_weekly_income"
+            ]
             evidence = reporting["disclosures"][1]["evidence"]
         else:
             file, array, field = "axiom_input_closure.json", "entries", "input"
             original = _load(file)
             if disclosure == "sharing_home":
-                expected_key = (
-                    "nz_super_shares_residence_with_person_at_least_adult_age"
-                )
+                expected_keys = [
+                    "nz_super_shares_residence_with_person_at_least_adult_age",
+                    "nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors",
+                ]
                 evidence = reporting["disclosures"][0]["evidence"]
             else:
-                expected_key = "accommodation_supplement_non_beneficiary"
+                expected_keys = ["accommodation_supplement_non_beneficiary"]
                 evidence = reporting["as_non_beneficiary_audit"]["evidence"]
-        (expected,) = [row for row in original[array] if row[field] == expected_key]
+        expected = []
+        for key in expected_keys:
+            (row,) = [row for row in original[array] if row[field] == key]
+            expected.append(row)
         original[array].insert(0, {field: "dummy_record"})
         citation_checkout(file, original)
-        (citation,) = json_pointer_citations(evidence)
-        assert resolve_json_pointer(*citation) == expected
+        citations = json_pointer_citations(evidence)
+        assert [resolve_json_pointer(*citation) for citation in citations] == expected
 
     def test_local_file_pins_cannot_hide_absolute_or_parent_path_aliases(self) -> None:
         relative = "packages/microcosm-frame/src/microcosm/frame/concepts.py"
@@ -3413,18 +3419,32 @@ def test_financial_independence_citations_still_bind_carried_usual_hours(
         ]
         assert f"`{rule['donor_variable']}`" in row
 
-    def test_reporting_disclosure_cites_the_sharing_home_default_record(self) -> None:
+    def test_reporting_disclosure_cites_the_sharing_home_binding_record(self) -> None:
         disclosure = _load("reporting_classifiers.json")["disclosures"][0]
-        (citation,) = json_pointer_citations(disclosure["evidence"])
-        record = resolve_json_pointer(*citation)
+        record, exempt = (
+            resolve_json_pointer(*citation)
+            for citation in json_pointer_citations(disclosure["evidence"])
+        )
         assert (
             record["input"]
             == "nz_super_shares_residence_with_person_at_least_adult_age"
         )
-        assert record["class"] == "defaulted"
-        assert record["value"] is False
-        assert "overstates NZS for singles who share a home" in record["reason"]
-        assert "overstated for single people who share a home" in disclosure["note"]
+        # H2 (R2C-20): household composition now encodes the input.
+        assert record["class"] == "encoded"
+        assert record["encoded_by"] == "concept_binding"
+        assert "value" not in record
+        # The exempt-adults default the note names is the second citation.
+        assert (
+            exempt["input"]
+            == "nz_super_all_shared_adults_are_exempt_dependent_children_or_temporary_visitors"
+        )
+        assert exempt["class"] == "defaulted"
+        assert exempt["value"] is False
+        assert "default understates NZS for that group" in exempt["reason"]
+        assert (
+            "understates NZ Super for single people whose only co-resident adults"
+            in disclosure["note"]
+        )
 
     def test_reporting_non_beneficiary_audit_cites_its_exact_state_binding(
         self,