Add donor transport operators: reader, stable seeds, currency bridge and quantile map (NZ v0, G3b)

changelog.d/nz-transport-operators.added.md

@@ -0,0 +1,10 @@
+Add engine-free transport operators: a reader for local populace-US donor
+files pinned by size and SHA-256, stable source-ID seeds, one-step currency
+conversion, and weighted signed quantile maps with component and
+entity-aggregate support. The reader requires exactly one
+`is_household_head` reference person per household. For a two-person parent
+cycle, it drops the edge naming a younger parent, or both edges when ages are
+equal or the donor has no age column, and returns the dropped-edge count.
+Longer cycles and other inconsistent relationships are refused.
+The full reader smoke test loads the pinned donor's 166,321 persons in
+57,240 households, dropping two parent edges.

docs/concept-schema-transport-adr.md

@@ -1,9 +1,17 @@
 # Engine-neutral concepts and transport (ADR)
 
 **Status:** accepted for the concept schema, the per-engine mappings and their
-coverage reports, which this change adds. The transport pipeline described
-below is the design those pieces serve; none of it is built yet, and no build
-has migrated. **Date:** 2026-09-28. **Source:** Max's 27 September rulings on
+coverage reports. `microcosm.frame.transport` adds a reader for local
+populace-US donor files pinned by size and SHA-256, source-ID seeds, a
+currency bridge and weighted quantile mapping. The reader selects the donor's
+`is_household_head` as the reference person and repairs two-person parent
+cycles under the age rule below, following the NZ hub's 2026-10-07 defaults
+recorded for D1 method card d1043. The full reader smoke test returns a valid
+bank from its pinned donor: 166,321 persons, 57,240 households, 57,240 heads,
+74,572 partner pointers, 62,096 `parent_1_person_id` pointers and 43,731
+`parent_2_person_id` pointers, after dropping two parent edges. Concept
+validation reports no violations. The composed transport pipeline below
+remains a design, and no build has migrated. **Date:** 2026-09-28. **Source:** Max's 27 September rulings on
 international populations and law-anchored concepts. **Amended 2026-10-07:**
 schema version 2 adds `liquid_financial_assets`, the first stock concept, for
 New Zealand's Accommodation Supplement cash-asset test. Only the Axiom New
@@ -284,8 +292,26 @@ These hold for every input and are tested (Hypothesis properties unless noted):
   encoding it through the adapter's mapping, one build at a time.
 - The spec engine's `imputation.yaml` `concepts:` block is unrelated. It groups
   predictor columns for imputation, and its names are not concept ids.
-- Transport still needs four pieces beyond the schema: the donor bank, the
-  income transformation (step 3), a unit-construction step that builds engine
+- `microcosm.frame.transport` supplies a reader for pinned local donor files
+  and the income transformation operators (step 3). The reader's bank
+  declares US donor provenance and source-currency amounts; it does not
+  declare destination residents. Each household must have exactly one person
+  whose boolean `is_household_head` flag is true; this supplies its
+  `reference_person_id`. `A_EXPRRP` is not used to select it. On the pinned
+  donor, `is_household_head` equals `P_SEQ == 1` on every row and is the US
+  engine's own head. It agrees with the Census `A_EXPRRP` reference person in
+  all 19,753 households from 2024, including 222 where that person is not
+  line 1. The 2022/2023 `A_EXPRRP` values instead come from the build's line-1
+  derivation.
+- If two people name each other as parents, the reader drops the edge whose
+  named parent is younger than the child and keeps the other edge. If their
+  ages are equal or the donor has no age column, it drops both edges. A
+  present age column must satisfy the existing concept contract: whole,
+  nonmissing ages in completed years, from 0 through 130.
+  `DonorBank.dropped_parent_cycle_edges` exposes the number of dropped edges.
+  Longer cycles and other inconsistent relationships still fail validation.
+- The consuming builder supplies the destination frame declaration after
+  transport. Transport still needs a unit-construction step that builds engine
   units from the concept pointers (until it exists, 13 of New Zealand's 80 and
   46 of Belgium's 105 module bindings, and the take-up and housing bindings on
   US and UK group entities, stay deferred), and a country pack with geography,