Cite US and UK spec sources by symbol or at a commit, never by a drifting line

changelog.d/nz-spec-symbol-citations.fixed.md

@@ -0,0 +1 @@
+Cite source code by symbol, not line number, in the New Zealand spec package. `benefit_unit_rule.json` cited the relationship pointers as `concepts.py:880-919` and `concepts.py lines 892-901`, which #1120 shifted by one line, and the graph executor as `executor.py lines 636-643` and `lines 1550-1573`. It now names the `# --- Relationships` block from `_pointer("partner_person_id")` through `_pointer("reference_person_id")`, `_pointer("parent_1_person_id")`, and `microcosm.graph.executor._structural_columns` and `_validate_population_declaration`. `scenarios.json` cited the conformance harness as `ops main run.py:168`, which moves with ops main. It now names `WEEKS_IN_MODEL_YEAR` in `nz-lane/emtr_reproduction/run.py` at ops `ba6e7d6e`. A new engine-free test refuses any line citation of a Python source in the package unless the same resource pins that source at a commit, as `as_rate_bridge.json` pins the harness. It also checks that the benefit unit rule's pointer citations match the concepts source and that every dotted `microcosm.*` symbol the package names resolves. The two resource hashes and the NZ spec fingerprint in `tests/golden/nz_country_spec.json` are re-pinned. The spec-engine `package_fingerprint` moves, and no test or artifact pins it. The `spec_sha256` and `documentation_sha256` are unchanged. No behaviour or data changes.

changelog.d/spec-source-citations-us-uk.fixed.md

@@ -0,0 +1 @@
+Cite source code by symbol, or by line at a named commit, in the US and UK spec packages. A new engine-free guard (`test_spec_source_citations.py`, validators in `test_support/microcosm_build/spec_source_citations.py`) scans every resource in every country package. It refuses a line citation of a file in this repository, pinned or not, and a line citation of any other source unless its string names the commit (`commit <sha>`, `at <sha>`, `@<sha>` or a `/blob/<sha>/` link) or the resource pins that file in a `path`/`commit` mapping. In `us/ecps_parity_known_gaps.json`, the `asec_pool.py`, `tools/build_us_puf_support_base.py` and `experiments/build_j_recert/*` line citations now name `microcosm.build.us_runtime.asec_pool` symbols, the tool's functions, the `--asec-h5` arguments and `base_j.summary.json` keys. Where #720's Census person-column restore had made a sentence false, the sentence now says which columns the restore leaves out, and tests check those columns against `ASEC_CENSUS_PERSON_COLUMN_NAMES`. The us-data citations in `us/source_stages.json` and `us/target_parity_manifest.json` name archived commit `42ed5d45`. The uk-data citations in `uk/uk_data_target_parity.json` name incumbent commit `8629dbbf`, and those in `uk/uk_population_targets.json` name the registry ref `12a1e028`. Reading each cited range at its commit also corrected six citations that pointed at the wrong code: SSI take-up (`cps.py` 584 / 1497-1499 labels swapped), SCF net worth (`source_impute.py` fit at 1227-1240), `hmrc_cgt.py` 195 to 196, `frs_only.py` to `services.py` 137-148, `_land.py` 52-73 (the file has 65 lines) to per-sector ranges, and the salary-sacrifice drop (`build_loss_matrix.py` 376-394 to the `except Exception` in `hmrc_salary_sacrifice.py`). Re-pinned: the `source_stages.json` raw hash (`sources.yaml` `stage_asset`, the generator's frozen hash, `us_spec_bundle.py`, `test_us_bundle_core_contracts.py`), the regenerated `us/spec/sources.yaml`, the US `spec_sha256` and `documentation_sha256`, three `inventory_coverage.EXPECTED_HASHES` (`source_manifest`, `late_resource_semantics`, `full_checkpoint`) and `docs/evidence/spec-engine/us-f0-coverage.json`. Existing stacked US pool stage checkpoints will be treated as stale and rebuilt. No behaviour or data changes.

docs/evidence/spec-engine/us-f0-coverage.json

@@ -4,7 +4,7 @@
     "version": 1
   },
   "country": "us",
-  "documentation_sha256": "0931cbd3aae2abcd8c072b78eba40c1c006b1bf7fa23c6a6681f9a895e47070e",
+  "documentation_sha256": "b3d98ce90c62d273061fed19ee8db943ef7d64f53e697ddb9c9180a47f09daa3",
   "field_usage": {
     "authored_normative_field_count": 32404,
     "claim_count": 49,
@@ -1361,12 +1361,12 @@
         ],
         "expected": {
           "producer_count": 38,
-          "sha256": "cc34ba11288d01145fc2dc1a669df3f7c4ef2019d73afb02dd8eeee852b16d20"
+          "sha256": "5d84124a6109a8c0d22445fb36c12e56e29817cc694f15f7984dd6bff90aa26e"
         },
         "failures": [],
         "observed": {
           "producer_count": 38,
-          "sha256": "cc34ba11288d01145fc2dc1a669df3f7c4ef2019d73afb02dd8eeee852b16d20"
+          "sha256": "5d84124a6109a8c0d22445fb36c12e56e29817cc694f15f7984dd6bff90aa26e"
         },
         "status": "covered"
       },
@@ -1775,12 +1775,12 @@
           "legacy_adapter.imputation.late_producer_resource_semantics"
         ],
         "expected": {
-          "sha256": "f4f8bfeb79268a4043a843b47cec1d1c0e58e9f5dd6bc23417ada95446dd7b8e",
+          "sha256": "4e0d2a606457f5e9d92c2d1e88fb682e861535f8b59e276c989ae06b67cf4e0d",
           "stages": 37
         },
         "failures": [],
         "observed": {
-          "sha256": "f4f8bfeb79268a4043a843b47cec1d1c0e58e9f5dd6bc23417ada95446dd7b8e",
+          "sha256": "4e0d2a606457f5e9d92c2d1e88fb682e861535f8b59e276c989ae06b67cf4e0d",
           "stages": 38
         },
         "status": "covered"
@@ -1887,7 +1887,7 @@
             "alpha",
             "zeta"
           ],
-          "sha256": "3db095ce2d1ef89028d3862f0edc827d704f099c5b3323f9b115642a3c27e007"
+          "sha256": "9a86a97784e022d5654f6d420e3fff58f3564bf11d2ffc66155e68ed37500d31"
         },
         "failures": [],
         "observed": {
@@ -1911,7 +1911,7 @@
             "alpha",
             "zeta"
           ],
-          "sha256": "3db095ce2d1ef89028d3862f0edc827d704f099c5b3323f9b115642a3c27e007"
+          "sha256": "9a86a97784e022d5654f6d420e3fff58f3564bf11d2ffc66155e68ed37500d31"
         },
         "status": "covered"
       },
@@ -1975,7 +1975,7 @@
             "take_up_contract",
             "us_qbi_reconciliation_contract"
           ],
-          "sha256": "61a5484eab9fae1d6651b3ae15f1793d4934ea2f6ed2c08d05716b745c221014"
+          "sha256": "934b244e467d82cf620eaf56a5cf388d7af20896d03be2ad5869c7aa9083ccd4"
         },
         "status": "covered"
       },
@@ -2599,7 +2599,7 @@
       "country": "us",
       "schema_id": "country_spec",
       "schema_version": 1,
-      "spec_sha256": "f76f921d4f74392b106b8c0729ce250494e0a55455eaba7b910b19cdf7825178"
+      "spec_sha256": "cf79472d67d56c738e6b0fb519853c9476bff34455480df3ed61da6db73055e1"
     }
   },
   "report_schema_version": 3,
@@ -2609,7 +2609,7 @@
     "country": "us",
     "schema_id": "country_spec",
     "schema_version": 1,
-    "spec_sha256": "f76f921d4f74392b106b8c0729ce250494e0a55455eaba7b910b19cdf7825178"
+    "spec_sha256": "cf79472d67d56c738e6b0fb519853c9476bff34455480df3ed61da6db73055e1"
   },
   "status": "pass"
 }

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

@@ -2,7 +2,7 @@
   "version": 1,
   "country": "nz",
   "method_card_row": "MC7",
-  "description": "The New Zealand benefit unit (engine Family entity): an adult, their co-resident partner, and their dependent children; every other adult forms their own unit. The unit id family.family_id and the membership person.person_family_id are structural graph columns: the graph executor counts each entity's id column and each person-table membership column as structural (microcosm.graph.executor._structural_columns, executor.py lines 636-643) and rejects a non-structural node that declares one as an output (_validate_population_declaration, executor.py lines 1550-1573). family.family_household_id, the unit's link to its household, is not structural; it is an ordinary family column. The planned shared transport CREATE kernel (packages G4 and G5a) is to build the units from the donor concept pointers, refusing ambiguous or cross-household units. Family weights are never stored: each unit inherits its household's weight through the Frame.",
+  "description": "The New Zealand benefit unit (engine Family entity): an adult, their co-resident partner, and their dependent children; every other adult forms their own unit. The unit id family.family_id and the membership person.person_family_id are structural graph columns: the graph executor counts each entity's id column and each person-table membership column as structural (microcosm.graph.executor._structural_columns) and rejects a non-structural node that declares one as an output (microcosm.graph.executor._validate_population_declaration). family.family_household_id, the unit's link to its household, is not structural; it is an ordinary family column. The planned shared transport CREATE kernel (packages G4 and G5a) is to build the units from the donor concept pointers, refusing ambiguous or cross-household units. Family weights are never stored: each unit inherits its household's weight through the Frame.",
   "status": "awaiting D1 (MC7; the dependent-child rule is spec data under amendment MC11a, which is proposed and also awaits D1)",
   "entity": "family",
   "engine_entity": "Family",
@@ -19,7 +19,7 @@
       "parent_2_person_id"
     ],
     "household_reference_person": "reference_person_id",
-    "citation": "packages/microcosm-frame/src/microcosm/frame/concepts.py:880-919"
+    "citation": "packages/microcosm-frame/src/microcosm/frame/concepts.py, the \"# --- Relationships\" block: _pointer(\"partner_person_id\") through _pointer(\"reference_person_id\")"
   },
   "composition": [
     {
@@ -32,7 +32,7 @@
     },
     {
       "member": "dependent_child",
-      "rule": "a dependent child joins the unit of its co-resident parent parent_1_person_id; a lone co-resident parent is always parent 1 (the pointer definition, concepts.py lines 892-901; the pointer checks flag parent_2_person_id without parent_1_person_id as parent_order, concepts.py _check_pointers), so parent_2_person_id never chooses the unit"
+      "rule": "a dependent child joins the unit of its co-resident parent parent_1_person_id; a lone co-resident parent is always parent 1 (the pointer definition, concepts.py _pointer(\"parent_1_person_id\"); the pointer checks flag parent_2_person_id without parent_1_person_id as parent_order, concepts.py _check_pointers), so parent_2_person_id never chooses the unit"
     },
     {
       "member": "other_adult",

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

@@ -150,7 +150,7 @@
     "annualisation": {
       "weeks_per_year": 52,
       "method_card_row": "MC12",
-      "note": "the conformance harness uses 365/7 weeks (ops main run.py:168); the model states and uses 52"
+      "note": "the conformance harness uses 365/7 weeks (WEEKS_IN_MODEL_YEAR in TheAxiomFoundation/ops nz-lane/emtr_reproduction/run.py at ba6e7d6e); the model states and uses 52"
     },
     "groupings": {
       "method_card_row": "MC3",

packages/microcosm-build/src/microcosm/build/spec_engine/inventory_coverage.py

@@ -350,18 +350,18 @@
     "acs_person_predictors": "878c788a6f037d7aca12b3586ea034eff04f3034ffa11935a736493042551f25",
     "authority": "9d4a9672a0f03039b1fe874b9fe21ed575be0d29f14afc396d03cdf5c809bdd2",
     "early_families": "4aa9f736fd76e83955477ad1667e58f48f264783f05bdc7f0102cd32d61323bd",
-    "full_checkpoint": "3db095ce2d1ef89028d3862f0edc827d704f099c5b3323f9b115642a3c27e007",
+    "full_checkpoint": "9a86a97784e022d5654f6d420e3fff58f3564bf11d2ffc66155e68ed37500d31",
     "gap_fill_schedule": "1c31f9868f7884347cc19cf1ff65da43f950b9114941a715bab168246db414a7",
     "graph_nodes": "40cd51ffdfe2e9d9d08d48c08e8ded9de1e4b134783bab05c4abc6ad5c72ca1e",
     "geography_assignment": "44e7f5f6cd7ceeef85d532c3d46306d03de4f4ee811376e6d29920742746b65c",
     "late_families": "d91f9ff0eb52f43e7b6eed3d5c58c37abe1620c3a11021da15dae9c10e16d382",
-    "late_resource_semantics": "cc34ba11288d01145fc2dc1a669df3f7c4ef2019d73afb02dd8eeee852b16d20",
+    "late_resource_semantics": "5d84124a6109a8c0d22445fb36c12e56e29817cc694f15f7984dd6bff90aa26e",
     "late_schedule": "e59c019d3d454eac99ac0ac209b6c5b6faaf9bdfcaeee18c36a25be19bf7da2f",
     "ownership": "5f64f0aac49e2313177564f71876bffc8c81b3ded4df701e70930e60e9c98356",
     "primary_tuples": "fdf23da429f8c501e198a2f5b719763d523a41565c2153fdf17b0344f21bcd7c",
     "seed_map": "b4d6ec9c11ce323d83319a3d0289e0cf7216a7936d6c6f08cef0a463ad369641",
     "seed_protocol": "114217a2918329b0601d94deb8ed83f73919584b85ca8aabe45a40665afb6560",
-    "source_manifest": "f4f8bfeb79268a4043a843b47cec1d1c0e58e9f5dd6bc23417ada95446dd7b8e",
+    "source_manifest": "4e0d2a606457f5e9d92c2d1e88fb682e861535f8b59e276c989ae06b67cf4e0d",
     "take_up": "9522ce40f7dea569312dd7a7beb474e5a5afadd2f1e10cb5876534c3ef623d35",
     "tail": "ac92829c88a1a4fb6460d61190918d5d99c6c377fc8dd8f62f02b332d09bf59c",
 }