From f0353b67a79b67ea3cbcf4f0f73beb320ca79e61 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 17:27:53 -0400 Subject: [PATCH 01/18] docs: establish immigration module scope and domain laws Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 377 ++++++++++++++++++++++++++++++ 1 file changed, 377 insertions(+) create mode 100644 docs/design/immigration_module.md diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md new file mode 100644 index 00000000..0ec3ed6a --- /dev/null +++ b/docs/design/immigration_module.md @@ -0,0 +1,377 @@ +# Immigration module — new-entrant cohorts through the scheduled-entry seam + +- **Design id**: `2026-07-15-immigration-module` +- **Roadmap**: [#113](https://github.com/PolicyEngine/populace-dynamics/issues/113), + M6 immigration entry cohorts and the versioned Trustees alignment layer. +- **Status**: DESIGN DRAFT (revision 1; adversarial-referee adjudication pending). + No immigration surface is certified by this document. +- **Engine baseline**: `75d30dd57d71b91ee0929246b2f3cbb92263b350`. + File:line pins refer to that tree unless a different source is named. +- **Information boundaries**: the inherited M6 temporal gate boundary remains + `T* = 2014`. A current 2026 Trustees assumption may drive a separately + versioned forward scenario, but is not estimation evidence and cannot enter or + re-anchor the inherited M6 scored path. +- **Non-change declaration**: this is a docs-only design. It edits no code, gate, + floor, run artifact, certified model, threshold, or test. + +## Revision log (finding → section) + +- Dormant-generator finding: the engine already owns an entrant seam, but there + is no immigration schedule generator → §3.1, §4. +- Net-is-not-entry finding: the 2026 Trustees component table distinguishes + 1.340 million gross new-person inflows from 0.130 million total net change in + 2026 → §2.4, §4.3, §4.10. +- No-history finding: a row inserted through the seam is absent from the cached + marital, disability, household, and earnings support objects → §3.4, §4.7–4.9. +- Certificate-boundary finding: §2.8.3a, §2.8.2g, and amendment 3h prohibit + repairing an unsupported universe by fabricating state or bypassing a live- + roster guard → §3.3–3.5, §5.6. +- Donor-support finding: MINT's sparse annual cohorts and the public surveys' + different universes require floors before any accuracy threshold → §2.1–2.3, + §5.3. + +## 0. Executive disposition + +The immigration v1 object is a **pre-projection schedule builder**, not a ninth +`PeriodModules` step. It produces deterministic, pre-ID-assigned entry frames and +places only those frames at metadata key +`m6_scheduled_entries_by_year`. The existing engine then activates each frame at +the top of its period. + +The proposed design makes four provisional choices, all reviewable by the +referee: + +1. Size literal entrant cohorts from **gross new-person inflows**, not from net + migration. In the 2026 Trustees table, adjustment of status is a + reclassification and is not a new person. +2. Use recent-arrival ACS donor units for the joint entry state. Estimation + creates a versioned donor artifact; the runtime schedule is deterministic + conditional on that artifact, a binding manifest, and a schedule seed. +3. Copy donor information only through entry. Post-entry outcomes come from + named populace-dynamics laws; no donor's future is cloned. +4. Keep emigration outside the entry builder. Therefore entry-only v1 is + report-only for population stocks and cannot claim Trustees net alignment. + A separately designed exit law is mandatory before that claim can be made. + +The fourth choice is intentionally costly but honest. Substituting total net +change for actual entrants would create a reduced-form residual cohort whose age, +family, earnings, and nativity composition has no literal interpretation. In +2026, it would also replace 1.340 million gross arrivals with 0.130 million +residual persons. That alternative remains an explicit referee decision, not a +silent implementation shortcut. + +## 1. Scope and non-goals + +### 1.1 Roadmap authority and the scope it does not settle + +Roadmap issue #113 is open and explicitly places immigration in M6: + +> “M6 | **Projection engine**: year-by-year forward simulation to ~2100 — +> demographics (M3) + earnings forward + DI (M4) + immigration entry cohorts + +> an explicit, versioned alignment layer to Trustees intermediate assumptions” + +It also defines the target panel: + +> “The proposal here is that **the canonical object is a person-period panel**: +> populace persons × years (~2026–2100), with future births and immigrant +> entrants as synthetic persons entering the panel, per-year calibrated weights, +> and the full variable surface as column groups.” + +Those statements authorize entry cohorts, synthetic person rows, calibrated +weights, and Trustees alignment. They do **not** decide gross versus net flows, +emigration, legal status, donor construction, entry timing, family-unit +materialization, or the state histories required by downstream modules. This +document proposes that missing scope. + +### 1.2 In scope for v1 + +V1 specifies: + +- a vintage-pinned annual cohort-control manifest; +- an estimated, versioned recent-arrival donor artifact; +- a deterministic builder for entry frames and module-native entry-state + packets; +- activation exclusively through `SCHEDULED_ENTRIES_KEY`; +- invariant checks for time coordinates, IDs, ordinals, weights, roster + presence, and provenance; +- a proposed additive `gate_imm` for entrant characteristics; and +- report-only reconciliation to SSA and Census population projections. + +The design covers people whose latest entry places them in the United States for +the modeled spell. It does not assert that a survey's latest year-of-entry answer +identifies a first migration, a legal admission, or continuous U.S. residence. + +### 1.3 Non-goals + +V1 does not: + +- model legal-status transitions, visa classes, removals, adjustment of status, + naturalization, or status-specific program eligibility; +- infer undocumented status from ACS, CPS, or SIPP; +- treat foreign earnings as Social Security covered earnings; +- model return migration as a distinct state; +- implement emigration or an overseas-beneficiary population; +- modify mortality to disguise emigration; +- claim that SSA's Social Security-area population and the Census resident + population are the same universe; +- clone a donor's post-entry life; +- certify long-run entrant earnings, DI, marriage, fertility, household, + claiming, benefit, or population-stock outcomes; +- perform M7 trust-fund accounting or M8 rules execution; or +- change the inherited M6 gate, frozen floors, model registries, RNG registry, or + module order. + +### 1.4 Emigration boundary + +Emigration is **out of the v1 entry builder** because it has a different risk +universe and event law: it removes a roster-present person, can end an employment +spell, may preserve accrued U.S. benefit rights, and depends on time since entry. +The current entrant seam only adds prebuilt rows. Reusing mortality, negative +weights, or a fabricated negative entrant cohort would confound distinct events. + +This is a component boundary, not a declaration that emigration is unimportant. +MINT, DYNASIM, PENSIM, and PENSIM2 all provide evidence that literal entrant +modeling and population alignment require exits. Until a separate exit design is +ratified, v1 may certify only entry-time characteristics conditional on a gross +inflow control. Every stock, dependency ratio, benefit total, and net-migration +reconciliation remains report-only. + +## 2. Evidence and adjudication + +### 2.1 What predecessor models actually do + +| Model/source | Cohort count and exits | Entrant state | Transportable lesson | +|---|---|---|---| +| DYNASIM4 | The 2024 overview says immigration adds people, immigration and emigration are separate, and immigration is aligned to OACT targets (Cosic, Johnson, and Smith, *[Urban's Dynamic Simulation of Income Model 4](https://www.urban.org/sites/default/files/2024-09/Urban%E2%80%99s%20Dynamic%20Simulation%20of%20Income%20Model%204.pdf)*, pp. 1–2). | The public 2024 overview does not document a detailed donor algorithm. | Cite DYNASIM4 only for separate flows and OACT alignment; do not attribute undocumented donor mechanics to it. | +| DYNASIM3 detail | Table 1 of Favreault, Smith, and Johnson, *[The Dynamic Simulation of Income Model (DYNASIM): An Overview](https://www.urban.org/sites/default/files/publication/67366/2000391-The-Dynamic-Simulation-of-Income-Model-DYNASIM-%20An-Overview.pdf)* (2015), p. 7, uses OACT/Dowhan-Duleep targets by sex, age at entry, and source region, and a separate SSA-data emigration hazard using entry age and origin. | The same table says observed post-1980 immigrants' life histories are donors. | Donor histories plus distinct exit hazards are a useful precedent, but this report describes DYNASIM3 and cannot establish DYNASIM4's detailed implementation. | +| MINT6/MINT8 | MINT6 derived gross flows from OACT net targets and an emigration hazard; MINT8 uses projected gross legal and other-than-legal entries and models emigration separately (Smith et al., *[Modeling Income in the Near Term Version 6](https://www.urban.org/sites/default/files/publication/24986/412479-Modeling-Income-in-the-Near-Term-Version-.PDF)*, ch. II §VI, pp. II-24–II-28; Smith and Favreault, *[MINT8 and 2014: Primer](https://www.urban.org/sites/default/files/publication/100965/modeling_income_in_the_near_term_8_and_2014_primer.pdf)*, pp. 15–16, note 21 p. 29, Table 3 pp. 39–40). | MINT6 uses post-1990 SIPP immigrants to initialize sex, immigration age, source region, marital history/status, financial assets, and employment at arrival. It then runs ordinary post-entry modules. | Copy a coherent entry packet, never a donor's future. An initializer and the later transition laws are separate estimands. | +| PENSIM | *[PENSIM Overview](https://www.retirementplanblog.com/wp-content/uploads/sites/304/2006/10/overview.pdf)* (Holmer, Janney, and Cohen, 2006), §2.1.6 p. 8, combines SSASIM/Trustees net immigration with native- and foreign-born emigration assumptions to derive gross flows; Appendix B §§B.1.2–B.1.4 pp. 100–101 schedules entry and exit from a life synthesized at birth. | A person's whole pre-entry life exists before the immigration event. | Whole-life synthesis avoids missing histories, but is not portable to a roster that materializes a person at entry. The needed analogue is an explicit entry-state packet. | +| PENSIM2 | O'Donoghue, Redway, and Lennon, *[Simulating migration in the Pensim2 dynamic microsimulation model](https://www.microsimulation.pub/articles/00039)* (2010), §5.1 and Figure 3, disaggregates ONS net controls into gross immigration and emigration. | §5.2 samples immigrant **families** from the 2003 Labour Force Survey and calibrates person totals; Table 2 contrasts cloning and synthetic approaches. | Preserve joint family state and distinguish the control unit from the donor/simulation unit. Net-only migration can bias population structure (§3 and §4). | + +MINT is the closest architectural analogue. Earlier MINT versions cloned a +donor's later trajectory, but MINT6 “modifies this approach markedly”: donor +information stops at arrival and the entrant then passes through ordinary +modules (MINT6, pp. II-24–II-26). MINT6 also reports roughly 300 synthetic entrant +records per year and noisy single-age results (pp. II-25–II-28, Tables 2-15 and +2-16). That is direct evidence for support floors and against an arbitrarily fine +matching grid. + +The SSA research trilogy reaches a compatible conclusion. Duleep and Dowhan, +“[Incorporating Immigrant Flows into Microsimulation Models](https://www.ssa.gov/policy/docs/ssb/v68n1/v68n1p67.html),” +*Social Security Bulletin* 68(1), 2008, §§“Projecting the Flow of Immigrants” and +“Giving the New Immigrants Earnings Profiles,” identifies flow projection and +earnings imputation as different tasks. It recommends immigrant donors grouped +by sex, age at migration, and source region, and warns that a parametric approach +may suppress within-cell variation. The companion “[Adding Immigrants to +Microsimulation Models](https://www.ssa.gov/policy/docs/ssb/v68n1/v68n1p51.html),” +pp. 51–66, shows why initial relative earnings and time since entry matter and why +emigration cannot be ignored. + +### 2.2 Public microdata: roles and limitations + +| Source | Exact public support | V1 role | Binding limitation | +|---|---|---|---| +| ACS PUMS | Census, *[2010–2014 ACS 5-year PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* (Jan. 14, 2016): `SERIALNO`, `PWGTP`, `AGEP`, `CIT`, disability items, `MAR`, `SCHL`, `SEX`, `WAGP`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `PINCP`, and place of birth; the *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*, §3 pp. 5–7 and §4 p. 8, defines the pooled sample and dual-variable rule. | Primary joint-state donor and gate truth, weighted by `PWGTP` with replicate-weight uncertainty. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. `YOEP` is the latest entry, and `WAGP` covers the prior 12 months, possibly including pre-entry months. The 2016 publication date versus `T*=2014` is an open admissibility decision (§6.2, decision O6). | +| CPS ASEC | Census, *[2014 Annual Social and Economic Supplement Technical Documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian-noninstitutional sample; grouped entry years; survey-date demographics versus prior-calendar-year income; 2014 Traditional and Redesign files must never be silently combined. | +| SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves miss newly arrived immigrant-only households. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | + +The ACS donor predicate is named, not implied: + +```text +foreign_born == true +and 0 <= survey_year - latest_year_of_entry <= recent_arrival_max_duration +``` + +`survey_year` is decoded from `SERIALNO`; the correct `YOEP05`/`YOEP12` +classification is selected by collection year. The initial proposal is a 0–4 +year window, but the exact duration and fallback hierarchy remain decision O3. +The extractor must bind allocation-flag treatment, top/bottom-code treatment, +group-quarters policy, dual classifications, replicate weights, and the use of +`ADJINC` before any artifact can be certified. + +### 2.3 Donor-based versus model-based assignment + +**Provisional adjudication: donor-based joint assignment, with model-based +calibration and no cloned future.** This preserves observed covariance among age, +sex, education, marital/family state, disability indicators, employment, and +earnings. A purely parametric set of independent draws is rejected for v1 because +passing marginal cells would not establish a coherent person or family packet. + +“Donor-based” does not mean raw row copying: + +- the donor pool, matching grid, fallback ladder, unit construction, weight + trimming, allocation-flag policy, and calibration loss are fitted/versioned; +- survey concepts are mapped to named entrant concepts with missing/unsupported + states rejected rather than guessed; +- a SIPP history donor, if used, is a second named imputation with its own joint- + fidelity diagnostics; +- future outcomes are never present in the donor artifact; and +- runtime realization is deterministic conditional on the frozen artifact, + controls, and seed. + +A later parametric alternative may compete only on the same joint holdout +surface and floors. Lower marginal error alone is insufficient. + +### 2.4 Gross inflow, net change, and status adjustment + +The current control candidate is the *2026 OASDI Trustees Report*, §V.A.3 and +[Table V.A2, “Immigration Assumptions, Calendar Years 1940–2100”](https://www.ssa.gov/oact/TR/2026/lr5a2.html). +The assumptions were set in February 2026. Table V.A2 carries, separately, LPR +new-arrival inflow, LPR/citizen outflow, adjustment to LPR status, LPR net change, +temporary-or-unlawfully-present inflow, outflow, the offsetting status adjustment, +that stock's net change, and total net change. + +For intermediate 2026, in thousands: + +| Component | Persons (thousands) | Entry-seam meaning | +|---|---:|---| +| LPR new-arrival inflow | 600 | New-person inflow | +| Temporary/unlawfully present inflow | 740 | New-person inflow | +| **Gross new-person inflow** | **1,340** | Candidate entry-cohort total | +| LPR/citizen outflow | 263 | Exit, never an entrant | +| Temporary/unlawfully present outflow | 947 | Exit, never an entrant | +| Adjustment to LPR status | 450 in each stock, opposite signs | Internal reclassification; not a new person | +| **Total net change** | **130** | Reconciliation target, not a literal cohort | + +The 75-year intermediate average total net change is 1.138 million, but Table +V.A2 is annual and materially non-flat; the annual component values, not the +average or ultimate constant, are the binding shape. Components may differ by +rounding. + +The table's universe is the Social Security area, not the Census resident +population. The report's glossary includes residents of U.S. territories, +certain people abroad, and other groups absent from ACS PUMS. Therefore even +gross inflow is not directly a resident-population control. A named universe +bridge is required before production use (§6.1). Until then, both the gross entry +schedule and net reconciliation are report-only. + +## 3. Binding repository and domain law + +### 3.1 The only entrant activation seam + +The engine already defines +[`SCHEDULED_ENTRIES_KEY = "m6_scheduled_entries_by_year"`](../../src/populace_dynamics/engine/loop.py#L27) +at `src/populace_dynamics/engine/loop.py:27`. V1 feeds that seam and creates no +parallel entry hook. + +The baseline contract is exact: + +- `PeriodModules` contains the eight ordered adapters plus an initial-frame hook, + but no entrant adapter (`engine/loop.py:110-122`). +- Initialization runs once on the original starting slice before the schedule is + read (`engine/loop.py:180-192`). Scheduled entrants do not pass through it. +- Each schedule key must satisfy `start_year < entry_year <= end_year`; its value + must be a validated DataFrame with a single coordinate + `year == entry_year - 1` (`engine/loop.py:192-211`). +- Every scheduled `person_id` is pre-supplied, globally unique across the initial + slice and all cohorts (`engine/loop.py:213-221`). +- The dynamic synthetic-ID allocator starts above the maximum initial or + scheduled ID (`engine/loop.py:222-228`). +- Stable person RNG ordinals are preassigned over the complete initial-plus- + scheduled ID universe before period 1 (`engine/loop.py:234-237`). +- At entry year, the frame is concatenated and stably sorted at the very top of + the period (`engine/loop.py:239-257`), before mortality and the remaining + ordered modules (`engine/loop.py:258-321`). +- Newborns and any other dynamically created rows receive ordinals only after the + projected slice validates (`engine/loop.py:323-331`). + +The seam is not wholly dormant. `M6RealizedPopulation.projection_metadata` +already publishes later PSID openers through the same key +(`harness/m6_population.py:49-73`), and the realized-population builder schedules +2017/2019 openers (`harness/m6_population.py:313-335`). The missing object is an +**immigration/new-entrant generator and its state packet**, not a generic engine +entry mechanism. + +### 3.2 Consequences for timing, IDs, and RNG + +An entry frame is a pre-period state. Mortality sees it first +(`engine/steps.py:113-134`); aging then adds one to `age` and writes the target +year (`engine/steps.py:137-166`). The existing PSID opener builder deliberately +stores the prior year coordinate while retaining the observed collection-wave +age (`harness/m6_population.py:313-320`). That convention does not by itself +settle whether an annual gross immigrant inflow should receive a full-year, +half-year, or no domestic mortality exposure in its entry year. + +V1 therefore requires a named `entry_timing_basis` and a pre/post-aging age +identity check. Decision O2 must settle the convention before implementation; +the builder may not hide an age shift inside donor extraction. Whatever is +chosen, the schedule frame must use the seam's `year = entry_year - 1` contract. + +IDs are assigned outside the loop in deterministic order. They must be finite +integers, greater than every starting-population ID, collision-free across all +years, and invariant to row order. These conditions preserve every original +person's sorted-ID ordinal. The loop then places the newborn allocator above all +scheduled IDs, so entrant IDs cannot collide with later births. No existing M6 +module stream is consumed to construct the schedule. + +### 3.3 Amendment 3h: live-roster materialization + +Amendment 3h is not merged at the baseline commit. Its public source is the +[3h forensics/adjudication](https://github.com/PolicyEngine/populace-dynamics/issues/42#issuecomment-4984997277) +and draft [PR #216](https://github.com/PolicyEngine/populace-dynamics/pull/216). +This sibling design adopts its domain law as a dependency while accurately +describing its pending merge status: + +> Scheduled open-addition events may materialize a related person only when the +> required parent/person is present in the live post-mortality roster. The +> frame-independent risk schedule may remain the scoring universe; absent-parent +> events are dropped after the draw and reconciled report-only so RNG addresses +> do not shift. + +Entrants are roster-present when their own rows are activated. Their later +marriages, births, household links, and exits must still obey live-roster +materialization. A donor packet may not create a spouse, child, or other relation +whose person row is absent, and it may not weaken the existing birth-parent guard +at `engine/steps.py:409-414`. + +### 3.4 Why an entry row is not an initialized person + +The current certified assembly consumes fitted objects and native-panel builders +(`engine/assembly.py:81-99`). Several adapters construct and cache a whole-window +projection once per draw: + +- marital support is built once and cached (`engine/assembly.py:271-295`), and + its certified builder deliberately ignores the live frame + (`engine/panel_builders.py:150-165`); +- fertility draws over the cached marital IDs (`engine/assembly.py:297-324`); +- disability simulates once over realized PSID support + (`engine/assembly.py:326-377`); +- household composition builds and caches its native panel + (`engine/assembly.py:385-424`); and +- earnings initialization runs only on the original initial slice + (`engine/assembly.py:239-250`; `engine/loop.py:180-185`). + +Worse, `_merge_period_columns` drops existing state columns before left-merging +the cached update (`engine/assembly.py:174-192`). An immigrant absent from that +update receives missing state even if the scheduled row carried a seed value. +The later PSID openers work because their realized support is known to the +whole-window builders in advance. An unknown synthetic immigrant has no such +support. + +Therefore the immigration generator must produce both an entry row and an +explicit, module-native **EntrantStateBundle**. Merely adding more columns to the +entry frame is rejected. + +### 3.5 The §2.8.3a / §2.8.2g / 3h domain-law family + +The sibling M6 design's three laws bind this module: + +- **Earnings §2.8.3a**: the certified forward generator's domain is the + intersection with realized 2014 earnings state. Missing/new rows are false in + `earnings_domain` (`engine/earnings_domain.py:68-100`); the initializer writes + zero/missing outside that domain and validates exact fitted membership + (`engine/earnings_domain.py:156-210`). An immigrant may not be assigned a fake + 2014 anchor, `u_w`, or PSID history to enter that domain. +- **Marital §2.8.2g**: preserve the invariant guard and repair an unsupported + universe at builder/domain entry. The immigrant analogue is to construct a + named entrant risk-set seed; it is not to weaken the core or pretend the PSID + certificate covers the new population. +- **Fertility amendment 3h**: distinguish a frame-independent scoring schedule + from live-roster materialization. No related row may be materialized against an + absent person merely because that person exists in a donor or cached support + artifact. + +No existing certificate transfers across these bridges. Reuse of unchanged core +code may be plumbing at implementation time, but applying it to an entrant +population is a new domain claim and remains report-only until its expressly +named successor gate passes. From bd890956ad6ed085aa849f7bf0ca693e2ac8b685 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 17:32:00 -0400 Subject: [PATCH 02/18] docs: specify entrant schedule state and evaluation design Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 453 ++++++++++++++++++++++++++++++ 1 file changed, 453 insertions(+) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 0ec3ed6a..e3124a19 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -375,3 +375,456 @@ No existing certificate transfers across these bridges. Reuse of unchanged core code may be plumbing at implementation time, but applying it to an entrant population is a new domain claim and remains report-only until its expressly named successor gate passes. + +## 4. Proposed design + +### 4.1 Components and one-way data flow + +The design separates source estimation, scenario binding, schedule realization, +and period activation: + +```text +ACS <=T* records ──fit──> ImmigrationDonorArtifact ─┐ + ├─> ImmigrationScheduleBuilder +SSA annual components ──bind──> BindingManifest ───┘ │ + ├─> entry frames +SIPP/CPS ──diagnostics only───────────────────────────────────────┤ + ├─> EntrantStateBundle +Census scenarios ──report-only corridors─────────────────────────┘ + +entry frames ──metadata[SCHEDULED_ENTRIES_KEY]──> existing engine loop +EntrantStateBundle ──entrant-only adapters/builders──> downstream state +``` + +The conceptual products are: + +- **`ImmigrationBindingManifest`**: immutable source/vintage/schema/hash records, + annual flow controls, universe labels, and scenario identity; +- **`ImmigrationDonorArtifact`**: a fitted pool of recent-arrival person or family + units, matching cells, fallback hierarchy, concept mappings, and provenance; +- **`EntrantStateBundle`**: the entry frame plus module-native initial state and + exposure objects for the same people; +- **`ImmigrationSchedule`**: `entries_by_year`, the state bundle, deterministic + ID ledger, and reconciliation tables; and +- **`ImmigrationAudit`**: cohort totals, donor support, calibration residuals, + universe caveats, dropped/unsupported units, hashes, and certification labels. + +`ImmigrationSchedule.entries_by_year` is the only product sent to +`SCHEDULED_ENTRIES_KEY`. The state bundle is consumed by explicit entrant-side +builders/adapters assembled before projection. There is no entrant event draw in +the annual engine loop. + +### 4.2 Estimation versus deterministic realization + +The campaign's estimation/determinism split is binding: + +**Estimated and versioned** + +- recent-arrival definition and survey concept map; +- donor unit, matching variables, and fallback order; +- sampling/calibration loss and weight trimming; +- any ACS→SIPP joint-history imputation; +- any entrant-specific earnings or disability initializer; and +- every evaluation floor and eventual gate threshold. + +**Deterministic conditional on frozen inputs** + +- parsing the annual external-control table; +- selecting an artifact by exact ID/hash; +- schedule realization under an explicit schedule seed; +- synthetic IDs and arrival-unit IDs; +- conversion to the seam's prior-year frame coordinate; +- cohort weight calibration to the bound control; and +- serialization and audit calculations. + +The schedule is built **once per scenario before the K projection draws** and is +reused across those draws. It does not consume any of the eight existing M6 +period-module streams. Sampling uncertainty is studied by separately named +schedule seeds/artifacts; it is not accidentally mixed into the engine's +process-error draws. + +### 4.3 Annual cohort sizing + +For Trustees calendar year `y`, define the unbridged new-person control + +```text +G_ssa[y] = 1,000 * ( + V_A2_intermediate[y].lpr_new_arrival_inflow + + V_A2_intermediate[y].temporary_or_unlawfully_present_inflow +) +``` + +Adjustment of status is excluded because the same person moves between the two +Trustees stocks. Outflows are excluded because they are exit events. The +intermediate total-net column is retained as `N_ssa[y]` for reconciliation only. + +`G_ssa` is not yet a usable resident-population cohort. Production construction +requires an adjudicated, vintage-pinned bridge +`G_resident[y] = bridge(G_ssa[y])` between the Social Security-area and ACS +resident universes. Until decision O1 supplies that bridge, the builder must +either hard-stop or produce an explicitly named `ssa_area_proxy` schedule whose +entire projection is report-only. It may not silently set the bridge to identity +and label the result resident-population aligned. + +The schedule uses a manageable synthetic sample and positive calibration +weights; it does not create 1.34 million physical rows in 2026. For each year: + +- the number of donor units is set by support/precision requirements established + in the floor ceremony, not by the external population count; +- unit sampling preserves all members selected together; +- person weights are finite and positive; +- the sum of person weights equals `G_resident[y]` within a pinned numerical + tolerance; +- age/sex and other composition margins come from the frozen donor artifact, + never from Table V.A2, which has no public age/sex detail; and +- no unannounced ultimate-value or nearest-year fallback is allowed. A missing + year is a hard failure. + +Low-cost and high-cost Trustees series are separately named report-only +scenarios. The 75-year average is a disclosure, never a replacement for annual +values. + +### 4.4 Donor and simulation unit + +PENSIM2's family sampling exposes a real unit mismatch: the external control is +people, while the state to preserve may be a family. V1's provisional unit is a +**co-resident co-arrival unit**, not a claimed historical travel party: + +1. Start with a PUMS household (`SERIALNO`). +2. Select foreign-born recent-arrival people with the same latest-year-of-entry + classification. +3. Preserve spouse/partner and parent/minor-child links only when both endpoints + are in that selected set. +4. Assign a new `arrival_unit_id`; never expose `SERIALNO` as a synthetic person + or household identifier. + +A spouse, child, or parent who is native-born, entered in a different year, or is +absent from the PUMS household is not cloned. The entrant may retain an observed +marital/parental state with a named `relation_outside_entry_roster` marker, but +no related synthetic row or relationship ID is invented. This is required by +amendment 3h. + +Sampling whole units while calibrating person totals requires an explicit rule +for within-unit weights. The provisional invariant is one common simulation +weight for every member of an arrival unit, with a unit-selection/calibration +algorithm that reproduces person margins. That is not yet binding; decision O4 +may instead choose person donors with report-only relationship structure. The +floor ceremony must price whichever unit is selected. + +### 4.5 Characteristic assignment + +The fitted donor artifact preserves, at minimum: + +- age at the named pre-period/entry timing coordinate; +- sex; +- education and enrollment; +- source-region grouping derived from place of birth; +- race and Hispanic-origin fields only where a downstream/reporting contract + already has a defined concept; +- marital status/history fields available at the survey date; +- co-resident relationship structure and unit size; +- ACS disability-question indicators, without relabeling them DI status; +- employment, weeks/hours where available, wage/salary earnings, self-employment + earnings, and zero-earnings status; and +- survey year, latest year of entry, observed duration, allocation flags, donor + weight, and all concept-map provenance. + +The default matching ladder begins with sex × broad age-at-entry × source region +and then uses education and family state when support permits, consistent with +the MINT/Duleep-Dowhan precedent. The precise cells are selected and frozen +before candidate scoring. Fallbacks coarsen in a published order; they never +cross a prohibited concept boundary merely to fill a cohort. Every fallback +count appears in the audit. + +Long-run composition is held at the donor artifact's calibrated distribution +unless a separately sourced, gate-reviewed composition trajectory is bound. +Trustees aggregate totals cannot be used to manufacture one. Constant +composition through 2100 is therefore a visible extrapolation limitation, not an +empirical forecast claim. + +### 4.6 Schedule seed, IDs, and reproducibility + +The schedule PRNG address is conceptually + +```text +(schedule_seed, binding_manifest_hash, donor_artifact_hash, + entry_year, unit_slot, member_slot, purpose_tag) +``` + +It is independent of `ProjectionRNGRegistry`. Unit selection, tie-breaking, and +any stochastic calibration use named `purpose_tag` values so adding one draw does +not shift another purpose's addresses. + +After the full schedule is realized, IDs are allocated in stable order +`(entry_year, unit_slot, member_slot)` beginning above the maximum initial +`person_id`. The builder stores the allocation ledger and verifies global +uniqueness before calling the engine. Arrival-unit and household IDs use their +own namespaces and may not alias person IDs. + +Changing a source vintage, donor artifact, recent-arrival definition, or schedule +seed creates a new schedule identity. The design does not promise entrant or +newborn byte identity across such scenarios. It does promise that, within one +schedule, pre-supplying entrant IDs above the initial maximum leaves every +original person's sorted-ID ordinal unchanged and lets the engine place its +dynamic allocator above every scheduled entrant. + +### 4.7 Entry-frame schema and hard invariants + +Every scheduled entry frame contains these conceptual groups: + +| Group | Required fields | +|---|---| +| Engine | `person_id`, `year`, `age`, `sex`, `weight` | +| Entry identity | `synthetic_entry = true`, `entry_kind = "immigration"`, `entry_year`, `arrival_unit_id`, `foreign_born = true` | +| Timing | `entry_timing_basis`, `age_timing_basis`, `years_since_entry = 0` | +| Provenance | binding-manifest ID/hash, donor-artifact ID/hash, schedule ID/seed, donor-cell and fallback code | +| Static/donor state | education, source region, marital/family seed, employment/earnings seed, disability-concept seed, household seed | +| Domain markers | `earnings_domain = false` and named entrant-domain flags for every composite adapter | + +No `legal_status` field is inferred. A source-stock component from Table V.A2 may +be retained only at aggregate manifest level; it is not assigned to a person. + +Before engine invocation the builder hard-checks: + +- mapping keys are integer entry years in the projection range; +- each frame has exactly `year = entry_year - 1`; +- pre/post-aging age identities match decision O2; +- person IDs are finite integers, globally unique, and greater than the initial + maximum; +- all relation endpoints are either scheduled no later than the relation's + materialization year or explicitly marked outside-roster; +- weights are finite, positive, and reconcile at person and unit level; +- every required downstream state is supplied by the state bundle, not merely a + frame column that a later merge will erase; +- no donor future outcome or post-cutoff gate input is present; and +- every source, parser, derived artifact, and schedule payload matches its bound + hash. + +Any failure aborts before period 1. There is no nearest-year, nearest-vintage, +native-donor, legal-status, or fabricated-history fallback. + +### 4.8 `EntrantStateBundle` + +The state bundle is atomic by scheduled person ID and contains: + +| Native support object | Purpose | +|---|---| +| `entry_frames_by_year` | The exact frames sent through the seam. | +| `entrant_marital_seed` | Entry state/history, risk-set start year, relation IDs only for roster-present people, and entrant-domain marker. | +| `entrant_household_seed` | Arrival-unit household links, household state, and entry-year exposure mask. | +| `entrant_disability_seed` | Survey-concept indicators plus the explicitly estimated mapping to any entrant disability state. | +| `entrant_earnings_seed` | Entry employment/earnings state, zero pre-entry U.S.-covered history, any entrant-specific lag state, and normalization provenance. | +| `entrant_relationship_roster` | Parent/spouse/child endpoints and the first year each endpoint can materialize. | +| `entrant_audit` | Donor support, fallback, imputation, weight, universe, and hash records. | + +The packet must be coherent. State surfaces come from the same donor unit unless +a separately fitted joint imputation is named and validated. Independent +hot-decks for education, marriage, disability, and earnings are rejected because +they can construct combinations absent from the observed support while still +passing marginal checks. + +The packet includes only state through entry and the minimum pre-entry history +needed to define a downstream covariate. It never contains realized post-entry +outcomes. Foreign earnings may inform education/occupation matching if a future +source supports it, but U.S. Social Security covered earnings before modeled +entry are zero. Return migration is not inferred from a latest-entry response; +handling prior U.S. coverage is a successor design. + +### 4.9 Downstream module-state contract + +| Existing step | Entrant analogue | Certification boundary | +|---|---|---| +| Mortality | An activated entrant mechanically receives the existing age/sex mortality draw before aging. Decision O2 must define first-year exposure. | Mortality drift is already report-only; applying it to entrants is not newly certified. Emigration may not be encoded as excess mortality. | +| Aging | The existing deterministic `advance_age` runs unchanged after the prior-year coordinate check. | Plumbing only; the entry-age convention, not the function, is the new law. | +| Marital core | An entrant-side panel builder supplies one admissible entry seed and risk-set start. A production open-panel adapter may combine markets only in a report-only run. | Candidate-16's PSID certificate does not transfer to immigrants or to cross-domain matching. Closed-panel scored outputs must remain unchanged. | +| Fertility | Co-arriving children are entrant rows. Children conceived/born after entry use the normal fertility path and amendment-3h live-roster materialization. | No absent donor relative may be materialized. Entrant fertility remains report-only. | +| Disability | ACS disability questions and SIPP work-limit/benefit concepts feed a separately estimated entrant initializer/forward law; they are never relabeled as the realized PSID M4 status. | M4 reproduction support and certificate stay unchanged. Entrant disability is a successor-gate surface. | +| Earnings | Entrants remain `earnings_domain = false`. A separate immigrant-entrant generator owns entry earnings and all later entrant earnings until a future handoff law is designed. It uses zero pre-entry U.S.-covered earnings and a pinned wage normalization. | No fake 2014 earnings, `u_w`, `gen_earn_w2`, or `gen_earn_w4`; the §2.8.3a generator is untouched and its certificate does not transfer. | +| Claiming | The schedule may be reused as plumbing, but insured status and AIME/PIA must use only simulated U.S.-covered earnings. | Entrant claims and benefits are report-only until earnings/history and eligibility concepts are certified. | +| Household composition | An entrant-side native panel starts exposure at entry, carries arrival-unit links, and makes no link to an absent person. | Candidate-9's PSID certificate does not transfer. Open-market effects on existing people are report-only. | + +The scored M6 closed-panel run and an open-population production run are distinct +products. Entrant interactions may affect existing people's marriages, +households, and births in the open run, but those effects cannot be allowed to +retroactively change the frozen closed-panel gate or its certificate. + +### 4.10 Emigration and net reconciliation + +The v1 audit publishes, by year: + +```text +gross_entry_control +scheduled_entry_weight +trustees_gross_outflow_required +trustees_status_adjustment_reclassification +trustees_total_net_target +entry_only_minus_net_gap +universe_bridge_status +``` + +With no exit law, `entry_only_minus_net_gap` is expected and disqualifies any net +alignment claim. A chart may show what the Trustees total-net path would imply, +but no population stock produced by entry-only v1 is “aligned” to that path. + +A successor emigration design must decide at least the exit timing/order, risk +population, age/sex/source/duration hazard, family versus individual exit, +return-entry identity, employment termination, household reconciliation, +accrued-coverage and overseas-benefit state, death-versus-exit observability, and +RNG addressing. Table V.A2 supplies aggregate outflow controls, not those hazards. + +**Rejected for production:** feeding total net change through the entry seam and +calling the rows immigrants. If the referee authorizes a reduced-form +`net_entry_proxy` experiment, its metadata, report, and output columns must say +that exact name; it cannot enter `gate_imm`, family-unit evaluation, entrant +characteristic claims, or M7 accounting. + +### 4.11 Fail-closed audit behavior + +Every build writes a machine-readable audit before projection. The audit includes +source and derived hashes, retrieval/publication/observation dates, parser and +schema versions, schedule seed, ID ranges, per-year physical rows and weighted +totals, donor-cell effective sample sizes, fallback counts, calibration residuals, +top-code/allocation shares, unit-size distribution, state-bundle completeness, +and all report-only/certified labels. + +The builder refuses to run when a binding is missing or mutable, a raw or derived +hash differs, a required year is absent, a unit crosses an unsupported concept, +an outside-roster relation is assigned an ID, an entry is accidentally admitted +to the certified earnings domain, or the universe bridge is absent for a run +claiming resident alignment. Network access and runtime redownload are prohibited +on a scored or production run. + +## 5. Evaluation and proposed `gate_imm` + +### 5.1 Gate identity and estimand + +`gate_imm` is a proposed **additive successor gate**. This document does not add +it to `gates.yaml`, choose tolerances, build a floor, or lock an artifact. + +The candidate estimand is narrow: + +> Conditional on the named recent-arrival resident-stock proxy and its survey +> universe, does the frozen donor/schedule procedure reproduce held-out ACS +> entry-state marginals and named joint distributions at their empirical noise +> floor? + +This is not a gate on external cohort counts: exact agreement with a forced +control is tautological. It is not truth for gross arrivals, people who left or +died before interview, legal status, or post-entry trajectories. + +### 5.2 Temporal split and leakage fence + +The primary proposed split uses collection-year information inside the +2010–2014 ACS 5-year PUMS: + +- fit donor construction and all matching/calibration choices on collection + years 2010–2013, recovered from `SERIALNO`; +- freeze the candidate artifact and surface; +- generate a synthetic 2014 recent-arrival resident cross-section without + reading 2014 person records; and +- score against collection year 2014 using the same recent-arrival predicate, + concept map, universe, and weight treatment. + +Households/arrival units are indivisible. The truth and candidate normalize to +the same total before characteristic scoring; the total itself is not a gate +cell. No 2014 characteristic, marginal, top-code treatment selected after seeing +the holdout, CPS/SIPP statistic, current Trustees assumption, or Census projection +may affect the fit. + +The 2010–2014 pooled file was published in January 2016. Decision O6 must ratify +the observation-date rule (all person observations are `<=T*`) or reject the file +under a publication-date rule. Rejection pauses the gate; it does not silently +move the boundary. A fallback using individually pinned one-year files published +by 2014 requires a new design amendment and floor. + +Later ACS windows, including 2015–2019 and 2020–2024, are temporal-drift stress +tests only under this gate. Refitting on them creates a new production artifact +to which no exact-artifact certificate automatically transfers. + +### 5.3 Floors before thresholds + +The ceremony order is mandatory: + +1. Freeze the recent-arrival predicate, donor/simulation unit, concept map, + matching ladder, gate cells, metrics, and weighting rules without candidate + holdout results. +2. Construct a correlation-respecting real-vs-real floor from deterministic, + household-disjoint splits or survey replicate-weight pseudo-replicates of the + 2014 truth. Never split members of one donor/household unit. +3. Publish, for every proposed cell, raw person count, raw unit count, weighted + effective sample size + `n_eff = (sum(w))^2 / sum(w^2)`, denominator, allocation share, top-code share, + and the distribution of the chosen distance under truth-vs-truth comparison. +4. Prune, pool, or demote every cell that fails predeclared support or whose floor + is unstable. Record each demotion; do not widen a threshold to retain it. +5. Price thresholds from the surviving empirical floors using a predeclared + transform. No numerical tolerance is assumed by this design. +6. Run an operating-characteristic experiment on the surviving conjunction + using predeclared degraded pseudo-candidates. If power is weak or the gate is + near-tautological, pause and redesign before any lock. +7. Only then score the registered candidate and, if it passes, bind the exact + artifacts, floor, registry, code commit, and hashes. + +This order is the M6 floors-before-thresholds law. Sparse single-age MINT6 cohorts +and the ACS weighted/unit structure make it substantive, not ceremonial. + +### 5.4 Candidate gate surface + +The floor ceremony may consider these predeclared families: + +| Family | Candidate observables | Candidate metric | +|---|---|---| +| Demographic | broad age-at-entry × sex shares; arrival-duration band; broad source region | total-variation or weighted absolute-share distance | +| Education | attainment band overall and by broad age/sex | total-variation distance | +| Family state | marital-state shares; co-arrival unit size; spouse/child co-arrival indicators | total-variation distance, unit-weighted where applicable | +| Employment | employed/unemployed/NILF; zero earnings; work-intensity bands | absolute-share or total-variation distance | +| Positive earnings | `WAGP`/earnings normalized under the pinned economic index, p10/p50/p90 and log spread | floor-scaled log-quantile distance | +| Disability proxy | the six ACS question concepts individually and “any” | absolute-share distance; never named DI status | +| Named joints | age × sex × education; sex × marital state × duration; education × employment/earnings band | pooled-cell total-variation distance | + +The final registry contains only cells that clear the floors. Fine source-region, +single-age, detailed education, high-order family, and earnings-tail cells are +presumptively report-only until their support proves otherwise. + +### 5.5 Report-only evaluation + +The following are useful but are not gate truth: + +- CPS ASEC 2014 foreign-born tables and microdata marginals for age/sex, marital + status, education, total money income, and earnings; +- SIPP 2014 Wave 1 joint plausibility for marital, employment/earnings, + disability, and nativity/entry concepts; +- ACS 2015–2019 and 2020–2024 drift from the frozen donor composition; +- 2026 Trustees low-cost/intermediate/high-cost gross inflows, outflows, and + total-net paths; +- the 2023 Census National Population Projections main/high/low/zero immigration + corridors; and +- foreign-born population stocks, dependency ratios, AIME/PIA, DI, claiming, + household, and benefit outputs. + +The Census “zero immigration” scenario is especially easy to misstate: its +method sets gross foreign-born immigration to zero while leaving emigration and +net native migration in place, so net international migration may be negative. +Agreement with any Census corridor is a cross-model comparison, not validation. + +### 5.6 What a PASS would and would not certify + +A `gate_imm` PASS could certify only: + +- the exact donor artifact, concept map, schedule procedure, seed protocol, and + surviving registry named in the lock; +- reproduction of the named held-out ACS recent-arrival resident-stock + cross-sections within floor-priced thresholds; and +- deterministic conversion of that artifact into seam-valid entry frames and a + complete entrant-state packet. + +It would not certify gross-flow truth, the Social Security-area→resident bridge, +emigration, legal status, current-vintage refits, composition through 2100, +entry-year mortality exposure, donor representativeness for people who left or +died before interview, any post-entry transition, any interaction with the +closed population, or any Social Security eligibility/benefit result. + +It also would not modify or extend the M6 certificate. Entrants remain family-B +open additions under `m6_reporting.py:71-73` and its explicit immigrant +person-row bridge at `m6_reporting.py:104-118` until a later ratified gate says +otherwise. From b47ca811fe40d716a80afcfe7b54e02bb68bfd3b Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 17:35:16 -0400 Subject: [PATCH 03/18] docs: bind sources decisions and amendment history Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 378 ++++++++++++++++++++++++++++++ 1 file changed, 378 insertions(+) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index e3124a19..cdb9864a 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -828,3 +828,381 @@ It also would not modify or extend the M6 certificate. Entrants remain family-B open additions under `m6_reporting.py:71-73` and its explicit immigrant person-row bridge at `m6_reporting.py:104-118` until a later ratified gate says otherwise. + +## 6. External bindings + +### 6.1 Manifest contract + +Every external or derived input is represented by a field-level manifest entry, +following the sibling §2.8.10 pattern. Each entry must contain: + +- stable binding ID and semantic version; +- source agency, exact report/file title, table/section, scenario and columns; +- observation universe, reference-period convention, units, and covered years; +- information date, publication/release date, retrieval timestamp, canonical URL, + and raw SHA-256; +- parser name/version, ordered source-field map, unit conversion, rounding rule, + missing-year behavior, and universe transformation; +- derived artifact schema, row count, minimum/maximum year, SHA-256, and immutable + artifact location; +- consuming component and whether use is gated, alignment-only, report-only, or + blocking; and +- explicit alternatives rejected or still open. + +An implementation factory must take no unbound source arguments. It resolves +repository-root-relative immutable artifacts, checks every raw and derived hash, +checks the declared time range and schema independently, and returns the ordered +binding objects. No scored or production run may fetch a source over the network. + +This design records the sources and required fields, but it does not create raw +or derived artifacts. Consequently no source hash is invented here: `raw_sha256` +and `derived_sha256` are **required lock-ceremony fields** and remain blocking +until an acquisition PR records the actual bytes. + +### 6.2 Binding ledger + +| Binding ID | Exact source and vintage | Fields/transformation | Consumer and status | +|---|---|---|---| +| `ssa_tr2026_v_a2_intermediate` | Social Security Administration, *[The 2026 Annual Report of the Board of Trustees of the Federal OASI and DI Trust Funds](https://www.ssa.gov/OACT/TR/2026/tr2026.pdf)*, §V.A.3, Table V.A2 “[Immigration Assumptions, Calendar Years 1940–2100](https://www.ssa.gov/oact/TR/2026/lr5a2.html),” assumptions set February 2026, report released June 2026. | Annual intermediate LPR inflow/outflow/status-adjustment/net; temporary-or-unlawfully-present inflow/outflow/status-adjustment/net; total net; thousands→persons; retain source rounding. Use exact annual rows 2026–2100. | Gross-entry control candidate and net reconciliation. Forward-assumption/report-only until universe bridge and exit design exist; prohibited as gate-estimation data. | +| `ssa_tr2026_v_a2_sensitivity` | Same report/table/vintage, low-cost and high-cost alternatives. | Same component schema; never substitute 75-year average or ultimate value for annual rows. | Report-only scenario sensitivity. | +| `ssa_area_to_census_resident_bridge` | **UNBOUND.** Must reconcile the 2026 report's Social Security-area definition (glossary pp. 247–248) to the ACS/Census resident universe with an exact source and vintage. | Annual inclusion/exclusion or factor by population category; preserve an auditable raw-SSA series beside the bridged series. Identity is not an admissible silent default. | **BLOCKING** for a schedule labeled resident-population aligned. A raw `ssa_area_proxy` may run report-only. | +| `acs_pums_2010_2014_recent_arrivals` | Census Bureau, [2010–2014 ACS 5-year person PUMS `csv_pus.zip`](https://www2.census.gov/programs-surveys/acs/data/pums/2014/5-Year/csv_pus.zip); *[PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)*, Jan. 14, 2016; *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*. Observations 2010–2014. | Decode collection year from `SERIALNO`; bind `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `POBP`, education, marital/relationship, disability, employment and income/earnings fields plus allocation flags. Fit years 2010–2013; hold out 2014. | Primary donor estimation and proposed `gate_imm` truth, conditional on decision O6. | +| `cps_asec_2014_foreign_born` | Census Bureau, *[2014 Annual Social and Economic Supplement Technical Documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)* and [2014 ASEC data page](https://www.census.gov/data/datasets/time-series/demo/cps/cps-asec.2014.html). | `A-AGE`, `A-MARITL`, `A-SEX`, `A-HGA`, six disability items, `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT`, `WSAL-VAL`, `PEARNVAL`, `PTOTVAL`; bind Traditional **or** Redesign file and correction/repost status. | Report-only marginal triangulation. Exact file choice is decision O7; the two files may not be merged silently. | +| `sipp_2014_wave1_entry_state` | Census Bureau, *[2014 SIPP Metadata All Sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*, Sept. 12, 2017; [Wave 1 raw directory](https://www2.census.gov/programs-surveys/sipp/data/datasets/2014/w1/); *[SIPP 2014 Panel Source and Accuracy Statement, Wave 1](https://www2.census.gov/programs-surveys/sipp/tech-documentation/source-accuracy-statements/2014/sipp-2014-source-and-accuracy-statement.pdf)*. Interviews in 2014, reference year 2013. | `WPFINWGT`, marital state/history, age, `EBORNUS`, `ECITIZEN`, `ENATCIT`, grouped `TYRENTRY`, education, sex, disability and monthly earnings concepts. `TIMSTAT` is excluded from legal-status state. | Report-only joint-state/initializer diagnostics. No later-wave immigrant-only household coverage claim. | +| `census_np2023_nim_corridors` | Census Bureau, *[Methodology, Assumptions, and Inputs for the 2023 National Population Projections](https://www2.census.gov/programs-surveys/popproj/technical-documentation/methodology/methodstatement23.pdf)* (Nov. 2023), migration pp. 8–14; [Alternative Scenarios table page](https://www.census.gov/data/tables/2023/demo/popproj/2023-alternative-summary-tables.html), Table 1 “Projected Population and Components of Change, 2022–2100”; [main workbook](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1.xlsx) and sibling `-h`, `-l`, `-z` workbooks. | Annual net international migration in thousands for main/high/low/zero scenarios; July 1 prior year–June 30 current year. Preserve scenario definitions: alternatives change gross foreign-born immigration, not every migration component. | Report-only cross-model corridors; never gate truth or a gross entrant control. | +| `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: realized SSA NAWI through 2014 and `I_proj` beyond, estimated only from `<=T*`; see `m6_projection_engine.md:666-708,1723-1756`. | ACS `ADJINC` first expresses pooled income in 2014 dollars; any projection-year entrant earnings use the already pinned `I_proj`, never realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | +| `emigration_duration_hazard` | **UNBOUND.** Table V.A2 supplies aggregate outflow counts only. The Duleep-Dowhan 2008 hazards and legacy model methods are research evidence, not a current operational binding. | Must identify age, sex, source grouping, time since entry, family/individual unit, re-entry treatment, universe and vintage. | **BLOCKING** for explicit exits and any Trustees net-alignment claim; outside entry-builder v1. | + +### 6.3 Binding-specific guards + +The SSA parser must assert scenario labels, all nine component columns, annual +coverage, units, and the internal identities + +```text +lpr_net = lpr_inflow - lpr_outflow + status_adjustment +temporary_net = temporary_inflow - temporary_outflow - status_adjustment +total_net = lpr_net + temporary_net +``` + +within the source's thousand-person rounding. It must not treat status adjustment +as two events or as a new arrival. + +The ACS extractor must assert each collection year from `SERIALNO`, apply the +correct dual-year-of-entry variable for that collection vintage, use person and +replicate weights, and publish allocation/top-code/group-quarters counts. It must +keep the survey's latest-entry meaning in field names; `first_entry_year` is +prohibited without another source. + +The Census parser must preserve its July-to-June event year and resident- +population universe. A calendar-year bridge to Trustees may be displayed only as +a named transformation with both originals retained. The “zero” scenario may not +be rewritten to zero net international migration. + +## 7. Open decisions for the referee + +Nothing in this list is silently resolved by the provisional recommendation. + +### O1. Literal gross entrants, exit scope, and the universe bridge — hardest + +Choose among: + +- **recommended**: gross new-person entrants through the seam, entry-only v1 + explicitly report-only, followed by a separate emigration design before any net + alignment claim; +- widen this design to include an audited exit law before implementing entries; + or +- authorize a named reduced-form `net_entry_proxy` experiment, accepting that it + is not a literal immigrant cohort and cannot enter entrant/family/benefit gates. + +Also select or commission the Social Security-area→resident bridge. Raw identity +is not presumed. + +### O2. Entry-year timing, age, and mortality exposure + +The seam inserts the prior-year-coordinate row before mortality and aging. +Decide whether the external calendar-year inflow represents opening-of-period, +midperiod, or end-of-period entry; what `age` means on the scheduled frame and +the target slice; and whether first-period mortality exposure is full, fractional, +or deferred. The choice must preserve the seam and publish an exposure audit. + +### O3. Recent-arrival window and matching ladder + +Ratify the proposed 0–4-year latest-entry window or a different duration; decide +whether duration-zero/one donors receive priority; freeze age/source/education/ +family matching cells and their fallback order; and decide how return entrants +are labeled without inferring unobserved prior U.S. coverage. + +### O4. Person versus co-arrival-family units and weights — hardest + +Choose person donors, co-resident co-arrival units, or a mixed rule. If units are +chosen, bind relationship closure, common versus person-specific simulation +weights, calibration to person totals, partial families, group quarters, and +whether later exits occur by person or unit. This decision sets the correlation +unit for floors. + +### O5. Atomic state/history packet and post-entry laws — hardest + +Decide which state comes from one ACS donor, which history may come from a +jointly matched SIPP donor, and which requires a new model. In particular: + +- marital history and spouse-outside-roster state; +- the ACS/SIPP disability-concept bridge; +- entry employment, partial-year earnings, lags and persistent earnings state; +- the entire entrant earnings law, since §2.8.3a membership cannot expand; +- cross-domain marriage/household interactions with existing people; and +- the certification boundary for ordinary cores applied to entrant inputs. + +The default is no independent marginal hot-decks and no certificate transfer. + +### O6. Observation date versus publication date at `T*` + +The proposed ACS pooled file contains only 2010–2014 observations but was +published in January 2016. Ratify an observation-date rule analogous to the M6 +NAWI publication-lag reasoning, or reject the pooled file and redesign the gate +around individually released pre-boundary files. The same issue affects the +later-published SIPP metadata, which is report-only here. + +### O7. CPS ASEC diagnostic vintage + +Choose Traditional or Redesign 2014 ASEC public-use data and bind its correction +history. This affects report-only triangulation, not candidate fitting or gate +truth. + +### O8. Current-vintage production refits + +Decide whether a later ACS donor refit (for example 2015–2019 or 2020–2024) +requires a new holdout/lock ceremony or may inherit a procedure-level certificate. +The conservative default is that the exact-artifact certificate does not +transfer and the refit remains report-only. + +### O9. Physical cohort size and calibration constraints + +Let the floor ceremony determine annual physical unit counts, weight caps, +calibration margins, and maximum fallback share. No arbitrary “one row per N +people” constant is adopted here. + +## 8. What this design does not change + +This document and its eventual entrant-side implementation must leave these +surfaces unchanged unless a later, separately adjudicated design explicitly +authorizes surgery: + +- `gates.yaml`, every `gate_m6` cell/threshold, the v1/v2/v3 M6 floors and their + hashes, `tests/tier_counts.json`, and all existing run artifacts; +- M6's `T* = 2014`, temporal holdout, shock partition, weight convention, and + closed-panel scoring support; +- the certified candidate-16 marital core, candidate-9 household composition + object, M4 disability reproduction object, gate-2c earnings modifier, and + gate-1/backward or M6/forward certified earnings specifications; +- the §2.8.3a earnings-domain predicate and its realized-2014 state maps; +- the §2.8.2g marital risk-set guard and seed-at-domain-entry law; +- amendment 3h's schedule-versus-live-roster materialization distinction and + absent-parent guard; +- `SCHEDULED_ENTRIES_KEY`, its frame/year/ID contract, and the existing 2017/2019 + PSID opener schedule; +- the eight-member `PeriodModules` order, existing module RNG streams, original- + person ordinals, synthetic-ID allocator semantics, and period trace; +- M6's current statement that immigrant/open-panel additions are report-only; +- M7 trust-fund accounting, M8 rules execution, and any PolicyEngine-US legal + eligibility rule; and +- every source or artifact outside the immigration binding manifest. + +An entrant adapter may call unchanged core code, but it must do so under an +entrant-domain label and separate report/gate surface. It may not alter the +closed-panel input or score and call the resulting difference “immigration.” + +## 9. Candidate-blind implementation and certification order + +A later implementation should proceed in this order: + +1. Referee resolves O1–O6 and ratifies the external-binding schema. +2. Acquisition PR commits/hash-binds exact source bytes and parsers; the zero- + argument binding factory passes independently of any candidate. +3. Donor-build PR constructs only training artifacts and synthetic fixtures; + holdout outcomes remain sealed. +4. Floors PR freezes the surface, creates truth-vs-truth floors, prunes unsupported + cells, and runs the operating-characteristic pause check. +5. Schedule/state PR implements the deterministic builder, seam adapter, complete + state packet, failure guards, and report-only open-population run without + changing the M6 closed-panel score. +6. A registered `gate_imm` candidate is scored once against the locked surface. +7. If PASS is verified and ratified, the lock names exact source, derived, floor, + code and schedule-protocol hashes. +8. Emigration and current-vintage refit designs run their own ceremonies before + any net-population or benefit certification claim. + +No stage reads a later stage's candidate outcomes to redesign an earlier frozen +surface. + +## 10. Referee citation ledger + +- **DYNASIM4**: Cosic, Johnson, and Smith, *Urban's Dynamic Simulation of Income + Model 4* (Urban Institute, September 2024), pp. 1–2. Detailed donor mechanics + are not public in that overview. +- **DYNASIM3 detail, not DYNASIM4**: Favreault, Smith, and Johnson, *The Dynamic + Simulation of Income Model (DYNASIM): An Overview* (Urban Institute, September + 2015), Table 1, report p. 7. +- **MINT**: Smith et al., *Modeling Income in the Near Term Version 6* (Urban + Institute, December 2010), ch. II §VI, pp. II-24–II-28, Tables 2-14–2-16; Smith + and Favreault, *Modeling Income in the Near Term 8 and 2014: Primer* (Urban + Institute, April 2019), pp. 15–16, note 21 p. 29, Table 3 pp. 39–40. +- **PENSIM/PENSIM2**: Holmer, Janney, and Cohen, *PENSIM Overview* (2006), + §2.1.6 p. 8, Appendix B §§B.1.2–B.1.4 pp. 100–101 and §§B.7–B.8 pp. 106–107; + O'Donoghue, Redway, and Lennon, “Simulating migration in the Pensim2 dynamic + microsimulation model,” *International Journal of Microsimulation* 3(2), 2010, + Table 2, §§5.1–5.2. +- **SSA methods/current controls**: Duleep and Dowhan, “Adding Immigrants to + Microsimulation Models” and “Incorporating Immigrant Flows into + Microsimulation Models,” *Social Security Bulletin* 68(1), 2008; *2026 OASDI + Trustees Report*, §V.A.3 and Table V.A2. +- **Microdata**: Census 2010–2014 ACS 5-year PUMS dictionary/accuracy statement; + Census 2014 ASEC technical documentation; Census 2014 SIPP Wave 1 metadata and + source/accuracy statement. Exact variables and pages are pinned in §2.2 and + §6.2. +- **Projection corridors**: Census, *Methodology, Assumptions, and Inputs for the + 2023 National Population Projections* (November 2023), migration pp. 8–14, and + Alternative Scenarios Table 1. + +## 11. Design parameters and amendment history + +```json immigration-design-parameters +{ + "design_id": "2026-07-15-immigration-module", + "revision": 1, + "status": "design_draft_referee_pending", + "engine_baseline": "75d30dd57d71b91ee0929246b2f3cbb92263b350", + "roadmap_issue": 113, + "docs_only": true, + "certifies_now": [], + "information_boundaries": { + "inherited_m6_T_star": 2014, + "trustees_2026_role": "versioned forward assumption and report-only alignment; never gate-estimation evidence", + "realized_post_T_star_nawi_on_scored_path": "prohibited" + }, + "entry_seam": { + "metadata_key": "m6_scheduled_entries_by_year", + "definition_pin": "src/populace_dynamics/engine/loop.py:27", + "contract_pin": "src/populace_dynamics/engine/loop.py:192-257", + "frame_year": "entry_year - 1", + "activation": "top of period before mortality", + "new_period_module": false, + "ids_preassigned": true, + "synthetic_allocator_start": "max(initial and all scheduled person_id) + 1" + }, + "provisional_adjudications": { + "cohort_control": "gross new-person inflow after an explicit Social-Security-area-to-resident bridge", + "status_adjustment": "aggregate reclassification; not an entrant and not assigned to persons", + "emigration": "outside entry-builder v1; mandatory successor before net-alignment claim", + "assignment": "recent-arrival ACS joint donor units plus model-based calibration; no cloned future", + "runtime": "schedule built once per scenario and reused across K engine draws", + "legal_status_dynamics": "out of scope", + "current_entry_only_outputs": "report_only" + }, + "external_bindings": [ + { + "id": "ssa_tr2026_v_a2_intermediate", + "source": "2026 OASDI Trustees Report, section V.A.3, Table V.A2", + "vintage": "assumptions set February 2026; report released June 2026", + "role": "gross-entry control candidate and net reconciliation", + "status": "report_only_until_universe_bridge_and_exit_law" + }, + { + "id": "ssa_tr2026_v_a2_sensitivity", + "source": "2026 OASDI Trustees Report, Table V.A2 low-cost/high-cost", + "vintage": "2026", + "role": "scenario sensitivity", + "status": "report_only" + }, + { + "id": "ssa_area_to_census_resident_bridge", + "source": "unbound", + "vintage": "unbound", + "role": "population-universe bridge", + "status": "blocking_for_resident_alignment" + }, + { + "id": "acs_pums_2010_2014_recent_arrivals", + "source": "Census 2010-2014 ACS 5-year PUMS person file, dictionary, and accuracy statement", + "vintage": "observations 2010-2014; published January 2016", + "role": "fit 2010-2013; hold out 2014", + "status": "proposed_gate_binding_pending_O6" + }, + { + "id": "cps_asec_2014_foreign_born", + "source": "Census 2014 ASEC public-use file and technical documentation", + "vintage": "2014", + "role": "marginal triangulation", + "status": "report_only_pending_traditional_or_redesign_choice" + }, + { + "id": "sipp_2014_wave1_entry_state", + "source": "Census 2014 SIPP Wave 1 public-use file, metadata v2, and source/accuracy statement", + "vintage": "2013 reference year; 2014 interviews", + "role": "joint-state and initializer diagnostics", + "status": "report_only" + }, + { + "id": "census_np2023_nim_corridors", + "source": "Census 2023 National Population Projections, Alternative Scenarios Table 1", + "vintage": "November 2023", + "role": "main/high/low/zero net-international-migration corridors", + "status": "report_only" + }, + { + "id": "m6_projected_wage_index", + "source": "existing M6 <=2014 NAWI-derived I_proj binding", + "vintage": "realized through 2014; projected thereafter", + "role": "entrant earnings normalization", + "status": "reuse_without_certificate_transfer" + }, + { + "id": "emigration_duration_hazard", + "source": "unbound", + "vintage": "unbound", + "role": "allocate aggregate outflow controls to roster-present people", + "status": "blocking_for_explicit_exit_and_net_alignment" + } + ], + "gate_imm": { + "exists_now": false, + "estimand": "held-out ACS recent-arrival resident-stock characteristic reproduction", + "fit_collection_years": [2010, 2011, 2012, 2013], + "holdout_collection_years": [2014], + "count_alignment_gated": false, + "floors_before_thresholds": true, + "operating_characteristic_before_lock": true, + "downstream_life_course_certified": false + }, + "hardest_open_decisions": [ + "O1: gross entrants plus separate exits versus entry-only report-only v1 or a named net-entry proxy, including the SSA-area-to-resident bridge", + "O4: person versus co-arrival-family simulation units, relationship closure, and common versus person weights", + "O5: atomic downstream state/history packet and entrant-specific post-entry earnings, disability, marital, and household laws" + ], + "certified_surfaces_untouched": [ + "gate_m6 registry, thresholds, floors, hashes, and closed-panel support", + "candidate-16 marital core", + "candidate-9 household composition object", + "M4 disability reproduction object", + "certified earnings specifications and section 2.8.3a domain", + "section 2.8.2g marital domain law", + "amendment 3h live-roster materialization law", + "PeriodModules order and ProjectionRNGRegistry", + "SCHEDULED_ENTRIES_KEY contract and existing PSID openers", + "M7 trust-fund accounting and M8 rules execution" + ], + "amendment_history": [ + { + "revision": 1, + "date": "2026-07-15", + "kind": "initial_docs_only_design", + "changes": [ + "bind immigration activation to the existing scheduled-entry seam", + "separate gross entry controls from outflows, status adjustments, and net reconciliation", + "select donor-based entry state provisionally while prohibiting cloned futures", + "define the EntrantStateBundle and no-certificate-transfer boundary", + "propose floors-first gate_imm and enumerate external bindings and open referee decisions" + ] + } + ] +} +``` From 39ed2b58bbbb2e061f31eacd3d87e833f59aa555 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 17:47:07 -0400 Subject: [PATCH 04/18] docs: harden entrant state and engine composition contracts Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 280 ++++++++++++++++++++---------- 1 file changed, 187 insertions(+), 93 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index cdb9864a..c498c577 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -3,7 +3,7 @@ - **Design id**: `2026-07-15-immigration-module` - **Roadmap**: [#113](https://github.com/PolicyEngine/populace-dynamics/issues/113), M6 immigration entry cohorts and the versioned Trustees alignment layer. -- **Status**: DESIGN DRAFT (revision 1; adversarial-referee adjudication pending). +- **Status**: DESIGN DRAFT (revision 2; adversarial-referee adjudication pending). No immigration surface is certified by this document. - **Engine baseline**: `75d30dd57d71b91ee0929246b2f3cbb92263b350`. File:line pins refer to that tree unless a different source is named. @@ -16,6 +16,13 @@ ## Revision log (finding → section) +- Revision 2 incorporates the pre-PR adversarial review: it distinguishes the + ACS survivor/stayer stock proxy from state at arrival; treats prior U.S. + covered earnings as censored for possible return entrants; adds fertility, + claiming, flow-to-stock, and stock-to-arrival blockers; composes immigrant IDs + with the existing 2017/2019 schedule; guards caller-supplied allocators; and + requires entrant RNG isolation before any byte-identity claim → §2.2–2.4, + §3.1–3.4, §4.1–4.11, §5, §6, O2/O5/O9–O13. - Dormant-generator finding: the engine already owns an entrant seam, but there is no immigration schedule generator → §3.1, §4. - Net-is-not-entry finding: the 2026 Trustees component table distinguishes @@ -41,12 +48,16 @@ the top of its period. The proposed design makes four provisional choices, all reviewable by the referee: -1. Size literal entrant cohorts from **gross new-person inflows**, not from net - migration. In the 2026 Trustees table, adjustment of status is a - reclassification and is not a new person. -2. Use recent-arrival ACS donor units for the joint entry state. Estimation - creates a versioned donor artifact; the runtime schedule is deterministic - conditional on that artifact, a binding manifest, and a schedule seed. +1. Use the positive inflow components of the 2026 Trustees stock accounting, not + net migration, as the candidate size control. In that table, adjustment of + status is a reclassification and not a new person. The temporary/unlawfully + present inflow counts only people who remain to year-end, so it is not a count + of every border arrival. +2. Use recent-arrival ACS donor units for a joint **resident survivor/stayer + stock proxy**. A separately estimated stock-to-arrival bridge must backcast or + otherwise map that proxy before it can be called entry-time state. The runtime + schedule is deterministic conditional on the frozen artifacts, binding + manifest, and schedule seed. 3. Copy donor information only through entry. Post-entry outcomes come from named populace-dynamics laws; no donor's future is cloned. 4. Keep emigration outside the entry builder. Therefore entry-only v1 is @@ -54,10 +65,11 @@ referee: A separately designed exit law is mandatory before that claim can be made. The fourth choice is intentionally costly but honest. Substituting total net -change for actual entrants would create a reduced-form residual cohort whose age, +change for a positive entrant control would create a reduced-form residual cohort whose age, family, earnings, and nativity composition has no literal interpretation. In 2026, it would also replace 1.340 million gross arrivals with 0.130 million -residual persons. That alternative remains an explicit referee decision, not a +residual persons. The 1.340 million itself is an SSA stock-accounting inflow, +not all physical arrivals during the year. That alternative remains an explicit referee decision, not a silent implementation shortcut. ## 1. Scope and non-goals @@ -97,9 +109,11 @@ V1 specifies: - a proposed additive `gate_imm` for entrant characteristics; and - report-only reconciliation to SSA and Census population projections. -The design covers people whose latest entry places them in the United States for -the modeled spell. It does not assert that a survey's latest year-of-entry answer -identifies a first migration, a legal admission, or continuous U.S. residence. +The design covers people whose **reported year of entry** places them in the +recent-arrival proxy for the modeled spell. ACS interviewers request the most +recent entry from repeat entrants, but mail/self responses can be first or most +recent; the public item therefore does not establish a first migration, legal +admission, or continuous U.S. residence. ### 1.3 Non-goals @@ -132,8 +146,8 @@ weights, or a fabricated negative entrant cohort would confound distinct events. This is a component boundary, not a declaration that emigration is unimportant. MINT, DYNASIM, PENSIM, and PENSIM2 all provide evidence that literal entrant modeling and population alignment require exits. Until a separate exit design is -ratified, v1 may certify only entry-time characteristics conditional on a gross -inflow control. Every stock, dependency ratio, benefit total, and net-migration +ratified, v1 may certify only the named recent-arrival stock-proxy characteristics +conditional on a positive inflow control. Every stock, dependency ratio, benefit total, and net-migration reconciliation remains report-only. ## 2. Evidence and adjudication @@ -142,11 +156,11 @@ reconciliation remains report-only. | Model/source | Cohort count and exits | Entrant state | Transportable lesson | |---|---|---|---| -| DYNASIM4 | The 2024 overview says immigration adds people, immigration and emigration are separate, and immigration is aligned to OACT targets (Cosic, Johnson, and Smith, *[Urban's Dynamic Simulation of Income Model 4](https://www.urban.org/sites/default/files/2024-09/Urban%E2%80%99s%20Dynamic%20Simulation%20of%20Income%20Model%204.pdf)*, pp. 1–2). | The public 2024 overview does not document a detailed donor algorithm. | Cite DYNASIM4 only for separate flows and OACT alignment; do not attribute undocumented donor mechanics to it. | +| DYNASIM4 | The 2024 overview says immigration adds people, lists immigration and emigration separately, and says immigration is aligned to OACT targets (Cosic, Johnson, and Smith, *[Urban's Dynamic Simulation of Income Model 4](https://www.urban.org/sites/default/files/2024-09/Urban%E2%80%99s%20Dynamic%20Simulation%20of%20Income%20Model%204.pdf)*, pp. 1–2). | The public 2024 overview does not document a detailed donor algorithm. | Cite DYNASIM4 only for the listed flows and OACT alignment; do not attribute undocumented separation or donor mechanics to it. | | DYNASIM3 detail | Table 1 of Favreault, Smith, and Johnson, *[The Dynamic Simulation of Income Model (DYNASIM): An Overview](https://www.urban.org/sites/default/files/publication/67366/2000391-The-Dynamic-Simulation-of-Income-Model-DYNASIM-%20An-Overview.pdf)* (2015), p. 7, uses OACT/Dowhan-Duleep targets by sex, age at entry, and source region, and a separate SSA-data emigration hazard using entry age and origin. | The same table says observed post-1980 immigrants' life histories are donors. | Donor histories plus distinct exit hazards are a useful precedent, but this report describes DYNASIM3 and cannot establish DYNASIM4's detailed implementation. | -| MINT6/MINT8 | MINT6 derived gross flows from OACT net targets and an emigration hazard; MINT8 uses projected gross legal and other-than-legal entries and models emigration separately (Smith et al., *[Modeling Income in the Near Term Version 6](https://www.urban.org/sites/default/files/publication/24986/412479-Modeling-Income-in-the-Near-Term-Version-.PDF)*, ch. II §VI, pp. II-24–II-28; Smith and Favreault, *[MINT8 and 2014: Primer](https://www.urban.org/sites/default/files/publication/100965/modeling_income_in_the_near_term_8_and_2014_primer.pdf)*, pp. 15–16, note 21 p. 29, Table 3 pp. 39–40). | MINT6 uses post-1990 SIPP immigrants to initialize sex, immigration age, source region, marital history/status, financial assets, and employment at arrival. It then runs ordinary post-entry modules. | Copy a coherent entry packet, never a donor's future. An initializer and the later transition laws are separate estimands. | +| MINT6/MINT8 | MINT6 derived gross flows from OACT net targets and an emigration hazard; MINT8 uses projected gross legal and other-than-legal entries and models emigration separately (Smith et al., *[Modeling Income in the Near Term Version 6](https://www.urban.org/sites/default/files/publication/24986/412479-Modeling-Income-in-the-Near-Term-Version-.PDF)*, ch. II §VI, pp. II-24–II-28; Smith and Favreault, *[Modeling Income in the Near Term 8 and 2014: Primer](https://www.urban.org/sites/default/files/publication/100965/modeling_income_in_the_near_term_8_and_2014_primer.pdf)*, pp. 15–16, note 21 p. 29, Table 3 pp. 39–40). | MINT6 uses post-1990 SIPP immigrants to initialize sex, immigration age, source region, marital history/status, financial assets, and employment at arrival. It then runs ordinary post-entry modules. | Copy a coherent entry packet, never a donor's future. An initializer and the later transition laws are separate estimands. | | PENSIM | *[PENSIM Overview](https://www.retirementplanblog.com/wp-content/uploads/sites/304/2006/10/overview.pdf)* (Holmer, Janney, and Cohen, 2006), §2.1.6 p. 8, combines SSASIM/Trustees net immigration with native- and foreign-born emigration assumptions to derive gross flows; Appendix B §§B.1.2–B.1.4 pp. 100–101 schedules entry and exit from a life synthesized at birth. | A person's whole pre-entry life exists before the immigration event. | Whole-life synthesis avoids missing histories, but is not portable to a roster that materializes a person at entry. The needed analogue is an explicit entry-state packet. | -| PENSIM2 | O'Donoghue, Redway, and Lennon, *[Simulating migration in the Pensim2 dynamic microsimulation model](https://www.microsimulation.pub/articles/00039)* (2010), §5.1 and Figure 3, disaggregates ONS net controls into gross immigration and emigration. | §5.2 samples immigrant **families** from the 2003 Labour Force Survey and calibrates person totals; Table 2 contrasts cloning and synthetic approaches. | Preserve joint family state and distinguish the control unit from the donor/simulation unit. Net-only migration can bias population structure (§3 and §4). | +| PENSIM2 | O'Donoghue, Redway, and Lennon, *[Simulating migration in the Pensim2 dynamic microsimulation model](https://www.microsimulation.pub/articles/00039)* (2010), §5.1 and Figure 3, disaggregates ONS net controls into gross immigration and emigration. | §3 discusses synthetic generation versus cloning and Table 2 inventories model components; §5.2 samples immigrant **families** from the 2003 Labour Force Survey and calibrates person totals. | Preserve joint family state and distinguish the control unit from the donor/simulation unit. Net-only migration can bias population structure (§3 and §4). | MINT is the closest architectural analogue. Earlier MINT versions cloned a donor's later trajectory, but MINT6 “modifies this approach markedly”: donor @@ -171,15 +185,15 @@ emigration cannot be ignored. | Source | Exact public support | V1 role | Binding limitation | |---|---|---|---| -| ACS PUMS | Census, *[2010–2014 ACS 5-year PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* (Jan. 14, 2016): `SERIALNO`, `PWGTP`, `AGEP`, `CIT`, disability items, `MAR`, `SCHL`, `SEX`, `WAGP`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `PINCP`, and place of birth; the *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*, §3 pp. 5–7 and §4 p. 8, defines the pooled sample and dual-variable rule. | Primary joint-state donor and gate truth, weighted by `PWGTP` with replicate-weight uncertainty. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. `YOEP` is the latest entry, and `WAGP` covers the prior 12 months, possibly including pre-entry months. The 2016 publication date versus `T*=2014` is an open admissibility decision (§6.2, decision O6). | -| CPS ASEC | Census, *[2014 Annual Social and Economic Supplement Technical Documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian-noninstitutional sample; grouped entry years; survey-date demographics versus prior-calendar-year income; 2014 Traditional and Redesign files must never be silently combined. | +| ACS PUMS | Census, *[2010–2014 ACS 5-year PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* (Jan. 14, 2016): `SERIALNO`, `PWGTP`, `AGEP`, `CIT`, disability items, `MAR`, `RELP`, `SCHL`, `SEX`, `WAGP`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `PINCP`, and dual place-of-birth fields; the *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*, §3 pp. 5–7 and §4 p. 8, defines the pooled sample and dual-variable rule. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents the response concept and ambiguity. | Primary joint-stock donor and gate truth, weighted by `PWGTP` with replicate-weight uncertainty. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The 2016 publication date versus `T*=2014` is decision O6. | +| CPS ASEC | Census, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)* or *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: the cited Redesigned layout has demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian noninstitutional universe plus Armed Forces members living in civilian housing; grouped entry years; survey-date demographics versus prior-calendar-year income. Traditional and Redesign files must never be silently combined. | | SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves miss newly arrived immigrant-only households. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | The ACS donor predicate is named, not implied: ```text foreign_born == true -and 0 <= survey_year - latest_year_of_entry <= recent_arrival_max_duration +and 0 <= survey_year - reported_year_of_entry <= recent_arrival_max_duration ``` `survey_year` is decoded from `SERIALNO`; the correct `YOEP05`/`YOEP12` @@ -189,6 +203,12 @@ The extractor must bind allocation-flag treatment, top/bottom-code treatment, group-quarters policy, dual classifications, replicate weights, and the use of `ADJINC` before any artifact can be certified. +This predicate defines a resident **stock proxy**, not entry-time truth. Education, +marriage, disability, employment, earnings, survival, and residence may all +change between reported entry and interview. Directly copying that state onto an +entry-year row is only a named report-only initializer. A literal arrival-state +claim requires the separately bound stock-to-arrival bridge in §6.2/O11. + ### 2.3 Donor-based versus model-based assignment **Provisional adjudication: donor-based joint assignment, with model-based @@ -203,6 +223,8 @@ passing marginal cells would not establish a coherent person or family packet. trimming, allocation-flag policy, and calibration loss are fitted/versioned; - survey concepts are mapped to named entrant concepts with missing/unsupported states rejected rather than guessed; +- an explicit duration/backcast and survivor/stayer selection law maps the ACS + stock proxy to arrival state, or the result stays labeled `stock_proxy`; - a SIPP history donor, if used, is a second named imputation with its own joint- fidelity diagnostics; - future outcomes are never present in the donor artifact; and @@ -214,8 +236,10 @@ surface and floors. Lower marginal error alone is insufficient. ### 2.4 Gross inflow, net change, and status adjustment -The current control candidate is the *2026 OASDI Trustees Report*, §V.A.3 and -[Table V.A2, “Immigration Assumptions, Calendar Years 1940–2100”](https://www.ssa.gov/oact/TR/2026/lr5a2.html). +The current control candidate is *The 2026 Annual Report of the Board of Trustees +of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance +Trust Funds*, §V.A.3, released June 9, 2026, and the [Supplemental Single-Year +Table V.A2, “Immigration Assumptions, Calendar Years 1940–2100”](https://www.ssa.gov/oact/TR/2026/lr5a2.html). The assumptions were set in February 2026. Table V.A2 carries, separately, LPR new-arrival inflow, LPR/citizen outflow, adjustment to LPR status, LPR net change, temporary-or-unlawfully-present inflow, outflow, the offsetting status adjustment, @@ -225,9 +249,9 @@ For intermediate 2026, in thousands: | Component | Persons (thousands) | Entry-seam meaning | |---|---:|---| -| LPR new-arrival inflow | 600 | New-person inflow | -| Temporary/unlawfully present inflow | 740 | New-person inflow | -| **Gross new-person inflow** | **1,340** | Candidate entry-cohort total | +| LPR new-arrival inflow | 600 | SSA stock-accounting new-person inflow | +| Temporary/unlawfully present inflow | 740 | SSA stock-accounting new-person inflow, conditioned on remaining to year-end | +| **Positive SSA inflow components** | **1,340** | Candidate entry-control proxy, not every physical arrival | | LPR/citizen outflow | 263 | Exit, never an entrant | | Temporary/unlawfully present outflow | 947 | Exit, never an entrant | | Adjustment to LPR status | 450 in each stock, opposite signs | Internal reclassification; not a new person | @@ -238,6 +262,11 @@ V.A2 is annual and materially non-flat; the annual component values, not the average or ultimate constant, are the binding shape. Components may differ by rounding. +For the temporary/unlawfully present stock, “inflow” counts people who enter the +Social Security-area population and remain through the end of the year. Thus the +positive sum is neither a border-admissions series nor an unselected gross-arrival +flow. + The table's universe is the Social Security area, not the Census resident population. The report's glossary includes residents of U.S. territories, certain people abroad, and other groups absent from ACS PUMS. Therefore even @@ -265,8 +294,10 @@ The baseline contract is exact: `year == entry_year - 1` (`engine/loop.py:192-211`). - Every scheduled `person_id` is pre-supplied, globally unique across the initial slice and all cohorts (`engine/loop.py:213-221`). -- The dynamic synthetic-ID allocator starts above the maximum initial or - scheduled ID (`engine/loop.py:222-228`). +- If metadata does not already supply one, the dynamic synthetic-ID allocator is + created above the maximum initial or scheduled ID (`engine/loop.py:222-228`). + Because the code uses `setdefault`, a caller-supplied allocator is only + type-checked at `engine/loop.py:225-233`; v1 must separately range-check it. - Stable person RNG ordinals are preassigned over the complete initial-plus- scheduled ID universe before period 1 (`engine/loop.py:234-237`). - At entry year, the frame is concatenated and stably sorted at the very top of @@ -282,6 +313,13 @@ already publishes later PSID openers through the same key **immigration/new-entrant generator and its state packet**, not a generic engine entry mechanism. +The immigration builder must **compose with**, not replace, that existing mapping. +For each shared year it schema-reconciles and concatenates the unchanged PSID +opener frame with the immigrant frame, then validates one prior-year coordinate +and global ID uniqueness. It allocates immigrant IDs above the maximum of the +initial IDs **and every pre-existing scheduled ID**. Because all new IDs are above +that union, existing-person and existing-opener sorted ordinals remain unchanged. + ### 3.2 Consequences for timing, IDs, and RNG An entry frame is a pre-period state. Mortality sees it first @@ -293,16 +331,22 @@ settle whether an annual gross immigrant inflow should receive a full-year, half-year, or no domestic mortality exposure in its entry year. V1 therefore requires a named `entry_timing_basis` and a pre/post-aging age -identity check. Decision O2 must settle the convention before implementation; -the builder may not hide an age shift inside donor extraction. Whatever is -chosen, the schedule frame must use the seam's `year = entry_year - 1` contract. +identity check. The unchanged adapters implement only a full mortality draw at +the scheduled age followed by unconditional `age += 1`; they cannot express a +fractional exposure, defer aging, or output a target-year age-zero immigrant +without an entrant-aware wrapper. Decision O2 must choose that feasible existing +convention or authorize a separately scoped wrapper inside the mortality/aging +slots. The builder may not hide an age shift or age `-1` inside donor extraction, +and every choice retains the seam's `year = entry_year - 1` contract. IDs are assigned outside the loop in deterministic order. They must be finite -integers, greater than every starting-population ID, collision-free across all -years, and invariant to row order. These conditions preserve every original -person's sorted-ID ordinal. The loop then places the newborn allocator above all -scheduled IDs, so entrant IDs cannot collide with later births. No existing M6 -module stream is consumed to construct the schedule. +integers, greater than every starting-population **or pre-existing scheduled** ID, +collision-free across all years, and invariant to row order. These conditions +preserve every original and PSID-opener sorted-ID ordinal. Projection metadata +must omit a pre-supplied synthetic allocator, or assert its mutable `next_id` is +strictly above the combined maximum before period 1; otherwise the loop does not +protect births from collision. No existing M6 module stream is consumed to +construct the schedule. ### 3.3 Amendment 3h: live-roster materialization @@ -312,17 +356,18 @@ and draft [PR #216](https://github.com/PolicyEngine/populace-dynamics/pull/216). This sibling design adopts its domain law as a dependency while accurately describing its pending merge status: -> Scheduled open-addition events may materialize a related person only when the -> required parent/person is present in the live post-mortality roster. The -> frame-independent risk schedule may remain the scoring universe; absent-parent -> events are dropped after the draw and reconciled report-only so RNG addresses -> do not shift. +> A scheduled maternal birth may materialize a child only when the mother is +> present in the live post-mortality roster. The frame-independent risk schedule +> may remain the scoring universe; absent-mother events are dropped after the draw +> and reconciled report-only so RNG addresses do not shift. -Entrants are roster-present when their own rows are activated. Their later -marriages, births, household links, and exits must still obey live-roster -materialization. A donor packet may not create a spouse, child, or other relation -whose person row is absent, and it may not weaken the existing birth-parent guard -at `engine/steps.py:409-414`. +Entrants are roster-present when their own rows are activated, and their later +maternal births obey this exact 3h law. V1 separately proposes a broader +**immigration relationship-closure invariant**: a donor packet may not materialize +a linked spouse, child, or other person whose row is absent. That new invariant +is analogous to, but not certified by, 3h; becoming `married` in the marital core +does not itself materialize a spouse person. Neither law may weaken the existing +birth-parent guard at `engine/steps.py:409-414`. ### 3.4 Why an entry row is not an initialized person @@ -341,9 +386,11 @@ projection once per draw: - earnings initialization runs only on the original initial slice (`engine/assembly.py:239-250`; `engine/loop.py:180-185`). -Worse, `_merge_period_columns` drops existing state columns before left-merging -the cached update (`engine/assembly.py:174-192`). An immigrant absent from that -update receives missing state even if the scheduled row carried a seed value. +When a cached update has rows for the current year, `_merge_period_columns` drops +existing state columns before left-merging it (`engine/assembly.py:174-192`). An +immigrant absent from that nonempty update receives missing state even if the +scheduled row carried a seed value; only a wholly empty year returns the frame +unchanged. The later PSID openers work because their realized support is known to the whole-window builders in advance. An unknown synthetic immigrant has no such support. @@ -384,9 +431,9 @@ The design separates source estimation, scenario binding, schedule realization, and period activation: ```text -ACS <=T* records ──fit──> ImmigrationDonorArtifact ─┐ - ├─> ImmigrationScheduleBuilder -SSA annual components ──bind──> BindingManifest ───┘ │ +ACS <=T* records ──fit──> ImmigrationDonorArtifact ─> ArrivalStateBridge ─┐ + ├─> ImmigrationScheduleBuilder +SSA annual components ──bind──> BindingManifest ─────────────────────────┘ │ ├─> entry frames SIPP/CPS ──diagnostics only───────────────────────────────────────┤ ├─> EntrantStateBundle @@ -402,6 +449,8 @@ The conceptual products are: annual flow controls, universe labels, and scenario identity; - **`ImmigrationDonorArtifact`**: a fitted pool of recent-arrival person or family units, matching cells, fallback hierarchy, concept mappings, and provenance; +- **`ArrivalStateBridge`**: an estimated duration/backcast and selection law, or + an explicit `stock_proxy` identity label that prohibits an arrival-state claim; - **`EntrantStateBundle`**: the entry frame plus module-native initial state and exposure objects for the same people; - **`ImmigrationSchedule`**: `entries_by_year`, the state bundle, deterministic @@ -409,8 +458,9 @@ The conceptual products are: - **`ImmigrationAudit`**: cohort totals, donor support, calibration residuals, universe caveats, dropped/unsupported units, hashes, and certification labels. -`ImmigrationSchedule.entries_by_year` is the only product sent to -`SCHEDULED_ENTRIES_KEY`. The state bundle is consumed by explicit entrant-side +The builder merges `ImmigrationSchedule.entries_by_year` with the pre-existing +mapping and sends that single combined mapping to `SCHEDULED_ENTRIES_KEY`; it +never overwrites the PSID opener frames. The state bundle is consumed by explicit entrant-side builders/adapters assembled before projection. There is no entrant event draw in the annual engine loop. @@ -424,6 +474,8 @@ The campaign's estimation/determinism split is binding: - donor unit, matching variables, and fallback order; - sampling/calibration loss and weight trimming; - any ACS→SIPP joint-history imputation; +- the stock-to-arrival duration/selection bridge, return-entry treatment, and + fertility/parity and prior-coverage mappings; - any entrant-specific earnings or disability initializer; and - every evaluation floor and eventual gate threshold. @@ -448,7 +500,7 @@ process-error draws. For Trustees calendar year `y`, define the unbridged new-person control ```text -G_ssa[y] = 1,000 * ( +G_ssa_stock[y] = 1,000 * ( V_A2_intermediate[y].lpr_new_arrival_inflow + V_A2_intermediate[y].temporary_or_unlawfully_present_inflow ) @@ -458,9 +510,10 @@ Adjustment of status is excluded because the same person moves between the two Trustees stocks. Outflows are excluded because they are exit events. The intermediate total-net column is retained as `N_ssa[y]` for reconciliation only. -`G_ssa` is not yet a usable resident-population cohort. Production construction +`G_ssa_stock` is not yet a usable resident-population cohort. It includes the +temporary/unlawfully present end-of-year-stayer condition. Production construction requires an adjudicated, vintage-pinned bridge -`G_resident[y] = bridge(G_ssa[y])` between the Social Security-area and ACS +`G_resident_entry_proxy[y] = bridge(G_ssa_stock[y])` between the Social Security-area stock accounting and ACS resident universes. Until decision O1 supplies that bridge, the builder must either hard-stop or produce an explicitly named `ssa_area_proxy` schedule whose entire projection is report-only. It may not silently set the bridge to identity @@ -491,10 +544,12 @@ people, while the state to preserve may be a family. V1's provisional unit is a **co-resident co-arrival unit**, not a claimed historical travel party: 1. Start with a PUMS household (`SERIALNO`). -2. Select foreign-born recent-arrival people with the same latest-year-of-entry +2. Select foreign-born recent-arrival people with the same reported-year-of-entry classification. -3. Preserve spouse/partner and parent/minor-child links only when both endpoints - are in that selected set. +3. Preserve only links unambiguously resolvable from the historical PUMS `RELP` + relationship-to-reference-person field (for example, the reference person's + spouse and children) when both endpoints are selected. Arbitrary spouse/parent + pointers are unavailable and remain unresolved. 4. Assign a new `arrival_unit_id`; never expose `SERIALNO` as a synthetic person or household identifier. @@ -522,13 +577,18 @@ The fitted donor artifact preserves, at minimum: - race and Hispanic-origin fields only where a downstream/reporting contract already has a defined concept; - marital status/history fields available at the survey date; -- co-resident relationship structure and unit size; +- reference-person relationship structure resolvable from `RELP`, unresolved- + relation markers, and unit size; - ACS disability-question indicators, without relabeling them DI status; - employment, weeks/hours where available, wage/salary earnings, self-employment earnings, and zero-earnings status; and -- survey year, latest year of entry, observed duration, allocation flags, donor +- survey year, reported year of entry, observed duration, allocation flags, donor weight, and all concept-map provenance. +These are **interview-date stock characteristics**. They become entry-time +characteristics only after the `ArrivalStateBridge`; an identity bridge must be +named `stock_proxy` and is report-only. + The default matching ladder begins with sex × broad age-at-entry × source region and then uses education and family state when support permits, consistent with the MINT/Duleep-Dowhan precedent. The precise cells are selected and frozen @@ -556,17 +616,35 @@ any stochastic calibration use named `purpose_tag` values so adding one draw doe not shift another purpose's addresses. After the full schedule is realized, IDs are allocated in stable order -`(entry_year, unit_slot, member_slot)` beginning above the maximum initial -`person_id`. The builder stores the allocation ledger and verifies global -uniqueness before calling the engine. Arrival-unit and household IDs use their -own namespaces and may not alias person IDs. +`(entry_year, unit_slot, member_slot)` beginning above the maximum `person_id` +across the initial population **and the full pre-existing schedule**. The builder +stores the allocation ledger, merges same-year frames without changing their +existing rows, and verifies global uniqueness before calling the engine. +Arrival-unit and household IDs use their own namespaces and may not alias person +IDs. + +The metadata adapter omits `synthetic_id_allocator` so the loop creates it from +the combined universe. If another caller requires a supplied allocator, the +adapter asserts `allocator.next_id > max(combined_person_ids)` before period 1; +the loop's type check alone is insufficient. Changing a source vintage, donor artifact, recent-arrival definition, or schedule seed creates a new schedule identity. The design does not promise entrant or newborn byte identity across such scenarios. It does promise that, within one schedule, pre-supplying entrant IDs above the initial maximum leaves every original person's sorted-ID ordinal unchanged and lets the engine place its -dynamic allocator above every scheduled entrant. +dynamic allocator above every scheduled entrant only under the preceding +metadata guard. + +Downstream RNG needs a separate isolation law. C16, fertility, and candidate-9 +consume shared ordered generators, so merely adding entrants to their panels can +shift existing-person draws even though person ordinals are stable. A composite +adapter must run the baseline closed support in its original order with its +original generators, run entrant-only transitions under named disjoint +draw×period×person namespaces, and return one authoritative partitioned marital +result to the existing fertility/household reader slots. Any cross-domain +marriage or household reconciliation that can change baseline people is a +distinct report-only open-market product; it makes no byte-identity claim. ### 4.7 Entry-frame schema and hard invariants @@ -576,8 +654,8 @@ Every scheduled entry frame contains these conceptual groups: |---|---| | Engine | `person_id`, `year`, `age`, `sex`, `weight` | | Entry identity | `synthetic_entry = true`, `entry_kind = "immigration"`, `entry_year`, `arrival_unit_id`, `foreign_born = true` | -| Timing | `entry_timing_basis`, `age_timing_basis`, `years_since_entry = 0` | -| Provenance | binding-manifest ID/hash, donor-artifact ID/hash, schedule ID/seed, donor-cell and fallback code | +| Timing | `entry_timing_basis`, `age_timing_basis`, `reported_year_of_entry`, `entry_year`; `years_since_entry` is derived, not stored as mutable state | +| Provenance | binding-manifest ID/hash, donor-artifact and arrival-state-bridge ID/hash, schedule ID/seed, donor-cell and fallback code | | Static/donor state | education, source region, marital/family seed, employment/earnings seed, disability-concept seed, household seed | | Domain markers | `earnings_domain = false` and named entrant-domain flags for every composite adapter | @@ -590,7 +668,7 @@ Before engine invocation the builder hard-checks: - each frame has exactly `year = entry_year - 1`; - pre/post-aging age identities match decision O2; - person IDs are finite integers, globally unique, and greater than the initial - maximum; + and every pre-existing scheduled maximum; - all relation endpoints are either scheduled no later than the relation's materialization year or explicitly marked outside-roster; - weights are finite, positive, and reconcile at person and unit level; @@ -603,6 +681,10 @@ Before engine invocation the builder hard-checks: Any failure aborts before period 1. There is no nearest-year, nearest-vintage, native-donor, legal-status, or fabricated-history fallback. +Every entrant adapter derives `years_since_entry = context.year - entry_year` at +read time. `advance_age` does not update that field, so a mutable carried counter +is prohibited. + ### 4.8 `EntrantStateBundle` The state bundle is atomic by scheduled person ID and contains: @@ -613,7 +695,9 @@ The state bundle is atomic by scheduled person ID and contains: | `entrant_marital_seed` | Entry state/history, risk-set start year, relation IDs only for roster-present people, and entrant-domain marker. | | `entrant_household_seed` | Arrival-unit household links, household state, and entry-year exposure mask. | | `entrant_disability_seed` | Survey-concept indicators plus the explicitly estimated mapping to any entrant disability state. | -| `entrant_earnings_seed` | Entry employment/earnings state, zero pre-entry U.S.-covered history, any entrant-specific lag state, and normalization provenance. | +| `entrant_fertility_seed` | Prior parity/birth-history state, its source/uncertainty, and an exposure-start rule; absent a bound bridge the entrant is excluded from fertility risk. | +| `entrant_earnings_seed` | Current-spell entry employment/earnings state, censored/unknown prior U.S.-covered history, any entrant-specific lag state, and normalization provenance. | +| `entrant_claiming_seed` | `claimed`, `claim_age`, `claim_year`, prior-coverage/insured-status provenance, and an eligibility-domain marker. | | `entrant_relationship_roster` | Parent/spouse/child endpoints and the first year each endpoint can materialize. | | `entrant_audit` | Donor support, fallback, imputation, weight, universe, and hash records. | @@ -626,9 +710,11 @@ passing marginal checks. The packet includes only state through entry and the minimum pre-entry history needed to define a downstream covariate. It never contains realized post-entry outcomes. Foreign earnings may inform education/occupation matching if a future -source supports it, but U.S. Social Security covered earnings before modeled -entry are zero. Return migration is not inferred from a latest-entry response; -handling prior U.S. coverage is a successor design. +source supports it. Because reported year of entry does not identify first entry, +prior U.S. Social Security covered earnings are **unknown/censored**, not zero. +A separately named first-entry-only scenario may set them to zero only with an +adjudicated identification rule; otherwise insured-status and benefit outputs are +suppressed. Return migration and prior coverage are decision O11. ### 4.9 Downstream module-state contract @@ -637,10 +723,10 @@ handling prior U.S. coverage is a successor design. | Mortality | An activated entrant mechanically receives the existing age/sex mortality draw before aging. Decision O2 must define first-year exposure. | Mortality drift is already report-only; applying it to entrants is not newly certified. Emigration may not be encoded as excess mortality. | | Aging | The existing deterministic `advance_age` runs unchanged after the prior-year coordinate check. | Plumbing only; the entry-age convention, not the function, is the new law. | | Marital core | An entrant-side panel builder supplies one admissible entry seed and risk-set start. A production open-panel adapter may combine markets only in a report-only run. | Candidate-16's PSID certificate does not transfer to immigrants or to cross-domain matching. Closed-panel scored outputs must remain unchanged. | -| Fertility | Co-arriving children are entrant rows. Children conceived/born after entry use the normal fertility path and amendment-3h live-roster materialization. | No absent donor relative may be materialized. Entrant fertility remains report-only. | +| Fertility | Co-arriving children are entrant rows but do not reveal all prior births. The current kernel initializes parity to zero (`engine/marital.py:313`), so entrants are excluded from its fertility risk IDs until a bound parity/history seed and entrant-aware kernel exist. Later maternal births then use amendment-3h live-roster materialization. | No parity-zero default and no absent mother. Entrant fertility is blocked/report-only pending O12. | | Disability | ACS disability questions and SIPP work-limit/benefit concepts feed a separately estimated entrant initializer/forward law; they are never relabeled as the realized PSID M4 status. | M4 reproduction support and certificate stay unchanged. Entrant disability is a successor-gate surface. | -| Earnings | Entrants remain `earnings_domain = false`. A separate immigrant-entrant generator owns entry earnings and all later entrant earnings until a future handoff law is designed. It uses zero pre-entry U.S.-covered earnings and a pinned wage normalization. | No fake 2014 earnings, `u_w`, `gen_earn_w2`, or `gen_earn_w4`; the §2.8.3a generator is untouched and its certificate does not transfer. | -| Claiming | The schedule may be reused as plumbing, but insured status and AIME/PIA must use only simulated U.S.-covered earnings. | Entrant claims and benefits are report-only until earnings/history and eligibility concepts are certified. | +| Earnings | Entrants remain `earnings_domain = false`. A separate immigrant-entrant generator owns current-spell entry earnings and all later entrant earnings until a future handoff law is designed. Prior U.S.-covered history remains censored unless O11 supplies it. | No fake 2014 earnings, `u_w`, `gen_earn_w2`, or `gen_earn_w4`; the §2.8.3a generator is untouched and its certificate does not transfer. | +| Claiming | Entrants are excluded by an eligibility-domain adapter unless the state packet resolves prior/current covered quarters and insured status. This is necessary because current `apply_claiming` draws for every person age 50+ without testing insurance, AIME, or PIA (`engine/steps.py:320-378`). | No unconditional claiming draw; entrant claims and benefits are blocked/report-only until O5/O11 and an eligibility gate. | | Household composition | An entrant-side native panel starts exposure at entry, carries arrival-unit links, and makes no link to an absent person. | Candidate-9's PSID certificate does not transfer. Open-market effects on existing people are report-only. | The scored M6 closed-panel run and an open-population production run are distinct @@ -653,7 +739,7 @@ retroactively change the frozen closed-panel gate or its certificate. The v1 audit publishes, by year: ```text -gross_entry_control +ssa_stock_accounting_inflow_control scheduled_entry_weight trustees_gross_outflow_required trustees_status_adjustment_reclassification @@ -708,7 +794,7 @@ The candidate estimand is narrow: > entry-state marginals and named joint distributions at their empirical noise > floor? -This is not a gate on external cohort counts: exact agreement with a forced +This is not a gate on literal arrival-time state or external cohort counts: exact agreement with a forced control is tautological. It is not truth for gross arrivals, people who left or died before interview, legal status, or post-entry trajectories. @@ -745,24 +831,31 @@ to which no exact-artifact certificate automatically transfers. The ceremony order is mandatory: -1. Freeze the recent-arrival predicate, donor/simulation unit, concept map, - matching ladder, gate cells, metrics, and weighting rules without candidate - holdout results. +1. Using training-only power analysis, freeze the recent-arrival predicate, + donor/simulation unit, physical annual sample size, weight caps, calibration + constraints, fallback limits, schedule-seed grid and aggregation/conjunction + rule, concept map, matching ladder, gate cells, metrics, and weighting rules + without candidate holdout results. 2. Construct a correlation-respecting real-vs-real floor from deterministic, household-disjoint splits or survey replicate-weight pseudo-replicates of the 2014 truth. Never split members of one donor/household unit. -3. Publish, for every proposed cell, raw person count, raw unit count, weighted - effective sample size - `n_eff = (sum(w))^2 / sum(w^2)`, denominator, allocation share, top-code share, - and the distribution of the chosen distance under truth-vs-truth comparison. -4. Prune, pool, or demote every cell that fails predeclared support or whose floor +3. On training-era pseudo-holdouts only, run the complete donor-selection, + calibration, fallback, and schedule pipeline across the registered seed grid. + Freeze how candidate-pipeline variability combines with the truth-side floor; + no favorable single schedule seed can define a PASS. +4. Publish, for every proposed cell, raw person count, raw unit count, person- + weight Kish ESS, cluster/unit-weight ESS, replicate-design variance, + denominator, allocation share, top-code share, and both truth-side and + pipeline distance distributions. The binding support measure is the most + conservative applicable unit/design quantity, not person ESS alone. +5. Prune, pool, or demote every cell that fails predeclared support or whose floor is unstable. Record each demotion; do not widen a threshold to retain it. -5. Price thresholds from the surviving empirical floors using a predeclared +6. Price thresholds from the surviving empirical floors using a predeclared transform. No numerical tolerance is assumed by this design. -6. Run an operating-characteristic experiment on the surviving conjunction +7. Run an operating-characteristic experiment on the surviving conjunction using predeclared degraded pseudo-candidates. If power is weak or the gate is near-tautological, pause and redesign before any lock. -7. Only then score the registered candidate and, if it passes, bind the exact +8. Only then score the registered candidate and, if it passes, bind the exact artifacts, floor, registry, code commit, and hashes. This order is the M6 floors-before-thresholds law. Sparse single-age MINT6 cohorts @@ -815,8 +908,9 @@ A `gate_imm` PASS could certify only: surviving registry named in the lock; - reproduction of the named held-out ACS recent-arrival resident-stock cross-sections within floor-priced thresholds; and -- deterministic conversion of that artifact into seam-valid entry frames and a - complete entrant-state packet. +- deterministic conversion of that artifact into seam-valid entry frames and + **structural/schema completeness** of the packet fields exercised by the gate. + It would not substantively validate latent histories or module-native mappings. It would not certify gross-flow truth, the Social Security-area→resident bridge, emigration, legal status, current-vintage refits, composition through 2100, @@ -825,8 +919,8 @@ died before interview, any post-entry transition, any interaction with the closed population, or any Social Security eligibility/benefit result. It also would not modify or extend the M6 certificate. Entrants remain family-B -open additions under `m6_reporting.py:71-73` and its explicit immigrant -person-row bridge at `m6_reporting.py:104-118` until a later ratified gate says +open additions under `harness/m6_reporting.py:71-73` and its explicit immigrant +person-row bridge at `harness/m6_reporting.py:104-118` until a later ratified gate says otherwise. ## 6. External bindings From f6d5917a6979300ba9b84a4bfd9c30ad7c2ea021 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 17:52:41 -0400 Subject: [PATCH 05/18] Harden entrant semantics and decision references Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 49 +++++++++++++++---------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index c498c577..40fb3d10 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -22,12 +22,12 @@ claiming, flow-to-stock, and stock-to-arrival blockers; composes immigrant IDs with the existing 2017/2019 schedule; guards caller-supplied allocators; and requires entrant RNG isolation before any byte-identity claim → §2.2–2.4, - §3.1–3.4, §4.1–4.11, §5, §6, O2/O5/O9–O13. + §3.1–3.4, §4.1–4.11, §5, §6, O2/O5/O8–O14. - Dormant-generator finding: the engine already owns an entrant seam, but there is no immigration schedule generator → §3.1, §4. - Net-is-not-entry finding: the 2026 Trustees component table distinguishes - 1.340 million gross new-person inflows from 0.130 million total net change in - 2026 → §2.4, §4.3, §4.10. + 1.340 million positive stock-accounting inflows from 0.130 million total net + change in 2026 → §2.4, §4.3, §4.10. - No-history finding: a row inserted through the seam is absent from the cached marital, disability, household, and earnings support objects → §3.4, §4.7–4.9. - Certificate-boundary finding: §2.8.3a, §2.8.2g, and amendment 3h prohibit @@ -207,7 +207,7 @@ This predicate defines a resident **stock proxy**, not entry-time truth. Educati marriage, disability, employment, earnings, survival, and residence may all change between reported entry and interview. Directly copying that state onto an entry-year row is only a named report-only initializer. A literal arrival-state -claim requires the separately bound stock-to-arrival bridge in §6.2/O11. +claim requires the separately bound stock-to-arrival bridge in §6.2/O12. ### 2.3 Donor-based versus model-based assignment @@ -413,10 +413,10 @@ The sibling M6 design's three laws bind this module: universe at builder/domain entry. The immigrant analogue is to construct a named entrant risk-set seed; it is not to weaken the core or pretend the PSID certificate covers the new population. -- **Fertility amendment 3h**: distinguish a frame-independent scoring schedule - from live-roster materialization. No related row may be materialized against an - absent person merely because that person exists in a donor or cached support - artifact. +- **Fertility amendment 3h**: distinguish a frame-independent maternal-birth + scoring schedule from live-roster materialization; a child may materialize + only against a live mother. The broader relationship-closure rule in §3.3 is a + new immigration invariant, not part of the 3h certificate. No existing certificate transfers across these bridges. Reuse of unchanged core code may be plumbing at implementation time, but applying it to an entrant @@ -431,16 +431,13 @@ The design separates source estimation, scenario binding, schedule realization, and period activation: ```text -ACS <=T* records ──fit──> ImmigrationDonorArtifact ─> ArrivalStateBridge ─┐ - ├─> ImmigrationScheduleBuilder -SSA annual components ──bind──> BindingManifest ─────────────────────────┘ │ - ├─> entry frames -SIPP/CPS ──diagnostics only───────────────────────────────────────┤ - ├─> EntrantStateBundle -Census scenarios ──report-only corridors─────────────────────────┘ +ACS <=T* ─> DonorArtifact ─> ArrivalStateBridge ─┐ +SSA components ─────────────> BindingManifest ───┼─> ScheduleBuilder +SIPP/CPS ─────────────> diagnostic/bridge evidence┘ ├─> entry frames +Census scenarios ─────────────> report-only corridor audit └─> StateBundle entry frames ──metadata[SCHEDULED_ENTRIES_KEY]──> existing engine loop -EntrantStateBundle ──entrant-only adapters/builders──> downstream state +StateBundle ──entrant-only adapters/builders──> downstream state ``` The conceptual products are: @@ -514,7 +511,7 @@ intermediate total-net column is retained as `N_ssa[y]` for reconciliation only. temporary/unlawfully present end-of-year-stayer condition. Production construction requires an adjudicated, vintage-pinned bridge `G_resident_entry_proxy[y] = bridge(G_ssa_stock[y])` between the Social Security-area stock accounting and ACS -resident universes. Until decision O1 supplies that bridge, the builder must +resident universes. Until decision O11 supplies that bridge, the builder must either hard-stop or produce an explicitly named `ssa_area_proxy` schedule whose entire projection is report-only. It may not silently set the bridge to identity and label the result resident-population aligned. @@ -556,8 +553,8 @@ people, while the state to preserve may be a family. V1's provisional unit is a A spouse, child, or parent who is native-born, entered in a different year, or is absent from the PUMS household is not cloned. The entrant may retain an observed marital/parental state with a named `relation_outside_entry_roster` marker, but -no related synthetic row or relationship ID is invented. This is required by -amendment 3h. +no related synthetic row or relationship ID is invented. This is the new +immigration relationship-closure invariant in §3.3, not a 3h-certified claim. Sampling whole units while calibrating person totals requires an explicit rule for within-unit weights. The provisional invariant is one common simulation @@ -714,7 +711,7 @@ source supports it. Because reported year of entry does not identify first entry prior U.S. Social Security covered earnings are **unknown/censored**, not zero. A separately named first-entry-only scenario may set them to zero only with an adjudicated identification rule; otherwise insured-status and benefit outputs are -suppressed. Return migration and prior coverage are decision O11. +suppressed. Return migration and prior coverage are decision O12. ### 4.9 Downstream module-state contract @@ -723,10 +720,10 @@ suppressed. Return migration and prior coverage are decision O11. | Mortality | An activated entrant mechanically receives the existing age/sex mortality draw before aging. Decision O2 must define first-year exposure. | Mortality drift is already report-only; applying it to entrants is not newly certified. Emigration may not be encoded as excess mortality. | | Aging | The existing deterministic `advance_age` runs unchanged after the prior-year coordinate check. | Plumbing only; the entry-age convention, not the function, is the new law. | | Marital core | An entrant-side panel builder supplies one admissible entry seed and risk-set start. A production open-panel adapter may combine markets only in a report-only run. | Candidate-16's PSID certificate does not transfer to immigrants or to cross-domain matching. Closed-panel scored outputs must remain unchanged. | -| Fertility | Co-arriving children are entrant rows but do not reveal all prior births. The current kernel initializes parity to zero (`engine/marital.py:313`), so entrants are excluded from its fertility risk IDs until a bound parity/history seed and entrant-aware kernel exist. Later maternal births then use amendment-3h live-roster materialization. | No parity-zero default and no absent mother. Entrant fertility is blocked/report-only pending O12. | +| Fertility | Co-arriving children are entrant rows but do not reveal all prior births. The current kernel initializes parity to zero (`engine/marital.py:313`), so entrants are excluded from its fertility risk IDs until a bound parity/history seed and entrant-aware kernel exist. Later maternal births then use amendment-3h live-roster materialization. | No parity-zero default and no absent mother. Entrant fertility is blocked/report-only pending O13. | | Disability | ACS disability questions and SIPP work-limit/benefit concepts feed a separately estimated entrant initializer/forward law; they are never relabeled as the realized PSID M4 status. | M4 reproduction support and certificate stay unchanged. Entrant disability is a successor-gate surface. | -| Earnings | Entrants remain `earnings_domain = false`. A separate immigrant-entrant generator owns current-spell entry earnings and all later entrant earnings until a future handoff law is designed. Prior U.S.-covered history remains censored unless O11 supplies it. | No fake 2014 earnings, `u_w`, `gen_earn_w2`, or `gen_earn_w4`; the §2.8.3a generator is untouched and its certificate does not transfer. | -| Claiming | Entrants are excluded by an eligibility-domain adapter unless the state packet resolves prior/current covered quarters and insured status. This is necessary because current `apply_claiming` draws for every person age 50+ without testing insurance, AIME, or PIA (`engine/steps.py:320-378`). | No unconditional claiming draw; entrant claims and benefits are blocked/report-only until O5/O11 and an eligibility gate. | +| Earnings | Entrants remain `earnings_domain = false`. A separate immigrant-entrant generator owns current-spell entry earnings and all later entrant earnings until a future handoff law is designed. Prior U.S.-covered history remains censored unless O12 supplies it. | No fake 2014 earnings, `u_w`, `gen_earn_w2`, or `gen_earn_w4`; the §2.8.3a generator is untouched and its certificate does not transfer. | +| Claiming | Entrants are excluded by an eligibility-domain adapter unless the state packet resolves prior/current covered quarters and insured status. This is necessary because current `apply_claiming` draws for every person age 50+ without testing insurance, AIME, or PIA (`engine/steps.py:320-378`). | No unconditional claiming draw; entrant claims and benefits are blocked/report-only until O5/O12 and an eligibility gate. | | Household composition | An entrant-side native panel starts exposure at entry, carries arrival-unit links, and makes no link to an absent person. | Candidate-9's PSID certificate does not transfer. Open-market effects on existing people are report-only. | The scored M6 closed-panel run and an open-population production run are distinct @@ -791,7 +788,7 @@ The candidate estimand is narrow: > Conditional on the named recent-arrival resident-stock proxy and its survey > universe, does the frozen donor/schedule procedure reproduce held-out ACS -> entry-state marginals and named joint distributions at their empirical noise +> recent-arrival stock-proxy marginals and named joint distributions at their empirical noise > floor? This is not a gate on literal arrival-time state or external cohort counts: exact agreement with a forced @@ -888,8 +885,8 @@ The following are useful but are not gate truth: - SIPP 2014 Wave 1 joint plausibility for marital, employment/earnings, disability, and nativity/entry concepts; - ACS 2015–2019 and 2020–2024 drift from the frozen donor composition; -- 2026 Trustees low-cost/intermediate/high-cost gross inflows, outflows, and - total-net paths; +- 2026 Trustees low-cost/intermediate/high-cost positive stock-accounting inflows, + outflows, and total-net paths; - the 2023 Census National Population Projections main/high/low/zero immigration corridors; and - foreign-born population stocks, dependency ratios, AIME/PIA, DI, claiming, From a99a485d752179913dbb0fd041de364d4481bc90 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 17:54:54 -0400 Subject: [PATCH 06/18] Bind unresolved entrant evidence and referee choices Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 110 ++++++++++++++++++++++-------- 1 file changed, 81 insertions(+), 29 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 40fb3d10..8333056f 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -159,7 +159,7 @@ reconciliation remains report-only. | DYNASIM4 | The 2024 overview says immigration adds people, lists immigration and emigration separately, and says immigration is aligned to OACT targets (Cosic, Johnson, and Smith, *[Urban's Dynamic Simulation of Income Model 4](https://www.urban.org/sites/default/files/2024-09/Urban%E2%80%99s%20Dynamic%20Simulation%20of%20Income%20Model%204.pdf)*, pp. 1–2). | The public 2024 overview does not document a detailed donor algorithm. | Cite DYNASIM4 only for the listed flows and OACT alignment; do not attribute undocumented separation or donor mechanics to it. | | DYNASIM3 detail | Table 1 of Favreault, Smith, and Johnson, *[The Dynamic Simulation of Income Model (DYNASIM): An Overview](https://www.urban.org/sites/default/files/publication/67366/2000391-The-Dynamic-Simulation-of-Income-Model-DYNASIM-%20An-Overview.pdf)* (2015), p. 7, uses OACT/Dowhan-Duleep targets by sex, age at entry, and source region, and a separate SSA-data emigration hazard using entry age and origin. | The same table says observed post-1980 immigrants' life histories are donors. | Donor histories plus distinct exit hazards are a useful precedent, but this report describes DYNASIM3 and cannot establish DYNASIM4's detailed implementation. | | MINT6/MINT8 | MINT6 derived gross flows from OACT net targets and an emigration hazard; MINT8 uses projected gross legal and other-than-legal entries and models emigration separately (Smith et al., *[Modeling Income in the Near Term Version 6](https://www.urban.org/sites/default/files/publication/24986/412479-Modeling-Income-in-the-Near-Term-Version-.PDF)*, ch. II §VI, pp. II-24–II-28; Smith and Favreault, *[Modeling Income in the Near Term 8 and 2014: Primer](https://www.urban.org/sites/default/files/publication/100965/modeling_income_in_the_near_term_8_and_2014_primer.pdf)*, pp. 15–16, note 21 p. 29, Table 3 pp. 39–40). | MINT6 uses post-1990 SIPP immigrants to initialize sex, immigration age, source region, marital history/status, financial assets, and employment at arrival. It then runs ordinary post-entry modules. | Copy a coherent entry packet, never a donor's future. An initializer and the later transition laws are separate estimands. | -| PENSIM | *[PENSIM Overview](https://www.retirementplanblog.com/wp-content/uploads/sites/304/2006/10/overview.pdf)* (Holmer, Janney, and Cohen, 2006), §2.1.6 p. 8, combines SSASIM/Trustees net immigration with native- and foreign-born emigration assumptions to derive gross flows; Appendix B §§B.1.2–B.1.4 pp. 100–101 schedules entry and exit from a life synthesized at birth. | A person's whole pre-entry life exists before the immigration event. | Whole-life synthesis avoids missing histories, but is not portable to a roster that materializes a person at entry. The needed analogue is an explicit entry-state packet. | +| PENSIM | Holmer, Janney, and Cohen, *[PENSIM Overview](https://www.retirementplanblog.com/wp-content/uploads/sites/304/2006/10/overview.pdf)* (Policy Simulation Group for the U.S. Department of Labor, Employee Benefits Security Administration, Sept. 2006), §2.1.6 p. 8, combines SSASIM/Trustees net immigration with native- and foreign-born emigration assumptions to derive gross flows; Appendix B §§B.1.2–B.1.4 pp. 100–101 schedules entry and exit from a life synthesized at birth. | A person's whole pre-entry life exists before the immigration event. | Whole-life synthesis avoids missing histories, but is not portable to a roster that materializes a person at entry. The needed analogue is an explicit entry-state packet. | | PENSIM2 | O'Donoghue, Redway, and Lennon, *[Simulating migration in the Pensim2 dynamic microsimulation model](https://www.microsimulation.pub/articles/00039)* (2010), §5.1 and Figure 3, disaggregates ONS net controls into gross immigration and emigration. | §3 discusses synthetic generation versus cloning and Table 2 inventories model components; §5.2 samples immigrant **families** from the 2003 Labour Force Survey and calibrates person totals. | Preserve joint family state and distinguish the control unit from the donor/simulation unit. Net-only migration can bias population structure (§3 and §4). | MINT is the closest architectural analogue. Earlier MINT versions cloned a @@ -523,7 +523,7 @@ weights; it does not create 1.34 million physical rows in 2026. For each year: in the floor ceremony, not by the external population count; - unit sampling preserves all members selected together; - person weights are finite and positive; -- the sum of person weights equals `G_resident[y]` within a pinned numerical +- the sum of person weights equals `G_resident_entry_proxy[y]` within a pinned numerical tolerance; - age/sex and other composition margins come from the frozen donor artifact, never from Table V.A2, which has no public age/sex detail; and @@ -954,13 +954,16 @@ until an acquisition PR records the actual bytes. | Binding ID | Exact source and vintage | Fields/transformation | Consumer and status | |---|---|---|---| -| `ssa_tr2026_v_a2_intermediate` | Social Security Administration, *[The 2026 Annual Report of the Board of Trustees of the Federal OASI and DI Trust Funds](https://www.ssa.gov/OACT/TR/2026/tr2026.pdf)*, §V.A.3, Table V.A2 “[Immigration Assumptions, Calendar Years 1940–2100](https://www.ssa.gov/oact/TR/2026/lr5a2.html),” assumptions set February 2026, report released June 2026. | Annual intermediate LPR inflow/outflow/status-adjustment/net; temporary-or-unlawfully-present inflow/outflow/status-adjustment/net; total net; thousands→persons; retain source rounding. Use exact annual rows 2026–2100. | Gross-entry control candidate and net reconciliation. Forward-assumption/report-only until universe bridge and exit design exist; prohibited as gate-estimation data. | +| `ssa_tr2026_v_a2_intermediate` | Social Security Administration, *[The 2026 Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds](https://www.ssa.gov/OACT/TR/2026/tr2026.pdf)*, §V.A.3, and Supplemental Single-Year Table V.A2, “[Immigration Assumptions, Calendar Years 1940–2100](https://www.ssa.gov/oact/TR/2026/lr5a2.html),” assumptions set Feb. 2026, report released June 9, 2026. | Annual intermediate LPR inflow/outflow/status-adjustment/net; temporary-or-unlawfully-present inflow/outflow/status-adjustment/net; total net; thousands→persons; retain source rounding. Use exact annual rows 2026–2100. The positive sum is an SSA stock-accounting inflow proxy; the temporary/unlawfully-present component counts year-end stayers, not all border arrivals. | Positive-inflow control candidate and net reconciliation. Forward-assumption/report-only until universe bridge and exit design exist; prohibited as gate-estimation data. | | `ssa_tr2026_v_a2_sensitivity` | Same report/table/vintage, low-cost and high-cost alternatives. | Same component schema; never substitute 75-year average or ultimate value for annual rows. | Report-only scenario sensitivity. | | `ssa_area_to_census_resident_bridge` | **UNBOUND.** Must reconcile the 2026 report's Social Security-area definition (glossary pp. 247–248) to the ACS/Census resident universe with an exact source and vintage. | Annual inclusion/exclusion or factor by population category; preserve an auditable raw-SSA series beside the bridged series. Identity is not an admissible silent default. | **BLOCKING** for a schedule labeled resident-population aligned. A raw `ssa_area_proxy` may run report-only. | -| `acs_pums_2010_2014_recent_arrivals` | Census Bureau, [2010–2014 ACS 5-year person PUMS `csv_pus.zip`](https://www2.census.gov/programs-surveys/acs/data/pums/2014/5-Year/csv_pus.zip); *[PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)*, Jan. 14, 2016; *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*. Observations 2010–2014. | Decode collection year from `SERIALNO`; bind `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `POBP`, education, marital/relationship, disability, employment and income/earnings fields plus allocation flags. Fit years 2010–2013; hold out 2014. | Primary donor estimation and proposed `gate_imm` truth, conditional on decision O6. | -| `cps_asec_2014_foreign_born` | Census Bureau, *[2014 Annual Social and Economic Supplement Technical Documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)* and [2014 ASEC data page](https://www.census.gov/data/datasets/time-series/demo/cps/cps-asec.2014.html). | `A-AGE`, `A-MARITL`, `A-SEX`, `A-HGA`, six disability items, `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT`, `WSAL-VAL`, `PEARNVAL`, `PTOTVAL`; bind Traditional **or** Redesign file and correction/repost status. | Report-only marginal triangulation. Exact file choice is decision O7; the two files may not be merged silently. | -| `sipp_2014_wave1_entry_state` | Census Bureau, *[2014 SIPP Metadata All Sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*, Sept. 12, 2017; [Wave 1 raw directory](https://www2.census.gov/programs-surveys/sipp/data/datasets/2014/w1/); *[SIPP 2014 Panel Source and Accuracy Statement, Wave 1](https://www2.census.gov/programs-surveys/sipp/tech-documentation/source-accuracy-statements/2014/sipp-2014-source-and-accuracy-statement.pdf)*. Interviews in 2014, reference year 2013. | `WPFINWGT`, marital state/history, age, `EBORNUS`, `ECITIZEN`, `ENATCIT`, grouped `TYRENTRY`, education, sex, disability and monthly earnings concepts. `TIMSTAT` is excluded from legal-status state. | Report-only joint-state/initializer diagnostics. No later-wave immigrant-only household coverage claim. | -| `census_np2023_nim_corridors` | Census Bureau, *[Methodology, Assumptions, and Inputs for the 2023 National Population Projections](https://www2.census.gov/programs-surveys/popproj/technical-documentation/methodology/methodstatement23.pdf)* (Nov. 2023), migration pp. 8–14; [Alternative Scenarios table page](https://www.census.gov/data/tables/2023/demo/popproj/2023-alternative-summary-tables.html), Table 1 “Projected Population and Components of Change, 2022–2100”; [main workbook](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1.xlsx) and sibling `-h`, `-l`, `-z` workbooks. | Annual net international migration in thousands for main/high/low/zero scenarios; July 1 prior year–June 30 current year. Preserve scenario definitions: alternatives change gross foreign-born immigration, not every migration component. | Report-only cross-model corridors; never gate truth or a gross entrant control. | +| `acs_pums_2010_2014_recent_arrivals` | Census Bureau, [2010–2014 ACS 5-year person PUMS `csv_pus.zip`](https://www2.census.gov/programs-surveys/acs/data/pums/2014/5-Year/csv_pus.zip); *[PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)*, Jan. 14, 2016; *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*; *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129. Observations 2010–2014. | Decode collection year from `SERIALNO`; bind `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, dual `YOEP05`/`YOEP12`, `NATIVITY`, dual place-of-birth classifications, `RELP`, education, disability, employment and income/earnings fields plus allocation flags. Fit 2010–2013; hold out 2014. Retain `reported_year_of_entry`, because responses may be first or most recent entry. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | +| `acs_stock_to_arrival_state_bridge` | **UNBOUND.** No cited ACS cross-section identifies state at the arrival instant or everyone who subsequently left/died. | Must pin a duration/backcast law, survivor/stayer selection adjustment, reported-entry ambiguity treatment, repeat-entry identification and source vintage. An identity mapping is labeled `stock_proxy` only. | **BLOCKING** for literal entry-time characteristics; decision O12. | +| `cps_asec_2014_foreign_born` | Census Bureau, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)*, *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*, and [2014 ASEC data page](https://www.census.gov/data/datasets/time-series/demo/cps/cps-asec.2014.html). Calendar-year 2013 income, 2014 interview characteristics. | `A-AGE`, `A-MARITL`, `A-SEX`, `A-HGA`, six disability items, `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT`, `WSAL-VAL`, `PEARNVAL`, `PTOTVAL`; civilian noninstitutional population plus Armed Forces members in civilian housing. Bind Traditional **or** Redesign bytes and correction/repost status. | Report-only marginal triangulation. Exact file choice is O7; the two designs may not be combined silently. | +| `sipp_2014_wave1_entry_state` | Census Bureau, *[2014 SIPP Metadata All Sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*, Sept. 12, 2017; [Wave 1 raw directory](https://www2.census.gov/programs-surveys/sipp/data/datasets/2014/w1/); *[SIPP 2014 Panel Source and Accuracy Statement, Wave 1](https://www2.census.gov/programs-surveys/sipp/tech-documentation/source-accuracy-statements/2014/sipp-2014-source-and-accuracy-statement.pdf)*. Interviews in 2014, reference year 2013. The directory is discovery evidence, not an immutable file binding; exact public-use filename/version and correction status are **UNBOUND** pending O8. | Candidate concepts: `WPFINWGT`, marital state/history, age, `EBORNUS`, `ECITIZEN`, `ENATCIT`, grouped `TYRENTRY`, education, sex, disability and monthly earnings. `TIMSTAT` is excluded from legal-status state. | Report-only joint-state/initializer diagnostics after exact bytes are bound. No later-wave newly arrived immigrant-only household coverage claim. | +| `entrant_fertility_history_bridge` | **UNBOUND.** Candidate evidence must name exact SIPP fertility-history or CPS fertility-supplement files, variables, universe, observation years and release vintage. | Map prior parity/birth history and exposure start jointly with entrant family state; never default parity to zero. | **BLOCKING** for entrant fertility risk; decision O13. | +| `prior_us_covered_earnings_bridge` | **UNBOUND.** ACS reported year of entry and public survey earnings do not establish first entry or prior U.S. Social Security covered earnings. | Identify repeat-entry/first-entry status, covered quarters and prior indexed earnings with a source, universe and vintage; otherwise retain censored/unknown. | **BLOCKING** for entrant insured status, claiming, AIME/PIA and benefits; decision O12. | +| `census_np2023_nim_corridors` | Census Bureau, *[Methodology, Assumptions, and Inputs for the 2023 National Population Projections](https://www2.census.gov/programs-surveys/popproj/technical-documentation/methodology/methodstatement23.pdf)* (Nov. 2023), migration pp. 8–14; Alternative Scenarios Table 1, “Projected Population and Components of Change, 2022–2100”: [main](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1.xlsx), [high](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-h.xlsx), [low](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-l.xlsx), and [zero](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-z.xlsx) workbooks. | Annual net international migration in thousands for main/high/low/zero scenarios; July 1 prior year–June 30 current year. Preserve scenario definitions: alternatives change gross foreign-born immigration, not every migration component. | Report-only cross-model corridors; never gate truth or a positive entrant control. | | `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: realized SSA NAWI through 2014 and `I_proj` beyond, estimated only from `<=T*`; see `m6_projection_engine.md:666-708,1723-1756`. | ACS `ADJINC` first expresses pooled income in 2014 dollars; any projection-year entrant earnings use the already pinned `I_proj`, never realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | | `emigration_duration_hazard` | **UNBOUND.** Table V.A2 supplies aggregate outflow counts only. The Duleep-Dowhan 2008 hazards and legacy model methods are research evidence, not a current operational binding. | Must identify age, sex, source grouping, time since entry, family/individual unit, re-entry treatment, universe and vintage. | **BLOCKING** for explicit exits and any Trustees net-alignment claim; outside entry-builder v1. | @@ -979,10 +982,11 @@ within the source's thousand-person rounding. It must not treat status adjustmen as two events or as a new arrival. The ACS extractor must assert each collection year from `SERIALNO`, apply the -correct dual-year-of-entry variable for that collection vintage, use person and -replicate weights, and publish allocation/top-code/group-quarters counts. It must -keep the survey's latest-entry meaning in field names; `first_entry_year` is -prohibited without another source. +correct dual-year-of-entry and place-of-birth classifications for that collection +vintage, use person and replicate weights, and publish allocation/top-code/group- +quarters counts. It must use `reported_year_of_entry`: the intended interviewer +concept is most recent entry, while unclarified/self responses may mean first or +most recent entry. `first_entry_year` is prohibited without another source. The Census parser must preserve its July-to-June event year and resident- population universe. A calendar-year bridge to Trustees may be displayed only as @@ -993,35 +997,38 @@ be rewritten to zero net international migration. Nothing in this list is silently resolved by the provisional recommendation. -### O1. Literal gross entrants, exit scope, and the universe bridge — hardest +### O1. Positive SSA inflow, exit scope, and net proxy — hardest Choose among: -- **recommended**: gross new-person entrants through the seam, entry-only v1 - explicitly report-only, followed by a separate emigration design before any net - alignment claim; +- **recommended**: use the two positive SSA stock-accounting inflow components as + an entry-control proxy through the seam, keep entry-only v1 report-only, and + require a separate emigration design before any net-alignment claim; - widen this design to include an audited exit law before implementing entries; or - authorize a named reduced-form `net_entry_proxy` experiment, accepting that it is not a literal immigrant cohort and cannot enter entrant/family/benefit gates. -Also select or commission the Social Security-area→resident bridge. Raw identity -is not presumed. +The temporary/unlawfully-present component counts people remaining through year +end, so none of these options may relabel the 1.340 million 2026 sum as every +physical border arrival. The population-universe bridge is a separate O11. ### O2. Entry-year timing, age, and mortality exposure The seam inserts the prior-year-coordinate row before mortality and aging. -Decide whether the external calendar-year inflow represents opening-of-period, -midperiod, or end-of-period entry; what `age` means on the scheduled frame and -the target slice; and whether first-period mortality exposure is full, fractional, -or deferred. The choice must preserve the seam and publish an exposure audit. +Choose either (a) the feasible unchanged-engine convention—full mortality at the +scheduled age followed by `age += 1`—or (b) an explicitly scoped entrant-aware +wrapper in the mortality/aging slots for fractional or deferred exposure. Also +bind whether the external calendar-year inflow is opening-, mid-, or end-period +and what age means on each side. The builder may not simulate a timing choice with +age `-1` or a hidden donor-age shift. ### O3. Recent-arrival window and matching ladder -Ratify the proposed 0–4-year latest-entry window or a different duration; decide -whether duration-zero/one donors receive priority; freeze age/source/education/ -family matching cells and their fallback order; and decide how return entrants -are labeled without inferring unobserved prior U.S. coverage. +Ratify the proposed 0–4-year **reported-entry** window or a different duration; +decide whether duration-zero/one donors receive priority; and freeze age/source/ +education/family matching cells and their fallback order. Repeat-entry +identification and prior U.S. coverage belong to O12. ### O4. Person versus co-arrival-family units and weights — hardest @@ -1040,10 +1047,14 @@ jointly matched SIPP donor, and which requires a new model. In particular: - the ACS/SIPP disability-concept bridge; - entry employment, partial-year earnings, lags and persistent earnings state; - the entire entrant earnings law, since §2.8.3a membership cannot expand; +- fertility-history and claiming/insured-status exclusion masks; - cross-domain marriage/household interactions with existing people; and - the certification boundary for ordinary cores applied to entrant inputs. The default is no independent marginal hot-decks and no certificate transfer. +Subparts may be ratified independently, but an entrant must remain out of every +unresolved module domain; a structurally complete packet is not substantive +validation. ### O6. Observation date versus publication date at `T*` @@ -1059,19 +1070,60 @@ Choose Traditional or Redesign 2014 ASEC public-use data and bind its correction history. This affects report-only triangulation, not candidate fitting or gate truth. -### O8. Current-vintage production refits +### O8. Exact SIPP Wave 1 file and correction vintage + +Choose and hash one exact 2014 SIPP Wave 1 public-use filename/version from the +mutable Census directory, record its correction/repost history, and bind the +metadata version to those bytes. Directory identity alone is not a binding. + +### O9. Current-vintage production refits Decide whether a later ACS donor refit (for example 2015–2019 or 2020–2024) requires a new holdout/lock ceremony or may inherit a procedure-level certificate. The conservative default is that the exact-artifact certificate does not transfer and the refit remains report-only. -### O9. Physical cohort size and calibration constraints +### O10. Physical cohort size and calibration constraints -Let the floor ceremony determine annual physical unit counts, weight caps, -calibration margins, and maximum fallback share. No arbitrary “one row per N +Freeze annual physical unit counts, weight caps, calibration margins and maximum +fallback share through training-only power analysis **before** truth floors are +constructed. The floor may prune an infeasible surface, but it may not +candidate-adaptively choose the sample design. No arbitrary “one row per N people” constant is adopted here. +### O11. Social Security-area to Census-resident universe bridge + +Select or commission a vintage-pinned transformation from each relevant Social +Security-area population category to the ACS/Census resident universe. Choose +the time basis and treatment of territories and covered people abroad. Identity +is not presumed; without this bridge only an `ssa_area_proxy` schedule is +permitted and every population output remains report-only. + +### O12. Stock-to-arrival state, repeat entry, and prior U.S. coverage + +Choose a vintage-pinned law that maps the ACS interview-date survivor/stayer +stock to arrival-time state, including duration change, selection from pre- +interview death/emigration, and ambiguity between first and most recent entry. +Also choose whether first/return entry can be identified and how prior U.S. +covered quarters and earnings are sourced. Until then the identity initializer +is labeled `stock_proxy`, prior coverage is censored, and claiming/benefit +outputs are suppressed. + +### O13. Fertility history and entrant exposure + +Bind an exact parity/birth-history source and concept bridge, decide exposure +start, and authorize an entrant-aware fertility kernel. Until then no parity-zero +default is allowed and entrants remain outside fertility risk IDs; later maternal +births still obey the exact 3h live-mother materialization guard. + +### O14. RNG-isolated composite and cross-domain markets + +Choose the composite adapter that preserves the original closed support, order, +generators and outputs while giving entrant transitions disjoint named RNG +addresses. Decide whether entrant/existing-person marriage and household markets +remain a separate report-only product. No byte-identity claim is admissible from +stable person ordinals alone. + ## 8. What this design does not change This document and its eventual entrant-side implementation must leave these From 2f577d2e3838979f300b40459b36cfc84474a57c Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 17:56:27 -0400 Subject: [PATCH 07/18] Finalize certification order and binding manifest Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 138 ++++++++++++++++++++++-------- 1 file changed, 101 insertions(+), 37 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 8333056f..a572e51a 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -67,10 +67,10 @@ referee: The fourth choice is intentionally costly but honest. Substituting total net change for a positive entrant control would create a reduced-form residual cohort whose age, family, earnings, and nativity composition has no literal interpretation. In -2026, it would also replace 1.340 million gross arrivals with 0.130 million -residual persons. The 1.340 million itself is an SSA stock-accounting inflow, -not all physical arrivals during the year. That alternative remains an explicit referee decision, not a -silent implementation shortcut. +2026, it would also replace a 1.340 million positive stock-accounting inflow proxy +with 0.130 million residual persons. The 1.340 million itself is not all physical +arrivals during the year. That alternative remains an explicit referee decision, +not a silent implementation shortcut. ## 1. Scope and non-goals @@ -1141,8 +1141,9 @@ authorizes surgery: - the §2.8.2g marital risk-set guard and seed-at-domain-entry law; - amendment 3h's schedule-versus-live-roster materialization distinction and absent-parent guard; -- `SCHEDULED_ENTRIES_KEY`, its frame/year/ID contract, and the existing 2017/2019 - PSID opener schedule; +- `SCHEDULED_ENTRIES_KEY`, its frame/year/ID contract, and every existing + 2017/2019 PSID opener row; the immigration builder merges that mapping and never + overwrites it; - the eight-member `PeriodModules` order, existing module RNG streams, original- person ordinals, synthetic-ID allocator semantics, and period trace; - M6's current statement that immigrant/open-panel additions are report-only; @@ -1153,21 +1154,27 @@ authorizes surgery: An entrant adapter may call unchanged core code, but it must do so under an entrant-domain label and separate report/gate surface. It may not alter the closed-panel input or score and call the resulting difference “immigration.” +The metadata adapter also must omit a caller allocator or enforce the combined- +maximum guard in §4.6. Any mixed entrant/existing-person market remains the +report-only O14 product and makes no closed-run byte-identity claim. ## 9. Candidate-blind implementation and certification order A later implementation should proceed in this order: -1. Referee resolves O1–O6 and ratifies the external-binding schema. +1. Referee resolves O1–O14 for the chosen implementation slice and ratifies the + external-binding schema. 2. Acquisition PR commits/hash-binds exact source bytes and parsers; the zero- argument binding factory passes independently of any candidate. -3. Donor-build PR constructs only training artifacts and synthetic fixtures; +3. Donor/bridge PR constructs only training artifacts, the separately identified + arrival-state/fertility/prior-coverage bridges, and synthetic fixtures; holdout outcomes remain sealed. -4. Floors PR freezes the surface, creates truth-vs-truth floors, prunes unsupported +4. Floors PR freezes the physical sample design and seed-grid aggregation, + creates truth-vs-truth and pipeline-variability floors, prunes unsupported cells, and runs the operating-characteristic pause check. -5. Schedule/state PR implements the deterministic builder, seam adapter, complete - state packet, failure guards, and report-only open-population run without - changing the M6 closed-panel score. +5. Schedule/state PR implements the deterministic builder, seam adapter, + structurally complete state packet, failure guards, and report-only open- + population run without changing the M6 closed-panel score. 6. A registered `gate_imm` candidate is scored once against the locked surface. 7. If PASS is verified and ratified, the lock names exact source, derived, floor, code and schedule-protocol hashes. @@ -1177,6 +1184,12 @@ A later implementation should proceed in this order: No stage reads a later stage's candidate outcomes to redesign an earlier frozen surface. +A literal resident-entry schedule pauses while O11 and O12 remain unbound; +entrant fertility and claiming/benefit outputs pause while O13 and the prior- +coverage portion of O12 remain unbound. A `stock_proxy` diagnostic schedule may +exercise seam structure only in a report-only run with those module domains +excluded. + ## 10. Referee citation ledger - **DYNASIM4**: Cosic, Johnson, and Smith, *Urban's Dynamic Simulation of Income @@ -1189,19 +1202,24 @@ surface. Institute, December 2010), ch. II §VI, pp. II-24–II-28, Tables 2-14–2-16; Smith and Favreault, *Modeling Income in the Near Term 8 and 2014: Primer* (Urban Institute, April 2019), pp. 15–16, note 21 p. 29, Table 3 pp. 39–40. -- **PENSIM/PENSIM2**: Holmer, Janney, and Cohen, *PENSIM Overview* (2006), - §2.1.6 p. 8, Appendix B §§B.1.2–B.1.4 pp. 100–101 and §§B.7–B.8 pp. 106–107; +- **PENSIM/PENSIM2**: Holmer, Janney, and Cohen, *PENSIM Overview* (Policy + Simulation Group for the U.S. Department of Labor, Employee Benefits Security + Administration, September 2006), §2.1.6 p. 8, Appendix B §§B.1.2–B.1.4 + pp. 100–101 and §§B.7–B.8 pp. 106–107; O'Donoghue, Redway, and Lennon, “Simulating migration in the Pensim2 dynamic microsimulation model,” *International Journal of Microsimulation* 3(2), 2010, Table 2, §§5.1–5.2. - **SSA methods/current controls**: Duleep and Dowhan, “Adding Immigrants to Microsimulation Models” and “Incorporating Immigrant Flows into - Microsimulation Models,” *Social Security Bulletin* 68(1), 2008; *2026 OASDI - Trustees Report*, §V.A.3 and Table V.A2. -- **Microdata**: Census 2010–2014 ACS 5-year PUMS dictionary/accuracy statement; - Census 2014 ASEC technical documentation; Census 2014 SIPP Wave 1 metadata and - source/accuracy statement. Exact variables and pages are pinned in §2.2 and - §6.2. + Microsimulation Models,” *Social Security Bulletin* 68(1), 2008; *The 2026 + Annual Report of the Board of Trustees of the Federal Old-Age and Survivors + Insurance and Federal Disability Insurance Trust Funds*, §V.A.3, and + Supplemental Single-Year Table V.A2. +- **Microdata**: Census 2010–2014 ACS 5-year PUMS dictionary, accuracy statement, + and 2014 ACS Subject Definitions “Year of Entry,” pp. 128–129; Census 2014 + Traditional and Redesigned ASEC technical documentation; Census 2014 SIPP + Wave 1 metadata and source/accuracy statement. The exact SIPP raw file remains + unbound at O8. Exact variables and pages are pinned in §2.2 and §6.2. - **Projection corridors**: Census, *Methodology, Assumptions, and Inputs for the 2023 National Population Projections* (November 2023), migration pp. 8–14, and Alternative Scenarios Table 1. @@ -1211,7 +1229,7 @@ surface. ```json immigration-design-parameters { "design_id": "2026-07-15-immigration-module", - "revision": 1, + "revision": 2, "status": "design_draft_referee_pending", "engine_baseline": "75d30dd57d71b91ee0929246b2f3cbb92263b350", "roadmap_issue": 113, @@ -1230,13 +1248,19 @@ surface. "activation": "top of period before mortality", "new_period_module": false, "ids_preassigned": true, - "synthetic_allocator_start": "max(initial and all scheduled person_id) + 1" + "synthetic_allocator_start": "engine default is max(initial and all scheduled person_id) + 1 when caller metadata omits the allocator", + "existing_schedule_merge": "preserve and concatenate every PSID opener frame; allocate immigrants above max(initial plus all pre-existing scheduled ids)", + "caller_allocator_guard": "omit caller allocator or assert next_id exceeds the combined maximum" }, "provisional_adjudications": { - "cohort_control": "gross new-person inflow after an explicit Social-Security-area-to-resident bridge", + "cohort_control": "positive SSA stock-accounting inflow proxy after an explicit Social-Security-area-to-Census-resident bridge", "status_adjustment": "aggregate reclassification; not an entrant and not assigned to persons", "emigration": "outside entry-builder v1; mandatory successor before net-alignment claim", - "assignment": "recent-arrival ACS joint donor units plus model-based calibration; no cloned future", + "assignment": "recent-arrival ACS joint resident-stock donor units plus model-based calibration; literal arrival state requires a separate bound bridge; no cloned future", + "prior_us_covered_earnings": "unknown/censored absent a first-or-return-entry and coverage bridge; never default zero", + "entrant_fertility": "excluded from fertility risk absent a bound parity/history bridge and entrant-aware kernel", + "entrant_claiming": "excluded absent insured-status and prior-coverage evidence", + "rng_isolation": "required composite partition before any closed-person byte-identity claim", "runtime": "schedule built once per scenario and reused across K engine draws", "legal_status_dynamics": "out of scope", "current_entry_only_outputs": "report_only" @@ -1244,14 +1268,14 @@ surface. "external_bindings": [ { "id": "ssa_tr2026_v_a2_intermediate", - "source": "2026 OASDI Trustees Report, section V.A.3, Table V.A2", - "vintage": "assumptions set February 2026; report released June 2026", - "role": "gross-entry control candidate and net reconciliation", + "source": "The 2026 Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds, section V.A.3, and Supplemental Single-Year Table V.A2", + "vintage": "assumptions set February 2026; report released June 9, 2026", + "role": "positive stock-accounting inflow control candidate and net reconciliation", "status": "report_only_until_universe_bridge_and_exit_law" }, { "id": "ssa_tr2026_v_a2_sensitivity", - "source": "2026 OASDI Trustees Report, Table V.A2 low-cost/high-cost", + "source": "2026 Trustees Supplemental Single-Year Table V.A2 low-cost/high-cost", "vintage": "2026", "role": "scenario sensitivity", "status": "report_only" @@ -1265,10 +1289,17 @@ surface. }, { "id": "acs_pums_2010_2014_recent_arrivals", - "source": "Census 2010-2014 ACS 5-year PUMS person file, dictionary, and accuracy statement", + "source": "Census 2010-2014 ACS 5-year PUMS person file, dictionary, accuracy statement, and 2014 Subject Definitions", "vintage": "observations 2010-2014; published January 2016", - "role": "fit 2010-2013; hold out 2014", - "status": "proposed_gate_binding_pending_O6" + "role": "resident survivor/stayer stock donor; fit 2010-2013 and hold out 2014", + "status": "proposed_gate_binding_pending_O6_not_arrival_truth" + }, + { + "id": "acs_stock_to_arrival_state_bridge", + "source": "unbound", + "vintage": "unbound", + "role": "map interview-date stock proxy to literal arrival state, including duration, selection, reported-entry ambiguity, and repeat entry", + "status": "blocking_for_literal_entry_state_pending_O12" }, { "id": "cps_asec_2014_foreign_born", @@ -1279,10 +1310,24 @@ surface. }, { "id": "sipp_2014_wave1_entry_state", - "source": "Census 2014 SIPP Wave 1 public-use file, metadata v2, and source/accuracy statement", + "source": "Census 2014 SIPP Wave 1 metadata v2, source/accuracy statement, and mutable raw-file directory; exact public-use file unbound", "vintage": "2013 reference year; 2014 interviews", "role": "joint-state and initializer diagnostics", - "status": "report_only" + "status": "report_only_pending_exact_file_and_correction_vintage_O8" + }, + { + "id": "entrant_fertility_history_bridge", + "source": "unbound exact SIPP fertility-history or CPS fertility-supplement file", + "vintage": "unbound", + "role": "parity, prior-birth history, and entrant fertility exposure start", + "status": "blocking_for_entrant_fertility_pending_O13" + }, + { + "id": "prior_us_covered_earnings_bridge", + "source": "unbound", + "vintage": "unbound", + "role": "first-versus-repeat entry, covered quarters, and prior indexed U.S. earnings", + "status": "blocking_for_claiming_aime_pia_and_benefits_pending_O12" }, { "id": "census_np2023_nim_corridors", @@ -1312,14 +1357,17 @@ surface. "fit_collection_years": [2010, 2011, 2012, 2013], "holdout_collection_years": [2014], "count_alignment_gated": false, + "physical_sample_design_frozen_from_training_power_analysis": true, + "schedule_seed_grid_and_aggregation_frozen_before_truth_floor": true, "floors_before_thresholds": true, "operating_characteristic_before_lock": true, + "packet_certification": "structural_schema_only", "downstream_life_course_certified": false }, "hardest_open_decisions": [ - "O1: gross entrants plus separate exits versus entry-only report-only v1 or a named net-entry proxy, including the SSA-area-to-resident bridge", - "O4: person versus co-arrival-family simulation units, relationship closure, and common versus person weights", - "O5: atomic downstream state/history packet and entrant-specific post-entry earnings, disability, marital, and household laws" + "O1: positive SSA stock-accounting inflow proxy plus separate exits versus an expanded entry-and-exit design or named net-entry proxy", + "O5/O12/O13: atomic downstream packet, stock-to-arrival and repeat-coverage bridges, and fertility/claiming exclusions", + "O4/O14: person versus co-arrival-family units, relationship and weight closure, and RNG-isolated cross-domain markets" ], "certified_surfaces_untouched": [ "gate_m6 registry, thresholds, floors, hashes, and closed-panel support", @@ -1330,7 +1378,8 @@ surface. "section 2.8.2g marital domain law", "amendment 3h live-roster materialization law", "PeriodModules order and ProjectionRNGRegistry", - "SCHEDULED_ENTRIES_KEY contract and existing PSID openers", + "SCHEDULED_ENTRIES_KEY contract and every existing PSID opener row", + "original closed-support generator order, RNG consumption, and outputs", "M7 trust-fund accounting and M8 rules execution" ], "amendment_history": [ @@ -1345,6 +1394,21 @@ surface. "define the EntrantStateBundle and no-certificate-transfer boundary", "propose floors-first gate_imm and enumerate external bindings and open referee decisions" ] + }, + { + "revision": 2, + "date": "2026-07-15", + "kind": "pre_pr_adversarial_hardening", + "changes": [ + "distinguish SSA positive stock-accounting inflows from all physical arrivals and separate the population-universe bridge", + "label ACS recent arrivals as a survivor/stayer stock proxy and make stock-to-arrival state an unbound bridge", + "treat possible prior U.S. covered earnings as censored and block unsupported claiming and benefit outputs", + "block entrant fertility until parity history and an entrant-aware kernel are bound", + "merge rather than overwrite existing PSID scheduled entries and guard caller-supplied synthetic allocators", + "require physical-sample and schedule-seed protocols before floors and limit packet PASS to structural/schema completeness", + "require RNG-isolated composite adapters before any original-person byte-identity claim", + "expand referee decisions through O14 and pin unresolved external bindings" + ] } ] } From 729e5351598163ae9c87bd428211aa46ecb4503d Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 18:03:08 -0400 Subject: [PATCH 08/18] Update merged domain law and run-specific guards Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index a572e51a..7829dc64 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -185,7 +185,7 @@ emigration cannot be ignored. | Source | Exact public support | V1 role | Binding limitation | |---|---|---|---| -| ACS PUMS | Census, *[2010–2014 ACS 5-year PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* (Jan. 14, 2016): `SERIALNO`, `PWGTP`, `AGEP`, `CIT`, disability items, `MAR`, `RELP`, `SCHL`, `SEX`, `WAGP`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `PINCP`, and dual place-of-birth fields; the *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*, §3 pp. 5–7 and §4 p. 8, defines the pooled sample and dual-variable rule. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents the response concept and ambiguity. | Primary joint-stock donor and gate truth, weighted by `PWGTP` with replicate-weight uncertainty. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The 2016 publication date versus `T*=2014` is decision O6. | +| ACS PUMS | Census, *[2010–2014 ACS 5-year PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* (Jan. 14, 2016): `SERIALNO`, `PWGTP`, `AGEP`, `CIT`, disability items, `MAR`, `RELP`, `SCHL`, `SEX`, `WAGP`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `PINCP`, and dual place-of-birth fields; the *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*, §3 pp. 5–7 and §4 p. 8, defines the pooled sample and dual-variable rule. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents the response concept and ambiguity. | Primary joint-stock donor and gate truth only for the named stock-proxy surface, weighted by `PWGTP` with replicate-weight uncertainty. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The 2016 publication date versus `T*=2014` is decision O6. | | CPS ASEC | Census, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)* or *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: the cited Redesigned layout has demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian noninstitutional universe plus Armed Forces members living in civilian housing; grouped entry years; survey-date demographics versus prior-calendar-year income. Traditional and Redesign files must never be silently combined. | | SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves miss newly arrived immigrant-only households. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | @@ -348,13 +348,16 @@ strictly above the combined maximum before period 1; otherwise the loop does not protect births from collision. No existing M6 module stream is consumed to construct the schedule. -### 3.3 Amendment 3h: live-roster materialization +### 3.3 Amendment 3h / M6 §2.8.2h: live-roster materialization -Amendment 3h is not merged at the baseline commit. Its public source is the +Amendment 3h is absent from the pinned engine baseline. It subsequently merged +to master as +[PR #216](https://github.com/PolicyEngine/populace-dynamics/pull/216), commit +`0e27be2d857719b30e33b556580b4a360808b5e0`, after this branch point. Its public +forensic source is the [3h forensics/adjudication](https://github.com/PolicyEngine/populace-dynamics/issues/42#issuecomment-4984997277) -and draft [PR #216](https://github.com/PolicyEngine/populace-dynamics/pull/216). -This sibling design adopts its domain law as a dependency while accurately -describing its pending merge status: +and the merged M6 §2.8.2h text. This sibling design adopts that law as a +dependency while retaining the stated baseline for every code pin: > A scheduled maternal birth may materialize a child only when the mother is > present in the live post-mortality roster. The frame-independent risk schedule @@ -519,8 +522,8 @@ and label the result resident-population aligned. The schedule uses a manageable synthetic sample and positive calibration weights; it does not create 1.34 million physical rows in 2026. For each year: -- the number of donor units is set by support/precision requirements established - in the floor ceremony, not by the external population count; +- the number of donor units is frozen from training-only support/power analysis + before the truth floor, not by the external population count or candidate; - unit sampling preserves all members selected together; - person weights are finite and positive; - the sum of person weights equals `G_resident_entry_proxy[y]` within a pinned numerical @@ -770,12 +773,12 @@ totals, donor-cell effective sample sizes, fallback counts, calibration residual top-code/allocation shares, unit-size distribution, state-bundle completeness, and all report-only/certified labels. -The builder refuses to run when a binding is missing or mutable, a raw or derived -hash differs, a required year is absent, a unit crosses an unsupported concept, -an outside-roster relation is assigned an ID, an entry is accidentally admitted -to the certified earnings domain, or the universe bridge is absent for a run -claiming resident alignment. Network access and runtime redownload are prohibited -on a scored or production run. +The builder refuses to run when a binding required by the selected run is missing +or mutable, a raw or derived hash differs, a required year is absent, a unit +crosses an unsupported concept, an outside-roster relation is assigned an ID, an +entry is accidentally admitted to the certified earnings domain, or the universe +bridge is absent for a run claiming resident alignment. Network access and runtime +redownload are prohibited on a scored or production run. ## 5. Evaluation and proposed `gate_imm` From 8dafc3d6db6ea35d971101f4947af7d349fefc76 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 18:08:01 -0400 Subject: [PATCH 09/18] Replace pooled ACS gate with annual holdout files Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 89 ++++++++++++++++++------------- 1 file changed, 52 insertions(+), 37 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 7829dc64..3588f925 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -185,7 +185,7 @@ emigration cannot be ignored. | Source | Exact public support | V1 role | Binding limitation | |---|---|---|---| -| ACS PUMS | Census, *[2010–2014 ACS 5-year PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* (Jan. 14, 2016): `SERIALNO`, `PWGTP`, `AGEP`, `CIT`, disability items, `MAR`, `RELP`, `SCHL`, `SEX`, `WAGP`, dual `YOEP05`/`YOEP12`, `NATIVITY`, `PINCP`, and dual place-of-birth fields; the *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*, §3 pp. 5–7 and §4 p. 8, defines the pooled sample and dual-variable rule. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents the response concept and ambiguity. | Primary joint-stock donor and gate truth only for the named stock-proxy surface, weighted by `PWGTP` with replicate-weight uncertainty. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The 2016 publication date versus `T*=2014` is decision O6. | +| ACS PUMS | Census annual 1-year person PUMS files for [2010](https://www2.census.gov/programs-surveys/acs/data/pums/2010/1-Year/csv_pus.zip), [2011](https://www2.census.gov/programs-surveys/acs/data/pums/2011/1-Year/csv_pus.zip), [2012](https://www2.census.gov/programs-surveys/acs/data/pums/2012/1-Year/csv_pus.zip), [2013](https://www2.census.gov/programs-surveys/acs/data/pums/2013/1-Year/csv_pus.zip), and [2014](https://www2.census.gov/programs-surveys/acs/data/pums/2014/1-Year/csv_pus.zip); annual dictionaries [2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict10.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict11.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict12.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict13.pdf), and [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict14.pdf); and corresponding annual Accuracy statements ([2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010AccuracyPUMS.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2011AccuracyPUMS.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2012AccuracyPUMS.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2013AccuracyPUMS.pdf), [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2014AccuracyPUMS.pdf)). The *[2010–2014 PUMS dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* is crosswalk evidence only. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents response ambiguity. | Primary joint-stock donor and gate truth only for the named stock-proxy surface. Fit 2010–2013 with each annual file's `PWGTP` and replicate weights; hold the separately weighted 2014 file out in full. Bind annual `YOEP`, `POBP`, `AGEP`, `SEX`, `RELP`, education, disability, employment and earnings concepts. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The gate never uses 5-year pooled weights, which are reraked to a five-year population. Current 2010/2011 bytes are the corrected Mar. 4, 2013 re-releases in [ACS erratum 87](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/087.html); observation versus release date remains O6. | | CPS ASEC | Census, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)* or *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: the cited Redesigned layout has demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian noninstitutional universe plus Armed Forces members living in civilian housing; grouped entry years; survey-date demographics versus prior-calendar-year income. Traditional and Redesign files must never be silently combined. | | SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves miss newly arrived immigrant-only households. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | @@ -196,9 +196,10 @@ foreign_born == true and 0 <= survey_year - reported_year_of_entry <= recent_arrival_max_duration ``` -`survey_year` is decoded from `SERIALNO`; the correct `YOEP05`/`YOEP12` -classification is selected by collection year. The initial proposal is a 0–4 -year window, but the exact duration and fallback hierarchy remain decision O3. +`survey_year` is fixed by the annual-file manifest and cross-checked against +`SERIALNO`; annual `YOEP` supplies the reported year. The initial proposal is +a 0–4 year window, but the exact duration, annual-pooling rule, and fallback +hierarchy remain decision O3. The extractor must bind allocation-flag treatment, top/bottom-code treatment, group-quarters policy, dual classifications, replicate weights, and the use of `ADJINC` before any artifact can be certified. @@ -800,28 +801,31 @@ died before interview, legal status, or post-entry trajectories. ### 5.2 Temporal split and leakage fence -The primary proposed split uses collection-year information inside the -2010–2014 ACS 5-year PUMS: +The primary proposed split uses five separately released annual ACS 1-year PUMS +files: -- fit donor construction and all matching/calibration choices on collection - years 2010–2013, recovered from `SERIALNO`; +- fit donor construction and all matching/calibration choices on the 2010–2013 + annual files using each year's own person and replicate weights, with the + cross-year pooling/normalization rule frozen from training only; - freeze the candidate artifact and surface; - generate a synthetic 2014 recent-arrival resident cross-section without - reading 2014 person records; and -- score against collection year 2014 using the same recent-arrival predicate, - concept map, universe, and weight treatment. + reading any 2014 person record, weight, or marginal; and +- score against the separately weighted annual 2014 file using the same recent- + arrival predicate, concept map, universe, and annual-weight treatment. Households/arrival units are indivisible. The truth and candidate normalize to the same total before characteristic scoring; the total itself is not a gate cell. No 2014 characteristic, marginal, top-code treatment selected after seeing the holdout, CPS/SIPP statistic, current Trustees assumption, or Census projection -may affect the fit. +may affect the fit. The 2010–2014 5-year PUMS is prohibited from both fitting and +truth: its five-year weights represent/rerake to the pooled period, so slicing it +by survey year would neither recover annual truth nor preserve the leakage fence. -The 2010–2014 pooled file was published in January 2016. Decision O6 must ratify -the observation-date rule (all person observations are `<=T*`) or reject the file -under a publication-date rule. Rejection pauses the gate; it does not silently -move the boundary. A fallback using individually pinned one-year files published -by 2014 requires a new design amendment and floor. +The annual files are observations at or before `T*`, but at least the 2014 file +was released after its observation year. Decision O6 must ratify an observation- +date rule analogous to the M6 NAWI publication-lag reasoning or reject every +post-boundary release. Rejection pauses the gate; it does not silently move the +boundary or fall back to the pooled file. Later ACS windows, including 2015–2019 and 2020–2024, are temporal-drift stress tests only under this gate. Refitting on them creates a new production artifact @@ -867,18 +871,24 @@ The floor ceremony may consider these predeclared families: | Family | Candidate observables | Candidate metric | |---|---|---| -| Demographic | broad age-at-entry × sex shares; arrival-duration band; broad source region | total-variation or weighted absolute-share distance | +| Demographic | broad derived reported-entry-age proxy × sex shares; reported-entry-duration proxy; broad source region | total-variation or weighted absolute-share distance | | Education | attainment band overall and by broad age/sex | total-variation distance | -| Family state | marital-state shares; co-arrival unit size; spouse/child co-arrival indicators | total-variation distance, unit-weighted where applicable | +| Family state | marital-state shares; constructed co-resident same-reported-entry unit size; spouse/child same-reported-entry co-residence indicators | total-variation distance, unit-weighted where applicable | | Employment | employed/unemployed/NILF; zero earnings; work-intensity bands | absolute-share or total-variation distance | | Positive earnings | `WAGP`/earnings normalized under the pinned economic index, p10/p50/p90 and log spread | floor-scaled log-quantile distance | | Disability proxy | the six ACS question concepts individually and “any” | absolute-share distance; never named DI status | -| Named joints | age × sex × education; sex × marital state × duration; education × employment/earnings band | pooled-cell total-variation distance | +| Named joints | derived reported-entry-age proxy × sex × education; sex × marital state × reported-entry-duration proxy; education × employment/earnings band | pooled-cell total-variation distance | The final registry contains only cells that clear the floors. Fine source-region, single-age, detailed education, high-order family, and earnings-tail cells are presumptively report-only until their support proves otherwise. +`reported_entry_duration_proxy = survey_year - reported_year_of_entry`; a +derived age proxy subtracts that duration from interview age under a frozen age/ +birthday convention. Neither is literal duration or age at arrival, and neither +can certify O12's arrival-state bridge. The constructed unit is a co-resident +same-reported-entry unit, never a claimed historical travel party. + ### 5.5 Report-only evaluation The following are useful but are not gate truth: @@ -960,7 +970,7 @@ until an acquisition PR records the actual bytes. | `ssa_tr2026_v_a2_intermediate` | Social Security Administration, *[The 2026 Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds](https://www.ssa.gov/OACT/TR/2026/tr2026.pdf)*, §V.A.3, and Supplemental Single-Year Table V.A2, “[Immigration Assumptions, Calendar Years 1940–2100](https://www.ssa.gov/oact/TR/2026/lr5a2.html),” assumptions set Feb. 2026, report released June 9, 2026. | Annual intermediate LPR inflow/outflow/status-adjustment/net; temporary-or-unlawfully-present inflow/outflow/status-adjustment/net; total net; thousands→persons; retain source rounding. Use exact annual rows 2026–2100. The positive sum is an SSA stock-accounting inflow proxy; the temporary/unlawfully-present component counts year-end stayers, not all border arrivals. | Positive-inflow control candidate and net reconciliation. Forward-assumption/report-only until universe bridge and exit design exist; prohibited as gate-estimation data. | | `ssa_tr2026_v_a2_sensitivity` | Same report/table/vintage, low-cost and high-cost alternatives. | Same component schema; never substitute 75-year average or ultimate value for annual rows. | Report-only scenario sensitivity. | | `ssa_area_to_census_resident_bridge` | **UNBOUND.** Must reconcile the 2026 report's Social Security-area definition (glossary pp. 247–248) to the ACS/Census resident universe with an exact source and vintage. | Annual inclusion/exclusion or factor by population category; preserve an auditable raw-SSA series beside the bridged series. Identity is not an admissible silent default. | **BLOCKING** for a schedule labeled resident-population aligned. A raw `ssa_area_proxy` may run report-only. | -| `acs_pums_2010_2014_recent_arrivals` | Census Bureau, [2010–2014 ACS 5-year person PUMS `csv_pus.zip`](https://www2.census.gov/programs-surveys/acs/data/pums/2014/5-Year/csv_pus.zip); *[PUMS Data Dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)*, Jan. 14, 2016; *[Accuracy of the Data](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010_2014AccuracyPUMS.pdf)*; *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129. Observations 2010–2014. | Decode collection year from `SERIALNO`; bind `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, dual `YOEP05`/`YOEP12`, `NATIVITY`, dual place-of-birth classifications, `RELP`, education, disability, employment and income/earnings fields plus allocation flags. Fit 2010–2013; hold out 2014. Retain `reported_year_of_entry`, because responses may be first or most recent entry. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | +| `acs_pums_annual_2010_2014_recent_arrivals` | Census Bureau annual 1-year person PUMS `csv_pus.zip` files for survey years 2010–2014, with exact URLs, annual dictionaries and annual Accuracy statements in §2.2; 2014 Subject Definitions “Year of Entry,” pp. 128–129. Current 2010/2011 bytes are corrected re-releases dated Mar. 4, 2013 (ACS erratum 87); subsequent file vintages are Dec. 17, 2013 (2012), Oct. 23, 2014 (2013), and Oct. 27, 2015 (2014). | Bind each file/hash/release date separately. Set survey year from its manifest and assert `SERIALNO`; bind annual `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, `YOEP`, `POBP`, `NATIVITY`, `RELP`, education, disability, employment, income/earnings and allocation flags. Fit 2010–2013; seal annual 2014. The 5-year PUMS and weights are prohibited. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | | `acs_stock_to_arrival_state_bridge` | **UNBOUND.** No cited ACS cross-section identifies state at the arrival instant or everyone who subsequently left/died. | Must pin a duration/backcast law, survivor/stayer selection adjustment, reported-entry ambiguity treatment, repeat-entry identification and source vintage. An identity mapping is labeled `stock_proxy` only. | **BLOCKING** for literal entry-time characteristics; decision O12. | | `cps_asec_2014_foreign_born` | Census Bureau, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)*, *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*, and [2014 ASEC data page](https://www.census.gov/data/datasets/time-series/demo/cps/cps-asec.2014.html). Calendar-year 2013 income, 2014 interview characteristics. | `A-AGE`, `A-MARITL`, `A-SEX`, `A-HGA`, six disability items, `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT`, `WSAL-VAL`, `PEARNVAL`, `PTOTVAL`; civilian noninstitutional population plus Armed Forces members in civilian housing. Bind Traditional **or** Redesign bytes and correction/repost status. | Report-only marginal triangulation. Exact file choice is O7; the two designs may not be combined silently. | | `sipp_2014_wave1_entry_state` | Census Bureau, *[2014 SIPP Metadata All Sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*, Sept. 12, 2017; [Wave 1 raw directory](https://www2.census.gov/programs-surveys/sipp/data/datasets/2014/w1/); *[SIPP 2014 Panel Source and Accuracy Statement, Wave 1](https://www2.census.gov/programs-surveys/sipp/tech-documentation/source-accuracy-statements/2014/sipp-2014-source-and-accuracy-statement.pdf)*. Interviews in 2014, reference year 2013. The directory is discovery evidence, not an immutable file binding; exact public-use filename/version and correction status are **UNBOUND** pending O8. | Candidate concepts: `WPFINWGT`, marital state/history, age, `EBORNUS`, `ECITIZEN`, `ENATCIT`, grouped `TYRENTRY`, education, sex, disability and monthly earnings. `TIMSTAT` is excluded from legal-status state. | Report-only joint-state/initializer diagnostics after exact bytes are bound. No later-wave newly arrived immigrant-only household coverage claim. | @@ -984,12 +994,13 @@ total_net = lpr_net + temporary_net within the source's thousand-person rounding. It must not treat status adjustment as two events or as a new arrival. -The ACS extractor must assert each collection year from `SERIALNO`, apply the -correct dual-year-of-entry and place-of-birth classifications for that collection -vintage, use person and replicate weights, and publish allocation/top-code/group- -quarters counts. It must use `reported_year_of_entry`: the intended interviewer -concept is most recent entry, while unclarified/self responses may mean first or -most recent entry. `first_entry_year` is prohibited without another source. +The ACS extractor must resolve five separate annual manifests, assert each +manifest year against `SERIALNO`, map that annual vintage's `YOEP` and `POBP`, +use only that file's person and replicate weights, and publish allocation/top- +code/group-quarters counts. It must hard-fail on a 5-year pooled input. It must use +`reported_year_of_entry`: the intended interviewer concept is most recent entry, +while unclarified/self responses may mean first or most recent entry. +`first_entry_year` is prohibited without another source. The Census parser must preserve its July-to-June event year and resident- population universe. A calendar-year bridge to Trustees may be displayed only as @@ -1061,11 +1072,13 @@ validation. ### O6. Observation date versus publication date at `T*` -The proposed ACS pooled file contains only 2010–2014 observations but was -published in January 2016. Ratify an observation-date rule analogous to the M6 -NAWI publication-lag reasoning, or reject the pooled file and redesign the gate -around individually released pre-boundary files. The same issue affects the -later-published SIPP metadata, which is report-only here. +The proposed annual ACS files contain 2010–2014 observations, but the 2014 file +vintage is Oct. 27, 2015; corrected 2010/2011 bytes are Mar. 4, 2013, and the +2012/2013 vintages are Dec. 17, 2013/Oct. 23, 2014. Ratify an observation-date +rule analogous to the M6 NAWI publication-lag reasoning, or reject every file +whose release crosses the boundary and redesign an earlier annual holdout. The +five-year pooled file is not an alternative under either rule. The same issue +affects later-published SIPP metadata, which is report-only here. ### O7. CPS ASEC diagnostic vintage @@ -1218,11 +1231,13 @@ excluded. Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds*, §V.A.3, and Supplemental Single-Year Table V.A2. -- **Microdata**: Census 2010–2014 ACS 5-year PUMS dictionary, accuracy statement, - and 2014 ACS Subject Definitions “Year of Entry,” pp. 128–129; Census 2014 - Traditional and Redesigned ASEC technical documentation; Census 2014 SIPP - Wave 1 metadata and source/accuracy statement. The exact SIPP raw file remains - unbound at O8. Exact variables and pages are pinned in §2.2 and §6.2. +- **Microdata**: Census annual 1-year ACS PUMS person files and annual Accuracy + statements for 2010–2014, with the 2010–2014 dictionary as schema/crosswalk + evidence and 2014 ACS Subject Definitions “Year of Entry,” pp. 128–129; Census + 2014 Traditional and Redesigned ASEC technical documentation; Census 2014 SIPP + Wave 1 metadata and source/accuracy statement. The five-year ACS file is + excluded from the gate; the exact SIPP raw file remains unbound at O8. Exact + variables and pages are pinned in §2.2 and §6.2. - **Projection corridors**: Census, *Methodology, Assumptions, and Inputs for the 2023 National Population Projections* (November 2023), migration pp. 8–14, and Alternative Scenarios Table 1. From e43b4489d51c3f2bc3089f1cad519c4d10b36083 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 18:14:51 -0400 Subject: [PATCH 10/18] Resolve projection origin and complete entrant bindings Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 170 ++++++++++++++++++++---------- 1 file changed, 115 insertions(+), 55 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 3588f925..02b0f19e 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -22,7 +22,7 @@ claiming, flow-to-stock, and stock-to-arrival blockers; composes immigrant IDs with the existing 2017/2019 schedule; guards caller-supplied allocators; and requires entrant RNG isolation before any byte-identity claim → §2.2–2.4, - §3.1–3.4, §4.1–4.11, §5, §6, O2/O5/O8–O14. + §3.1–3.4, §4.1–4.11, §5, §6, O2/O5/O8–O15. - Dormant-generator finding: the engine already owns an entrant seam, but there is no immigration schedule generator → §3.1, §4. - Net-is-not-entry finding: the 2026 Trustees component table distinguishes @@ -159,7 +159,7 @@ reconciliation remains report-only. | DYNASIM4 | The 2024 overview says immigration adds people, lists immigration and emigration separately, and says immigration is aligned to OACT targets (Cosic, Johnson, and Smith, *[Urban's Dynamic Simulation of Income Model 4](https://www.urban.org/sites/default/files/2024-09/Urban%E2%80%99s%20Dynamic%20Simulation%20of%20Income%20Model%204.pdf)*, pp. 1–2). | The public 2024 overview does not document a detailed donor algorithm. | Cite DYNASIM4 only for the listed flows and OACT alignment; do not attribute undocumented separation or donor mechanics to it. | | DYNASIM3 detail | Table 1 of Favreault, Smith, and Johnson, *[The Dynamic Simulation of Income Model (DYNASIM): An Overview](https://www.urban.org/sites/default/files/publication/67366/2000391-The-Dynamic-Simulation-of-Income-Model-DYNASIM-%20An-Overview.pdf)* (2015), p. 7, uses OACT/Dowhan-Duleep targets by sex, age at entry, and source region, and a separate SSA-data emigration hazard using entry age and origin. | The same table says observed post-1980 immigrants' life histories are donors. | Donor histories plus distinct exit hazards are a useful precedent, but this report describes DYNASIM3 and cannot establish DYNASIM4's detailed implementation. | | MINT6/MINT8 | MINT6 derived gross flows from OACT net targets and an emigration hazard; MINT8 uses projected gross legal and other-than-legal entries and models emigration separately (Smith et al., *[Modeling Income in the Near Term Version 6](https://www.urban.org/sites/default/files/publication/24986/412479-Modeling-Income-in-the-Near-Term-Version-.PDF)*, ch. II §VI, pp. II-24–II-28; Smith and Favreault, *[Modeling Income in the Near Term 8 and 2014: Primer](https://www.urban.org/sites/default/files/publication/100965/modeling_income_in_the_near_term_8_and_2014_primer.pdf)*, pp. 15–16, note 21 p. 29, Table 3 pp. 39–40). | MINT6 uses post-1990 SIPP immigrants to initialize sex, immigration age, source region, marital history/status, financial assets, and employment at arrival. It then runs ordinary post-entry modules. | Copy a coherent entry packet, never a donor's future. An initializer and the later transition laws are separate estimands. | -| PENSIM | Holmer, Janney, and Cohen, *[PENSIM Overview](https://www.retirementplanblog.com/wp-content/uploads/sites/304/2006/10/overview.pdf)* (Policy Simulation Group for the U.S. Department of Labor, Employee Benefits Security Administration, Sept. 2006), §2.1.6 p. 8, combines SSASIM/Trustees net immigration with native- and foreign-born emigration assumptions to derive gross flows; Appendix B §§B.1.2–B.1.4 pp. 100–101 schedules entry and exit from a life synthesized at birth. | A person's whole pre-entry life exists before the immigration event. | Whole-life synthesis avoids missing histories, but is not portable to a roster that materializes a person at entry. The needed analogue is an explicit entry-state packet. | +| PENSIM | Holmer, Janney, and Cohen, *[PENSIM Overview](https://www.retirementplanblog.com/wp-content/uploads/sites/304/2006/10/overview.pdf)* (Policy Simulation Group for the U.S. Department of Labor, Employee Benefits Security Administration, Sept. 2006), §2.1.6 p. 8, combines SSASIM/Trustees net immigration with native- and foreign-born emigration assumptions to derive gross flows; Appendix B §B.1 p. 99 begins a synthetic life at age zero, §§B.1.2–B.1.3 p. 100 schedule immigration/emigration, and §§B.7–B.8 pp. 106–107 execute them. | A person's whole pre-entry life exists before the immigration event. | Whole-life synthesis avoids missing histories, but is not portable to a roster that materializes a person at entry. The needed analogue is an explicit entry-state packet. | | PENSIM2 | O'Donoghue, Redway, and Lennon, *[Simulating migration in the Pensim2 dynamic microsimulation model](https://www.microsimulation.pub/articles/00039)* (2010), §5.1 and Figure 3, disaggregates ONS net controls into gross immigration and emigration. | §3 discusses synthetic generation versus cloning and Table 2 inventories model components; §5.2 samples immigrant **families** from the 2003 Labour Force Survey and calibrates person totals. | Preserve joint family state and distinguish the control unit from the donor/simulation unit. Net-only migration can bias population structure (§3 and §4). | MINT is the closest architectural analogue. Earlier MINT versions cloned a @@ -185,9 +185,9 @@ emigration cannot be ignored. | Source | Exact public support | V1 role | Binding limitation | |---|---|---|---| -| ACS PUMS | Census annual 1-year person PUMS files for [2010](https://www2.census.gov/programs-surveys/acs/data/pums/2010/1-Year/csv_pus.zip), [2011](https://www2.census.gov/programs-surveys/acs/data/pums/2011/1-Year/csv_pus.zip), [2012](https://www2.census.gov/programs-surveys/acs/data/pums/2012/1-Year/csv_pus.zip), [2013](https://www2.census.gov/programs-surveys/acs/data/pums/2013/1-Year/csv_pus.zip), and [2014](https://www2.census.gov/programs-surveys/acs/data/pums/2014/1-Year/csv_pus.zip); annual dictionaries [2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict10.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict11.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict12.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict13.pdf), and [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict14.pdf); and corresponding annual Accuracy statements ([2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010AccuracyPUMS.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2011AccuracyPUMS.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2012AccuracyPUMS.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2013AccuracyPUMS.pdf), [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2014AccuracyPUMS.pdf)). The *[2010–2014 PUMS dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* is crosswalk evidence only. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents response ambiguity. | Primary joint-stock donor and gate truth only for the named stock-proxy surface. Fit 2010–2013 with each annual file's `PWGTP` and replicate weights; hold the separately weighted 2014 file out in full. Bind annual `YOEP`, `POBP`, `AGEP`, `SEX`, `RELP`, education, disability, employment and earnings concepts. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The gate never uses 5-year pooled weights, which are reraked to a five-year population. Current 2010/2011 bytes are the corrected Mar. 4, 2013 re-releases in [ACS erratum 87](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/087.html); observation versus release date remains O6. | +| ACS PUMS | Census annual 1-year person PUMS files for [2010](https://www2.census.gov/programs-surveys/acs/data/pums/2010/1-Year/csv_pus.zip), [2011](https://www2.census.gov/programs-surveys/acs/data/pums/2011/1-Year/csv_pus.zip), [2012](https://www2.census.gov/programs-surveys/acs/data/pums/2012/1-Year/csv_pus.zip), [2013](https://www2.census.gov/programs-surveys/acs/data/pums/2013/1-Year/csv_pus.zip), and [2014](https://www2.census.gov/programs-surveys/acs/data/pums/2014/1-Year/csv_pus.zip); annual dictionaries [2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict10.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict11.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict12.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict13.pdf), and [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict14.pdf); and corresponding annual Accuracy statements ([2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010AccuracyPUMS.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2011AccuracyPUMS.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2012AccuracyPUMS.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2013AccuracyPUMS.pdf), [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2014AccuracyPUMS.pdf)). The *[2010–2014 PUMS dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* is crosswalk evidence only. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents response ambiguity. | Primary joint-stock donor and gate truth only for the named stock-proxy surface. Fit 2010–2013 with each annual file's `PWGTP` and replicate weights; hold the separately weighted 2014 file out in full. Bind annual `YOEP`, `POBP`, `AGEP`, `SEX`, `RELP`, education, disability, employment and earnings concepts. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The gate never uses 5-year pooled weights. Current 2010/2011 bytes are corrected Mar. 4, 2013 re-releases ([erratum 87](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/087.html)); the current 2013 person archive was reposted Feb. 12, 2015 alongside a housing-only `MV` correction ([erratum 97](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/097.html)). Exact bytes/correction status and observation versus release date remain bound/O6 decisions. | | CPS ASEC | Census, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)* or *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: the cited Redesigned layout has demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian noninstitutional universe plus Armed Forces members living in civilian housing; grouped entry years; survey-date demographics versus prior-calendar-year income. Traditional and Redesign files must never be silently combined. | -| SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves miss newly arrived immigrant-only households. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | +| SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves do not represent newly arrived immigrant-only households, although new co-residents of original sample people can enter. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | The ACS donor predicate is named, not implied: @@ -196,13 +196,14 @@ foreign_born == true and 0 <= survey_year - reported_year_of_entry <= recent_arrival_max_duration ``` -`survey_year` is fixed by the annual-file manifest and cross-checked against -`SERIALNO`; annual `YOEP` supplies the reported year. The initial proposal is -a 0–4 year window, but the exact duration, annual-pooling rule, and fallback -hierarchy remain decision O3. +`survey_year` comes only from the bound annual-file manifest; `SERIALNO` is a +within-file household/GQ identifier and contains no year. Annual `YOEP` supplies +the reported year. The training unit key is therefore +`(survey_year, SERIALNO)`. The initial proposal is a 0–4 year window, but the +exact duration, annual-pooling rule, and fallback hierarchy remain decision O3. The extractor must bind allocation-flag treatment, top/bottom-code treatment, -group-quarters policy, dual classifications, replicate weights, and the use of -`ADJINC` before any artifact can be certified. +group-quarters policy, per-year schema crosswalks, replicate weights, and the use +of `ADJINC` before any artifact can be certified. This predicate defines a resident **stock proxy**, not entry-time truth. Education, marriage, disability, employment, earnings, survival, and residence may all @@ -340,6 +341,14 @@ convention or authorize a separately scoped wrapper inside the mortality/aging slots. The builder may not hide an age shift or age `-1` inside donor extraction, and every choice retains the seam's `year = entry_year - 1` contract. +That choice must respect the source component's exposure basis. Table V.A2's +temporary/unlawfully-present inflow is already conditioned on remaining through +year end; applying the unchanged engine's full source-year mortality to the raw +control would apply a second survival filter. O2 therefore blocks production +until a component-aware aggregate timing/exposure bridge is bound. It may alter +the cohort control/exposure convention, but it may not assign a Trustees stock or +legal-status label to individual donor rows. + IDs are assigned outside the loop in deterministic order. They must be finite integers, greater than every starting-population **or pre-existing scheduled** ID, collision-free across all years, and invariant to row order. These conditions @@ -498,12 +507,12 @@ process-error draws. ### 4.3 Annual cohort sizing -For Trustees calendar year `y`, define the unbridged new-person control +For Trustees calendar year `y`, define the unbridged positive-inflow control ```text G_ssa_stock[y] = 1,000 * ( - V_A2_intermediate[y].lpr_new_arrival_inflow - + V_A2_intermediate[y].temporary_or_unlawfully_present_inflow + V_A2_selected_path[y].lpr_new_arrival_inflow + + V_A2_selected_path[y].temporary_or_unlawfully_present_inflow ) ``` @@ -514,11 +523,28 @@ intermediate total-net column is retained as `N_ssa[y]` for reconciliation only. `G_ssa_stock` is not yet a usable resident-population cohort. It includes the temporary/unlawfully present end-of-year-stayer condition. Production construction requires an adjudicated, vintage-pinned bridge -`G_resident_entry_proxy[y] = bridge(G_ssa_stock[y])` between the Social Security-area stock accounting and ACS -resident universes. Until decision O11 supplies that bridge, the builder must -either hard-stop or produce an explicitly named `ssa_area_proxy` schedule whose -entire projection is report-only. It may not silently set the bridge to identity -and label the result resident-population aligned. +`G_resident_entry_proxy[y] = bridge(G_ssa_stock[y])` between the Social +Security-area stock accounting and ACS resident universes. The calibration target +is conditional and both source series remain in the audit: + +```text +G_schedule_target[y] = + G_resident_entry_proxy[y] for a resident-labeled run with O11 bound + G_ssa_stock[y] only for an explicitly report-only ssa_area_proxy +``` + +Until O11 supplies the universe bridge, the builder must either hard-stop or use +the second branch. It may not silently set the bridge to identity and label the +result resident-population aligned. + +The schedule interval is also conditional on O15 and must be continuous from +`start_year + 1` through 2100. A report-only open run retaining M6's 2014 initial +slice uses Table V.A2 historical/estimated rows for 2015–2025 (preserving the +source's row-class and footnote flags) and intermediate-assumption rows for +2026–2100. A separately bound 2025 initial slice needs only the latter. A 2026 +initial slice cannot accept a 2026 schedule key: that cohort must be demonstrably +included in baseline stock or the run has an omission/double-count. No 2015–2025 +gap or silently dropped first cohort is permitted. The schedule uses a manageable synthetic sample and positive calibration weights; it does not create 1.34 million physical rows in 2026. For each year: @@ -527,8 +553,8 @@ weights; it does not create 1.34 million physical rows in 2026. For each year: before the truth floor, not by the external population count or candidate; - unit sampling preserves all members selected together; - person weights are finite and positive; -- the sum of person weights equals `G_resident_entry_proxy[y]` within a pinned numerical - tolerance; +- the sum of person weights equals the selected `G_schedule_target[y]` branch + within a pinned numerical tolerance; - age/sex and other composition margins come from the frozen donor artifact, never from Table V.A2, which has no public age/sex detail; and - no unannounced ultimate-value or nearest-year fallback is allowed. A missing @@ -544,15 +570,15 @@ PENSIM2's family sampling exposes a real unit mismatch: the external control is people, while the state to preserve may be a family. V1's provisional unit is a **co-resident co-arrival unit**, not a claimed historical travel party: -1. Start with a PUMS household (`SERIALNO`). +1. Start with an annual PUMS household (`survey_year, SERIALNO`). 2. Select foreign-born recent-arrival people with the same reported-year-of-entry classification. 3. Preserve only links unambiguously resolvable from the historical PUMS `RELP` relationship-to-reference-person field (for example, the reference person's spouse and children) when both endpoints are selected. Arbitrary spouse/parent pointers are unavailable and remain unresolved. -4. Assign a new `arrival_unit_id`; never expose `SERIALNO` as a synthetic person - or household identifier. +4. Assign a new `arrival_unit_id`; never expose either element of the source + tuple as a synthetic person or household identifier. A spouse, child, or parent who is native-born, entered in a different year, or is absent from the PUMS household is not cloned. The entrant may retain an observed @@ -805,15 +831,17 @@ The primary proposed split uses five separately released annual ACS 1-year PUMS files: - fit donor construction and all matching/calibration choices on the 2010–2013 - annual files using each year's own person and replicate weights, with the - cross-year pooling/normalization rule frozen from training only; + annual files using each year's own person and replicate weights, with equal- + year-mass versus population-mass pooling and cross-year normalization frozen + from training only; - freeze the candidate artifact and surface; - generate a synthetic 2014 recent-arrival resident cross-section without reading any 2014 person record, weight, or marginal; and - score against the separately weighted annual 2014 file using the same recent- arrival predicate, concept map, universe, and annual-weight treatment. -Households/arrival units are indivisible. The truth and candidate normalize to +Households/arrival units keyed by `(survey_year, SERIALNO)` are indivisible. The +truth and candidate normalize to the same total before characteristic scoring; the total itself is not a gate cell. No 2014 characteristic, marginal, top-code treatment selected after seeing the holdout, CPS/SIPP statistic, current Trustees assumption, or Census projection @@ -841,8 +869,10 @@ The ceremony order is mandatory: rule, concept map, matching ladder, gate cells, metrics, and weighting rules without candidate holdout results. 2. Construct a correlation-respecting real-vs-real floor from deterministic, - household-disjoint splits or survey replicate-weight pseudo-replicates of the - 2014 truth. Never split members of one donor/household unit. + household-disjoint splits or the annual 2014 replicate-weight design. Never + split members of one `(survey_year, SERIALNO)` unit. Training uncertainty + treats each year's replicate set as a separate block; replicate columns are + never concatenated across years as one common design. 3. On training-era pseudo-holdouts only, run the complete donor-selection, calibration, fallback, and schedule pipeline across the registered seed grid. Freeze how candidate-pipeline variability combines with the truth-side floor; @@ -937,8 +967,9 @@ otherwise. ### 6.1 Manifest contract -Every external or derived input is represented by a field-level manifest entry, -following the sibling §2.8.10 pattern. Each entry must contain: +Every external or derived input selected for a run is represented by a field- +level manifest entry, following the sibling §2.8.10 pattern. Each entry must +contain: - stable binding ID and semantic version; - source agency, exact report/file title, table/section, scenario and columns; @@ -967,23 +998,29 @@ until an acquisition PR records the actual bytes. | Binding ID | Exact source and vintage | Fields/transformation | Consumer and status | |---|---|---|---| -| `ssa_tr2026_v_a2_intermediate` | Social Security Administration, *[The 2026 Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds](https://www.ssa.gov/OACT/TR/2026/tr2026.pdf)*, §V.A.3, and Supplemental Single-Year Table V.A2, “[Immigration Assumptions, Calendar Years 1940–2100](https://www.ssa.gov/oact/TR/2026/lr5a2.html),” assumptions set Feb. 2026, report released June 9, 2026. | Annual intermediate LPR inflow/outflow/status-adjustment/net; temporary-or-unlawfully-present inflow/outflow/status-adjustment/net; total net; thousands→persons; retain source rounding. Use exact annual rows 2026–2100. The positive sum is an SSA stock-accounting inflow proxy; the temporary/unlawfully-present component counts year-end stayers, not all border arrivals. | Positive-inflow control candidate and net reconciliation. Forward-assumption/report-only until universe bridge and exit design exist; prohibited as gate-estimation data. | +| `ssa_tr2026_v_a2_components` | Social Security Administration, *[The 2026 Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds](https://www.ssa.gov/OACT/TR/2026/tr2026.pdf)*, §V.A.3, and Supplemental Single-Year Table V.A2, “[Immigration Assumptions, Calendar Years 1940–2100](https://www.ssa.gov/oact/TR/2026/lr5a2.html),” assumptions set Feb. 2026, report released June 9, 2026. | Annual LPR inflow/outflow/status-adjustment/net; temporary-or-unlawfully-present inflow/outflow/status-adjustment/net; total net; thousands→persons; retain row class, estimate footnotes and rounding. Use historical/estimated 2015–2025 plus intermediate 2026–2100 for the 2014 M6 origin, or intermediate 2026–2100 for a bound 2025 origin. The positive sum is a stock-accounting inflow proxy; the temporary/unlawfully-present component counts year-end stayers. | Positive-inflow control candidate and net reconciliation. Report-only until universe/timing bridges and exit design exist; prohibited as gate-estimation data. | | `ssa_tr2026_v_a2_sensitivity` | Same report/table/vintage, low-cost and high-cost alternatives. | Same component schema; never substitute 75-year average or ultimate value for annual rows. | Report-only scenario sensitivity. | | `ssa_area_to_census_resident_bridge` | **UNBOUND.** Must reconcile the 2026 report's Social Security-area definition (glossary pp. 247–248) to the ACS/Census resident universe with an exact source and vintage. | Annual inclusion/exclusion or factor by population category; preserve an auditable raw-SSA series beside the bridged series. Identity is not an admissible silent default. | **BLOCKING** for a schedule labeled resident-population aligned. A raw `ssa_area_proxy` may run report-only. | -| `acs_pums_annual_2010_2014_recent_arrivals` | Census Bureau annual 1-year person PUMS `csv_pus.zip` files for survey years 2010–2014, with exact URLs, annual dictionaries and annual Accuracy statements in §2.2; 2014 Subject Definitions “Year of Entry,” pp. 128–129. Current 2010/2011 bytes are corrected re-releases dated Mar. 4, 2013 (ACS erratum 87); subsequent file vintages are Dec. 17, 2013 (2012), Oct. 23, 2014 (2013), and Oct. 27, 2015 (2014). | Bind each file/hash/release date separately. Set survey year from its manifest and assert `SERIALNO`; bind annual `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, `YOEP`, `POBP`, `NATIVITY`, `RELP`, education, disability, employment, income/earnings and allocation flags. Fit 2010–2013; seal annual 2014. The 5-year PUMS and weights are prohibited. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | +| `projection_origin_population` | Existing realized 2014 M6 initial slice for the recommended report-only integration path; a 2025/2026 resident baseline source and vintage are **UNBOUND** alternatives. | Bind `start_year`, population universe/artifact/hash, first schedule key, first-cohort disposition and continuous control interval. | **BLOCKING** for an origin other than the existing 2014 report-only open run; decision O15. | +| `entry_timing_exposure_bridge` | **UNBOUND.** Must document each Table V.A2 inflow component's event/survival timing and the selected population-origin convention with exact report text and vintage. | Translate controls to opening/mid/end-period exposure without applying source-year survival twice; bind scheduled and target-year age meaning. No person-level status assignment. | **BLOCKING** for a production entry schedule; decision O2. | +| `acs_pums_annual_2010_2014_recent_arrivals` | Census Bureau annual 1-year person PUMS `csv_pus.zip` files for survey years 2010–2014, with exact URLs, annual dictionaries and annual Accuracy statements in §2.2; 2014 Subject Definitions “Year of Entry,” pp. 128–129. Current 2010/2011 bytes are corrected Mar. 4, 2013 re-releases (erratum 87); 2012 is Dec. 17, 2013; current 2013 bytes are the Feb. 12, 2015 repost associated with housing-only erratum 97; 2014 is Oct. 27, 2015. | Bind each file/hash/release/correction status separately. Set survey year only from its manifest; namespace units as `(survey_year, SERIALNO)` and validate `SERIALNO` within file. Bind annual `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, `YOEP`, `POBP`, `NATIVITY`, `RELP`, education, disability, employment, income/earnings and allocation flags. Fit 2010–2013; seal annual 2014. The 5-year PUMS and weights are prohibited. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | | `acs_stock_to_arrival_state_bridge` | **UNBOUND.** No cited ACS cross-section identifies state at the arrival instant or everyone who subsequently left/died. | Must pin a duration/backcast law, survivor/stayer selection adjustment, reported-entry ambiguity treatment, repeat-entry identification and source vintage. An identity mapping is labeled `stock_proxy` only. | **BLOCKING** for literal entry-time characteristics; decision O12. | +| `entrant_marital_household_history_initializer` | **UNBOUND.** Candidate evidence is the annual ACS stock donor plus an exact O8 SIPP file or another named history source; source, universe and vintage are not selected. | Map entry marital history/status, spouse/relations outside roster, household seed, exposure start and later entrant-only law jointly. | **BLOCKING** for entrant marital/household domains and every mixed market; decisions O4/O5/O14. | +| `entrant_disability_state_bridge` | **UNBOUND.** Candidate ACS disability questions and SIPP work-limit/benefit concepts have no selected module-native mapping source/vintage. | Estimate entry state and an entrant-specific forward law without relabeling survey concepts as M4 status. | **BLOCKING** for entrant disability outputs; decision O5 and a successor gate. | +| `entrant_earnings_initializer_forward_law` | **UNBOUND.** Candidate annual ACS current earnings and exact O8 SIPP spell/history evidence; source, universe and vintage are not selected. | Estimate partial-year current-spell state, lags/persistence and entrant-only forward earnings; `m6_projected_wage_index` normalizes dollars but supplies no behavior. | **BLOCKING** for entrant earnings and downstream benefit outputs; decisions O5/O12 and a successor gate. | | `cps_asec_2014_foreign_born` | Census Bureau, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)*, *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*, and [2014 ASEC data page](https://www.census.gov/data/datasets/time-series/demo/cps/cps-asec.2014.html). Calendar-year 2013 income, 2014 interview characteristics. | `A-AGE`, `A-MARITL`, `A-SEX`, `A-HGA`, six disability items, `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT`, `WSAL-VAL`, `PEARNVAL`, `PTOTVAL`; civilian noninstitutional population plus Armed Forces members in civilian housing. Bind Traditional **or** Redesign bytes and correction/repost status. | Report-only marginal triangulation. Exact file choice is O7; the two designs may not be combined silently. | -| `sipp_2014_wave1_entry_state` | Census Bureau, *[2014 SIPP Metadata All Sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*, Sept. 12, 2017; [Wave 1 raw directory](https://www2.census.gov/programs-surveys/sipp/data/datasets/2014/w1/); *[SIPP 2014 Panel Source and Accuracy Statement, Wave 1](https://www2.census.gov/programs-surveys/sipp/tech-documentation/source-accuracy-statements/2014/sipp-2014-source-and-accuracy-statement.pdf)*. Interviews in 2014, reference year 2013. The directory is discovery evidence, not an immutable file binding; exact public-use filename/version and correction status are **UNBOUND** pending O8. | Candidate concepts: `WPFINWGT`, marital state/history, age, `EBORNUS`, `ECITIZEN`, `ENATCIT`, grouped `TYRENTRY`, education, sex, disability and monthly earnings. `TIMSTAT` is excluded from legal-status state. | Report-only joint-state/initializer diagnostics after exact bytes are bound. No later-wave newly arrived immigrant-only household coverage claim. | +| `sipp_2014_wave1_entry_state` | Census Bureau, *[2014 SIPP Metadata All Sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*, Sept. 12, 2017; [Wave 1 raw directory](https://www2.census.gov/programs-surveys/sipp/data/datasets/2014/w1/); *[SIPP 2014 Panel Source and Accuracy Statement, Wave 1](https://www2.census.gov/programs-surveys/sipp/tech-documentation/source-accuracy-statements/2014/sipp-2014-source-and-accuracy-statement.pdf)*. Interviews in 2014, reference year 2013. The directory is discovery evidence, not an immutable file binding; exact public-use filename/version and correction status are **UNBOUND** pending O8. | Candidate concepts: `WPFINWGT`, marital state/history, age, `EBORNUS`, `ECITIZEN`, `ENATCIT`, grouped `TYRENTRY`, education, sex, disability and monthly earnings. `TIMSTAT` is excluded from legal-status state. | Report-only joint-state/initializer diagnostics after exact bytes are bound. Later waves do not represent new immigrant-only households, though new co-residents of original sample people can enter. | | `entrant_fertility_history_bridge` | **UNBOUND.** Candidate evidence must name exact SIPP fertility-history or CPS fertility-supplement files, variables, universe, observation years and release vintage. | Map prior parity/birth history and exposure start jointly with entrant family state; never default parity to zero. | **BLOCKING** for entrant fertility risk; decision O13. | | `prior_us_covered_earnings_bridge` | **UNBOUND.** ACS reported year of entry and public survey earnings do not establish first entry or prior U.S. Social Security covered earnings. | Identify repeat-entry/first-entry status, covered quarters and prior indexed earnings with a source, universe and vintage; otherwise retain censored/unknown. | **BLOCKING** for entrant insured status, claiming, AIME/PIA and benefits; decision O12. | -| `census_np2023_nim_corridors` | Census Bureau, *[Methodology, Assumptions, and Inputs for the 2023 National Population Projections](https://www2.census.gov/programs-surveys/popproj/technical-documentation/methodology/methodstatement23.pdf)* (Nov. 2023), migration pp. 8–14; Alternative Scenarios Table 1, “Projected Population and Components of Change, 2022–2100”: [main](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1.xlsx), [high](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-h.xlsx), [low](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-l.xlsx), and [zero](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-z.xlsx) workbooks. | Annual net international migration in thousands for main/high/low/zero scenarios; July 1 prior year–June 30 current year. Preserve scenario definitions: alternatives change gross foreign-born immigration, not every migration component. | Report-only cross-model corridors; never gate truth or a positive entrant control. | -| `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: realized SSA NAWI through 2014 and `I_proj` beyond, estimated only from `<=T*`; see `m6_projection_engine.md:666-708,1723-1756`. | ACS `ADJINC` first expresses pooled income in 2014 dollars; any projection-year entrant earnings use the already pinned `I_proj`, never realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | +| `census_np2023_nim_corridors` | Census Bureau, *[Methodology, Assumptions, and Inputs for the 2023 National Population Projections](https://www2.census.gov/programs-surveys/popproj/technical-documentation/methodology/methodstatement23.pdf)* (Nov. 2023), migration pp. 8–14; Table 1 in the Main Series and each Alternative Scenario, “Projected Population and Components of Change for the United States, [Main Series/High Immigration Scenario/Low Immigration Scenario/Zero Immigration Scenario]: 2022–2100”: [main](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1.xlsx), [high](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-h.xlsx), [low](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-l.xlsx), and [zero](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-z.xlsx) workbooks. | Annual net international migration in thousands for main/high/low/zero scenarios; July 1 prior year–June 30 current year. Preserve scenario definitions: alternatives change gross foreign-born immigration, not every migration component. | Report-only cross-model corridors; never gate truth or a positive entrant control. | +| `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: realized SSA NAWI through 2014 and `I_proj` beyond, estimated only from `<=T*`; see `m6_projection_engine.md:666-708,1723-1756`. | Annual-file `ADJINC` first expresses income in that survey year's dollars. Before cross-year training/holdout comparison bind `earnings_2014 = earnings_y_after_ADJINC * I_proj[2014] / I_proj[y]`; projection-year entrant earnings reverse the ratio from the 2014 base. Never use realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | | `emigration_duration_hazard` | **UNBOUND.** Table V.A2 supplies aggregate outflow counts only. The Duleep-Dowhan 2008 hazards and legacy model methods are research evidence, not a current operational binding. | Must identify age, sex, source grouping, time since entry, family/individual unit, re-entry treatment, universe and vintage. | **BLOCKING** for explicit exits and any Trustees net-alignment claim; outside entry-builder v1. | ### 6.3 Binding-specific guards -The SSA parser must assert scenario labels, all nine component columns, annual -coverage, units, and the internal identities +The SSA parser must assert scenario labels, all nine component columns, continuous +annual coverage from `start_year + 1` through 2100, units, and the internal +identities ```text lpr_net = lpr_inflow - lpr_outflow + status_adjustment @@ -994,10 +1031,11 @@ total_net = lpr_net + temporary_net within the source's thousand-person rounding. It must not treat status adjustment as two events or as a new arrival. -The ACS extractor must resolve five separate annual manifests, assert each -manifest year against `SERIALNO`, map that annual vintage's `YOEP` and `POBP`, -use only that file's person and replicate weights, and publish allocation/top- -code/group-quarters counts. It must hard-fail on a 5-year pooled input. It must use +The ACS extractor must resolve five separate annual manifests, set and validate +`survey_year` from the manifest/path alone, namespace household/GQ linkage by +`(survey_year, SERIALNO)`, map that annual vintage's `YOEP` and `POBP`, use +only that file's person and replicate weights, and publish allocation/top-code/ +group-quarters counts. It must hard-fail on a 5-year pooled input. It must use `reported_year_of_entry`: the intended interviewer concept is most recent entry, while unclarified/self responses may mean first or most recent entry. `first_entry_year` is prohibited without another source. @@ -1030,12 +1068,15 @@ physical border arrival. The population-universe bridge is a separate O11. ### O2. Entry-year timing, age, and mortality exposure The seam inserts the prior-year-coordinate row before mortality and aging. -Choose either (a) the feasible unchanged-engine convention—full mortality at the -scheduled age followed by `age += 1`—or (b) an explicitly scoped entrant-aware -wrapper in the mortality/aging slots for fractional or deferred exposure. Also -bind whether the external calendar-year inflow is opening-, mid-, or end-period -and what age means on each side. The builder may not simulate a timing choice with -age `-1` or a hidden donor-age shift. +Choose either (a) the feasible unchanged-engine convention—after an explicit +source-to-opening-exposure transformation, full mortality at the scheduled age +followed by `age += 1`—or (b) an entrant-aware wrapper in the mortality/aging +slots for fractional or deferred exposure. The temporary/unlawfully-present +control already excludes people who do not remain through year end; applying +unadjusted full source-year mortality would double-filter survival and is +prohibited. Bind the component-specific source timing, the aggregate translation, +and what age means on each side without assigning source-stock/legal status to +persons. The builder may not use age `-1` or a hidden donor-age shift. ### O3. Recent-arrival window and matching ladder @@ -1073,10 +1114,11 @@ validation. ### O6. Observation date versus publication date at `T*` The proposed annual ACS files contain 2010–2014 observations, but the 2014 file -vintage is Oct. 27, 2015; corrected 2010/2011 bytes are Mar. 4, 2013, and the -2012/2013 vintages are Dec. 17, 2013/Oct. 23, 2014. Ratify an observation-date -rule analogous to the M6 NAWI publication-lag reasoning, or reject every file -whose release crosses the boundary and redesign an earlier annual holdout. The +vintage is Oct. 27, 2015; corrected 2010/2011 bytes are Mar. 4, 2013; 2012 is +Dec. 17, 2013; and the current 2013 archive is the Feb. 12, 2015 repost whose +erratum affected only a housing-file variable. Ratify an observation-date rule +analogous to the M6 NAWI publication-lag reasoning, or reject every file whose +byte vintage crosses the boundary and redesign an earlier annual holdout. The five-year pooled file is not an alternative under either rule. The same issue affects later-published SIPP metadata, which is report-only here. @@ -1140,6 +1182,23 @@ addresses. Decide whether entrant/existing-person marriage and household markets remain a separate report-only product. No byte-identity claim is admissible from stable person ordinals alone. +### O15. Projection origin and the first entrant cohort + +Choose one complete origin contract: + +- **recommended for the existing M6 integration path**: retain the realized 2014 + initial slice and bind the 2026 Table V.A2 historical/estimated 2015–2025 rows + plus intermediate 2026–2100 rows in a separate report-only open run; +- bind an independently constructed 2025 initial resident slice, then schedule + 2026–2100 through the seam; or +- use a 2026 initial slice only if its construction proves the 2026 entrant cohort + is already included, then begin seam scheduling in 2027. + +The seam requires `entry_year > start_year`. The decision must name the initial- +population artifact/vintage, first schedule key, control range, and whether the +first cohort is baseline stock or a seam flow. It may neither omit 2015–2025 under +a 2014 start nor schedule an entry-year-equal-to-start-year frame. + ## 8. What this design does not change This document and its eventual entrant-side implementation must leave these @@ -1153,6 +1212,7 @@ authorizes surgery: - the certified candidate-16 marital core, candidate-9 household composition object, M4 disability reproduction object, gate-2c earnings modifier, and gate-1/backward or M6/forward certified earnings specifications; +- the existing age/sex mortality fit and frozen `<=2014` claiming schedule; - the §2.8.3a earnings-domain predicate and its realized-2014 state maps; - the §2.8.2g marital risk-set guard and seed-at-domain-entry law; - amendment 3h's schedule-versus-live-roster materialization distinction and @@ -1178,7 +1238,7 @@ report-only O14 product and makes no closed-run byte-identity claim. A later implementation should proceed in this order: -1. Referee resolves O1–O14 for the chosen implementation slice and ratifies the +1. Referee resolves O1–O15 for the chosen implementation slice and ratifies the external-binding schema. 2. Acquisition PR commits/hash-binds exact source bytes and parsers; the zero- argument binding factory passes independently of any candidate. @@ -1220,8 +1280,8 @@ excluded. Institute, April 2019), pp. 15–16, note 21 p. 29, Table 3 pp. 39–40. - **PENSIM/PENSIM2**: Holmer, Janney, and Cohen, *PENSIM Overview* (Policy Simulation Group for the U.S. Department of Labor, Employee Benefits Security - Administration, September 2006), §2.1.6 p. 8, Appendix B §§B.1.2–B.1.4 - pp. 100–101 and §§B.7–B.8 pp. 106–107; + Administration, September 2006), §2.1.6 p. 8, Appendix B §B.1 p. 99, + §§B.1.2–B.1.3 p. 100, and §§B.7–B.8 pp. 106–107; O'Donoghue, Redway, and Lennon, “Simulating migration in the Pensim2 dynamic microsimulation model,” *International Journal of Microsimulation* 3(2), 2010, Table 2, §§5.1–5.2. @@ -1240,7 +1300,7 @@ excluded. variables and pages are pinned in §2.2 and §6.2. - **Projection corridors**: Census, *Methodology, Assumptions, and Inputs for the 2023 National Population Projections* (November 2023), migration pp. 8–14, and - Alternative Scenarios Table 1. + Table 1 in the Main Series and each Alternative Scenario. ## 11. Design parameters and amendment history From 6429e63664e3c2f75e39af8780338a0c124e4809 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 18:17:20 -0400 Subject: [PATCH 11/18] Bind annual ACS concept and correction breaks Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 02b0f19e..840743d4 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -3,7 +3,7 @@ - **Design id**: `2026-07-15-immigration-module` - **Roadmap**: [#113](https://github.com/PolicyEngine/populace-dynamics/issues/113), M6 immigration entry cohorts and the versioned Trustees alignment layer. -- **Status**: DESIGN DRAFT (revision 2; adversarial-referee adjudication pending). +- **Status**: DESIGN DRAFT (revision 3; adversarial-referee adjudication pending). No immigration surface is certified by this document. - **Engine baseline**: `75d30dd57d71b91ee0929246b2f3cbb92263b350`. File:line pins refer to that tree unless a different source is named. @@ -16,6 +16,12 @@ ## Revision log (finding → section) +- Revision 3 replaces invalid collection-year slicing of five-year ACS PUMS with + separately weighted annual 1-year files; freezes year-namespaced units, annual + replicate designs and cross-year normalization; adds component-aware timing, + conditional controls, a projection-origin/first-cohort decision, and explicit + module-native initializer blockers → §2.2, §3.2, §4.2–4.9, §5, §6, + O2/O3/O5/O6/O11–O15. - Revision 2 incorporates the pre-PR adversarial review: it distinguishes the ACS survivor/stayer stock proxy from state at arrival; treats prior U.S. covered earnings as censored for possible return entrants; adds fertility, @@ -185,7 +191,7 @@ emigration cannot be ignored. | Source | Exact public support | V1 role | Binding limitation | |---|---|---|---| -| ACS PUMS | Census annual 1-year person PUMS files for [2010](https://www2.census.gov/programs-surveys/acs/data/pums/2010/1-Year/csv_pus.zip), [2011](https://www2.census.gov/programs-surveys/acs/data/pums/2011/1-Year/csv_pus.zip), [2012](https://www2.census.gov/programs-surveys/acs/data/pums/2012/1-Year/csv_pus.zip), [2013](https://www2.census.gov/programs-surveys/acs/data/pums/2013/1-Year/csv_pus.zip), and [2014](https://www2.census.gov/programs-surveys/acs/data/pums/2014/1-Year/csv_pus.zip); annual dictionaries [2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict10.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict11.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict12.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict13.pdf), and [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict14.pdf); and corresponding annual Accuracy statements ([2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010AccuracyPUMS.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2011AccuracyPUMS.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2012AccuracyPUMS.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2013AccuracyPUMS.pdf), [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2014AccuracyPUMS.pdf)). The *[2010–2014 PUMS dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* is crosswalk evidence only. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents response ambiguity. | Primary joint-stock donor and gate truth only for the named stock-proxy surface. Fit 2010–2013 with each annual file's `PWGTP` and replicate weights; hold the separately weighted 2014 file out in full. Bind annual `YOEP`, `POBP`, `AGEP`, `SEX`, `RELP`, education, disability, employment and earnings concepts. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The gate never uses 5-year pooled weights. Current 2010/2011 bytes are corrected Mar. 4, 2013 re-releases ([erratum 87](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/087.html)); the current 2013 person archive was reposted Feb. 12, 2015 alongside a housing-only `MV` correction ([erratum 97](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/097.html)). Exact bytes/correction status and observation versus release date remain bound/O6 decisions. | +| ACS PUMS | Census annual 1-year person PUMS files for [2010](https://www2.census.gov/programs-surveys/acs/data/pums/2010/1-Year/csv_pus.zip), [2011](https://www2.census.gov/programs-surveys/acs/data/pums/2011/1-Year/csv_pus.zip), [2012](https://www2.census.gov/programs-surveys/acs/data/pums/2012/1-Year/csv_pus.zip), [2013](https://www2.census.gov/programs-surveys/acs/data/pums/2013/1-Year/csv_pus.zip), and [2014](https://www2.census.gov/programs-surveys/acs/data/pums/2014/1-Year/csv_pus.zip); annual dictionaries [2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict10.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict11.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict12.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict13.pdf), and [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMSDataDict14.pdf); and corresponding annual Accuracy statements ([2010](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2010AccuracyPUMS.pdf), [2011](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2011AccuracyPUMS.pdf), [2012](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2012AccuracyPUMS.pdf), [2013](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2013AccuracyPUMS.pdf), [2014](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/accuracy/2014AccuracyPUMS.pdf)). The *[2010–2014 PUMS dictionary](https://www2.census.gov/programs-surveys/acs/tech_docs/pums/data_dict/PUMS_Data_Dictionary_2010-2014.pdf)* is crosswalk evidence only. The *[2014 ACS Subject Definitions](https://www2.census.gov/programs-surveys/acs/tech_docs/subject_definitions/2014_ACSSubjectDefinitions.pdf)*, “Year of Entry,” pp. 128–129, documents response ambiguity. | Primary joint-stock donor and gate truth only for the named stock-proxy surface. Fit 2010–2013 with each annual file's `PWGTP` and replicate weights; hold the separately weighted 2014 file out in full. Bind annual `YOEP`, `POBP`, `AGEP`, `SEX`, `RELP`, education, disability, employment and earnings concepts. | A recent-arrival respondent is a resident survivor/stayer observed at interview, not a gross arrival. Interviewers request the most recent entry, but unclarified/mail answers can be first or most recent. `WAGP` covers the prior 12 months, possibly including pre-entry months. `RELP` identifies relationship to the reference person, not arbitrary relationship pointers. The gate never uses 5-year pooled weights. Current 2010/2011 bytes are corrected Mar. 4, 2013 re-releases ([erratum 87](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/087.html)); the current 2013 person archive was reposted Feb. 12, 2015 alongside a housing-only `MV` correction ([erratum 97](https://www.census.gov/programs-surveys/acs/technical-documentation/errata/097.html)). The [2013 same-sex married-couple user note](https://www.census.gov/programs-surveys/acs/technical-documentation/user-notes/2013-03.html) is a marital/family concept break. Exact bytes/correction status and observation versus release date remain bound/O6 decisions. | | CPS ASEC | Census, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)* or *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: the cited Redesigned layout has demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian noninstitutional universe plus Armed Forces members living in civilian housing; grouped entry years; survey-date demographics versus prior-calendar-year income. Traditional and Redesign files must never be silently combined. | | SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves do not represent newly arrived immigrant-only households, although new co-residents of original sample people can enter. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | @@ -848,6 +854,10 @@ the holdout, CPS/SIPP statistic, current Trustees assumption, or Census projecti may affect the fit. The 2010–2014 5-year PUMS is prohibited from both fitting and truth: its five-year weights represent/rerake to the pooled period, so slicing it by survey year would neither recover annual truth nor preserve the leakage fence. +The 2013 same-sex married-couple edit change is frozen in the per-year concept +map. Marital/family cells must harmonize to a definition stable across all five +annual files or be demoted before the truth floor; a dictionary crosswalk alone is +not evidence of longitudinal concept invariance. The annual files are observations at or before `T*`, but at least the 2014 file was released after its observation year. Decision O6 must ratify an observation- @@ -1039,6 +1049,8 @@ group-quarters counts. It must hard-fail on a 5-year pooled input. It must use `reported_year_of_entry`: the intended interviewer concept is most recent entry, while unclarified/self responses may mean first or most recent entry. `first_entry_year` is prohibited without another source. +The concept-map manifest must also name the 2013 same-sex married-couple edit +break and its common-definition harmonization or explicit report-only demotion. The Census parser must preserve its July-to-June event year and resident- population universe. A calendar-year bridge to Trustees may be displayed only as @@ -1082,7 +1094,8 @@ persons. The builder may not use age `-1` or a hidden donor-age shift. Ratify the proposed 0–4-year **reported-entry** window or a different duration; decide whether duration-zero/one donors receive priority; and freeze age/source/ -education/family matching cells and their fallback order. Repeat-entry +education/family matching cells, annual pooling/replicate-block treatment, +same-sex-marriage concept harmonization, and fallback order. Repeat-entry identification and prior U.S. coverage belong to O12. ### O4. Person versus co-arrival-family units and weights — hardest @@ -1296,8 +1309,9 @@ excluded. evidence and 2014 ACS Subject Definitions “Year of Entry,” pp. 128–129; Census 2014 Traditional and Redesigned ASEC technical documentation; Census 2014 SIPP Wave 1 metadata and source/accuracy statement. The five-year ACS file is - excluded from the gate; the exact SIPP raw file remains unbound at O8. Exact - variables and pages are pinned in §2.2 and §6.2. + excluded from the gate; ACS errata 87/97 and the 2013 same-sex married-couple + user note are manifest inputs; the exact SIPP raw file remains unbound at O8. + Exact variables and pages are pinned in §2.2 and §6.2. - **Projection corridors**: Census, *Methodology, Assumptions, and Inputs for the 2023 National Population Projections* (November 2023), migration pp. 8–14, and Table 1 in the Main Series and each Alternative Scenario. From e0a2772466b8c4acc3376440d412d4f18c8ae200 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 18:18:51 -0400 Subject: [PATCH 12/18] Synchronize annual sources in design manifest Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 75 +++++++++++++++++++++++++------ 1 file changed, 61 insertions(+), 14 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 840743d4..f81903d5 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -1321,7 +1321,7 @@ excluded. ```json immigration-design-parameters { "design_id": "2026-07-15-immigration-module", - "revision": 2, + "revision": 3, "status": "design_draft_referee_pending", "engine_baseline": "75d30dd57d71b91ee0929246b2f3cbb92263b350", "roadmap_issue": 113, @@ -1330,6 +1330,7 @@ excluded. "information_boundaries": { "inherited_m6_T_star": 2014, "trustees_2026_role": "versioned forward assumption and report-only alignment; never gate-estimation evidence", + "annual_acs_gate_role": "annual 1-year PUMS observations 2010-2014 only; post-observation release-date rule pending O6; five-year PUMS prohibited", "realized_post_T_star_nawi_on_scored_path": "prohibited" }, "entry_seam": { @@ -1337,6 +1338,7 @@ excluded. "definition_pin": "src/populace_dynamics/engine/loop.py:27", "contract_pin": "src/populace_dynamics/engine/loop.py:192-257", "frame_year": "entry_year - 1", + "first_entry_year": "strictly greater than start_year; origin and first cohort pending O15", "activation": "top of period before mortality", "new_period_module": false, "ids_preassigned": true, @@ -1345,10 +1347,12 @@ excluded. "caller_allocator_guard": "omit caller allocator or assert next_id exceeds the combined maximum" }, "provisional_adjudications": { - "cohort_control": "positive SSA stock-accounting inflow proxy after an explicit Social-Security-area-to-Census-resident bridge", + "cohort_control": "G_resident_entry_proxy for a resident-labeled bound run; raw G_ssa_stock only for an explicitly report-only ssa_area_proxy", + "projection_origin": "existing 2014 initial slice plus 2015-2100 Table V.A2 path is recommended only for the separate report-only M6 integration run; O15 remains open", + "entry_timing": "component-aware exposure bridge required; year-end-stayer inflow may not receive a second unadjusted source-year mortality filter", "status_adjustment": "aggregate reclassification; not an entrant and not assigned to persons", "emigration": "outside entry-builder v1; mandatory successor before net-alignment claim", - "assignment": "recent-arrival ACS joint resident-stock donor units plus model-based calibration; literal arrival state requires a separate bound bridge; no cloned future", + "assignment": "annual 2010-2014 ACS 1-year joint resident-stock donor units plus model-based calibration; literal arrival state requires a separate bound bridge; no cloned future", "prior_us_covered_earnings": "unknown/censored absent a first-or-return-entry and coverage bridge; never default zero", "entrant_fertility": "excluded from fertility risk absent a bound parity/history bridge and entrant-aware kernel", "entrant_claiming": "excluded absent insured-status and prior-coverage evidence", @@ -1359,11 +1363,11 @@ excluded. }, "external_bindings": [ { - "id": "ssa_tr2026_v_a2_intermediate", + "id": "ssa_tr2026_v_a2_components", "source": "The 2026 Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds, section V.A.3, and Supplemental Single-Year Table V.A2", "vintage": "assumptions set February 2026; report released June 9, 2026", - "role": "positive stock-accounting inflow control candidate and net reconciliation", - "status": "report_only_until_universe_bridge_and_exit_law" + "role": "historical/estimated 2015-2025 and intermediate 2026-2100 positive stock-accounting inflow control candidate plus net reconciliation", + "status": "report_only_until_origin_universe_timing_bridges_and_exit_law" }, { "id": "ssa_tr2026_v_a2_sensitivity", @@ -1380,11 +1384,25 @@ excluded. "status": "blocking_for_resident_alignment" }, { - "id": "acs_pums_2010_2014_recent_arrivals", - "source": "Census 2010-2014 ACS 5-year PUMS person file, dictionary, accuracy statement, and 2014 Subject Definitions", - "vintage": "observations 2010-2014; published January 2016", - "role": "resident survivor/stayer stock donor; fit 2010-2013 and hold out 2014", - "status": "proposed_gate_binding_pending_O6_not_arrival_truth" + "id": "projection_origin_population", + "source": "existing realized M6 2014 initial slice; alternative 2025 or 2026 resident baseline unbound", + "vintage": "2014 for recommended report-only integration path; alternatives unbound", + "role": "start year, population universe, first schedule key, and first-cohort disposition", + "status": "blocking_for_any_alternative_origin_pending_O15" + }, + { + "id": "entry_timing_exposure_bridge", + "source": "unbound component event/survival timing interpretation", + "vintage": "unbound", + "role": "translate source controls to entry-year mortality/aging exposure without duplicate survival filtering", + "status": "blocking_for_production_schedule_pending_O2" + }, + { + "id": "acs_pums_annual_2010_2014_recent_arrivals", + "source": "Census annual 1-year ACS PUMS person files, annual dictionaries and Accuracy statements for 2010-2014; 2014 Subject Definitions; errata 87/97; 2013 same-sex married-couple user note", + "vintage": "current 2010/2011 bytes 2013-03-04; 2012 2013-12-17; current 2013 bytes 2015-02-12; 2014 2015-10-27", + "role": "annual resident survivor/stayer stock donor; fit 2010-2013 and hold out separately weighted 2014", + "status": "proposed_gate_binding_pending_O6_not_arrival_truth_five_year_input_prohibited" }, { "id": "acs_stock_to_arrival_state_bridge", @@ -1393,6 +1411,27 @@ excluded. "role": "map interview-date stock proxy to literal arrival state, including duration, selection, reported-entry ambiguity, and repeat entry", "status": "blocking_for_literal_entry_state_pending_O12" }, + { + "id": "entrant_marital_household_history_initializer", + "source": "unbound annual ACS plus exact SIPP or another named history source", + "vintage": "unbound", + "role": "entry marital/household history, roster-safe relations, exposure start, and entrant-only law", + "status": "blocking_for_marital_household_domains_pending_O4_O5_O14" + }, + { + "id": "entrant_disability_state_bridge", + "source": "unbound ACS/SIPP concept-to-module mapping and forward law", + "vintage": "unbound", + "role": "entrant disability initialization and transitions", + "status": "blocking_for_entrant_disability_pending_O5_and_successor_gate" + }, + { + "id": "entrant_earnings_initializer_forward_law", + "source": "unbound annual ACS and exact SIPP current-spell/history evidence", + "vintage": "unbound", + "role": "partial-year entry state, lags/persistence, and entrant-only future earnings", + "status": "blocking_for_entrant_earnings_and_downstream_benefits_pending_O5_O12" + }, { "id": "cps_asec_2014_foreign_born", "source": "Census 2014 ASEC public-use file and technical documentation", @@ -1423,7 +1462,7 @@ excluded. }, { "id": "census_np2023_nim_corridors", - "source": "Census 2023 National Population Projections, Alternative Scenarios Table 1", + "source": "Census 2023 National Population Projections, Table 1 in the Main Series and each Alternative Scenario", "vintage": "November 2023", "role": "main/high/low/zero net-international-migration corridors", "status": "report_only" @@ -1445,9 +1484,15 @@ excluded. ], "gate_imm": { "exists_now": false, - "estimand": "held-out ACS recent-arrival resident-stock characteristic reproduction", + "estimand": "held-out annual ACS 1-year recent-arrival resident-stock proxy characteristic reproduction", + "raw_input": "five separately bound annual 1-year PUMS files; five-year pooled PUMS prohibited", "fit_collection_years": [2010, 2011, 2012, 2013], "holdout_collection_years": [2014], + "unit_key": ["survey_year", "SERIALNO"], + "annual_pooling_rule": "freeze equal-year-mass versus population-mass treatment from training only", + "replicate_design": "year-specific blocks; annual 2014 truth uses only its own replicate set", + "cross_year_earnings_normalization": "ADJINC to survey-year dollars then I_proj[2014] / I_proj[survey_year]", + "concept_breaks": "bind and harmonize or demote the 2013 same-sex married-couple edit change", "count_alignment_gated": false, "physical_sample_design_frozen_from_training_power_analysis": true, "schedule_seed_grid_and_aggregation_frozen_before_truth_floor": true, @@ -1457,7 +1502,7 @@ excluded. "downstream_life_course_certified": false }, "hardest_open_decisions": [ - "O1: positive SSA stock-accounting inflow proxy plus separate exits versus an expanded entry-and-exit design or named net-entry proxy", + "O1/O2/O11/O15: literal flow versus net proxy, component timing, population-universe bridge, projection origin, and first cohort", "O5/O12/O13: atomic downstream packet, stock-to-arrival and repeat-coverage bridges, and fertility/claiming exclusions", "O4/O14: person versus co-arrival-family units, relationship and weight closure, and RNG-isolated cross-domain markets" ], @@ -1466,6 +1511,8 @@ excluded. "candidate-16 marital core", "candidate-9 household composition object", "M4 disability reproduction object", + "existing age-sex mortality fit", + "frozen claiming schedule estimated through 2014", "certified earnings specifications and section 2.8.3a domain", "section 2.8.2g marital domain law", "amendment 3h live-roster materialization law", From 847147e1dab7952fc2bac3e0da06a6622e5bf391 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 18:19:20 -0400 Subject: [PATCH 13/18] Record annual-gate correction in amendment history Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index f81903d5..4460233c 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -28,7 +28,7 @@ claiming, flow-to-stock, and stock-to-arrival blockers; composes immigrant IDs with the existing 2017/2019 schedule; guards caller-supplied allocators; and requires entrant RNG isolation before any byte-identity claim → §2.2–2.4, - §3.1–3.4, §4.1–4.11, §5, §6, O2/O5/O8–O15. + §3.1–3.4, §4.1–4.11, §5, §6, O2/O5/O8–O14. - Dormant-generator finding: the engine already owns an entrant seam, but there is no immigration schedule generator → §3.1, §4. - Net-is-not-entry finding: the 2026 Trustees component table distinguishes @@ -1548,6 +1548,21 @@ excluded. "require RNG-isolated composite adapters before any original-person byte-identity claim", "expand referee decisions through O14 and pin unresolved external bindings" ] + }, + { + "revision": 3, + "date": "2026-07-15", + "kind": "annual_gate_and_origin_correction", + "changes": [ + "replace invalid collection-year slicing of five-year ACS PUMS with separately bound annual 1-year files and weights", + "namespace donor units by survey year and SERIALNO and block annual replicate designs by year", + "bind annual archive corrections, the 2013 marital concept break, and explicit 2010-2014 earnings normalization", + "make raw SSA-area versus bridged resident calibration targets conditional and auditable", + "add component-aware entry timing so year-end-stayer controls cannot receive duplicate source-year survival filtering", + "add projection-origin decision O15 and require continuous controls from start_year plus one", + "add blocking marital-household, disability, and earnings initializer bindings", + "synchronize the machine-readable binding list and preserve mortality and claiming among untouched surfaces" + ] } ] } From bf2c81e8b5844bc5313900f9e3b9039e943870dc Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 18:21:11 -0400 Subject: [PATCH 14/18] Tighten observed-unit and wage-index labels Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 34 ++++++++++++++++--------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 4460233c..d46be33c 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -574,7 +574,8 @@ values. PENSIM2's family sampling exposes a real unit mismatch: the external control is people, while the state to preserve may be a family. V1's provisional unit is a -**co-resident co-arrival unit**, not a claimed historical travel party: +**constructed co-resident same-reported-entry unit**, not a claimed historical +travel party: 1. Start with an annual PUMS household (`survey_year, SERIALNO`). 2. Select foreign-born recent-arrival people with the same reported-year-of-entry @@ -622,12 +623,13 @@ These are **interview-date stock characteristics**. They become entry-time characteristics only after the `ArrivalStateBridge`; an identity bridge must be named `stock_proxy` and is report-only. -The default matching ladder begins with sex × broad age-at-entry × source region -and then uses education and family state when support permits, consistent with -the MINT/Duleep-Dowhan precedent. The precise cells are selected and frozen -before candidate scoring. Fallbacks coarsen in a published order; they never -cross a prohibited concept boundary merely to fill a cohort. Every fallback -count appears in the audit. +The stock-proxy matching ladder begins with sex × broad derived reported-entry- +age proxy × source region and then uses education and family state when support +permits, consistent with the MINT/Duleep-Dowhan precedent. A bound +`ArrivalStateBridge` may instead emit literal arrival age under its own label. +The precise cells are selected and frozen before candidate scoring. Fallbacks +coarsen in a published order; they never cross a prohibited concept boundary +merely to fill a cohort. Every fallback count appears in the audit. Long-run composition is held at the donor artifact's calibrated distribution unless a separately sourced, gate-reviewed composition trajectory is bound. @@ -1023,7 +1025,7 @@ until an acquisition PR records the actual bytes. | `entrant_fertility_history_bridge` | **UNBOUND.** Candidate evidence must name exact SIPP fertility-history or CPS fertility-supplement files, variables, universe, observation years and release vintage. | Map prior parity/birth history and exposure start jointly with entrant family state; never default parity to zero. | **BLOCKING** for entrant fertility risk; decision O13. | | `prior_us_covered_earnings_bridge` | **UNBOUND.** ACS reported year of entry and public survey earnings do not establish first entry or prior U.S. Social Security covered earnings. | Identify repeat-entry/first-entry status, covered quarters and prior indexed earnings with a source, universe and vintage; otherwise retain censored/unknown. | **BLOCKING** for entrant insured status, claiming, AIME/PIA and benefits; decision O12. | | `census_np2023_nim_corridors` | Census Bureau, *[Methodology, Assumptions, and Inputs for the 2023 National Population Projections](https://www2.census.gov/programs-surveys/popproj/technical-documentation/methodology/methodstatement23.pdf)* (Nov. 2023), migration pp. 8–14; Table 1 in the Main Series and each Alternative Scenario, “Projected Population and Components of Change for the United States, [Main Series/High Immigration Scenario/Low Immigration Scenario/Zero Immigration Scenario]: 2022–2100”: [main](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1.xlsx), [high](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-h.xlsx), [low](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-l.xlsx), and [zero](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-z.xlsx) workbooks. | Annual net international migration in thousands for main/high/low/zero scenarios; July 1 prior year–June 30 current year. Preserve scenario definitions: alternatives change gross foreign-born immigration, not every migration component. | Report-only cross-model corridors; never gate truth or a positive entrant control. | -| `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: realized SSA NAWI through 2014 and `I_proj` beyond, estimated only from `<=T*`; see `m6_projection_engine.md:666-708,1723-1756`. | Annual-file `ADJINC` first expresses income in that survey year's dollars. Before cross-year training/holdout comparison bind `earnings_2014 = earnings_y_after_ADJINC * I_proj[2014] / I_proj[y]`; projection-year entrant earnings reverse the ratio from the 2014 base. Never use realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | +| `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: `I_bound[y]` is realized SSA NAWI through 2014 and `I_proj[y]` beyond, estimated only from `<=T*`; see `m6_projection_engine.md:666-708,1723-1756`. | Annual-file `ADJINC` first expresses income in that survey year's dollars. Before cross-year training/holdout comparison bind `earnings_2014 = earnings_y_after_ADJINC * I_bound[2014] / I_bound[y]`; projection-year entrant earnings reverse the ratio from the 2014 base. Never use realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | | `emigration_duration_hazard` | **UNBOUND.** Table V.A2 supplies aggregate outflow counts only. The Duleep-Dowhan 2008 hazards and legacy model methods are research evidence, not a current operational binding. | Must identify age, sex, source grouping, time since entry, family/individual unit, re-entry treatment, universe and vintage. | **BLOCKING** for explicit exits and any Trustees net-alignment claim; outside entry-builder v1. | ### 6.3 Binding-specific guards @@ -1098,13 +1100,13 @@ education/family matching cells, annual pooling/replicate-block treatment, same-sex-marriage concept harmonization, and fallback order. Repeat-entry identification and prior U.S. coverage belong to O12. -### O4. Person versus co-arrival-family units and weights — hardest +### O4. Person versus constructed same-reported-entry units — hardest -Choose person donors, co-resident co-arrival units, or a mixed rule. If units are -chosen, bind relationship closure, common versus person-specific simulation -weights, calibration to person totals, partial families, group quarters, and -whether later exits occur by person or unit. This decision sets the correlation -unit for floors. +Choose person donors, constructed co-resident same-reported-entry units, or a +mixed rule. If units are chosen, bind relationship closure, common versus person- +specific simulation weights, calibration to person totals, partial families, +group quarters, and whether later exits occur by person or unit. This decision +sets the correlation unit for floors; it never identifies a travel party. ### O5. Atomic state/history packet and post-entry laws — hardest @@ -1491,7 +1493,7 @@ excluded. "unit_key": ["survey_year", "SERIALNO"], "annual_pooling_rule": "freeze equal-year-mass versus population-mass treatment from training only", "replicate_design": "year-specific blocks; annual 2014 truth uses only its own replicate set", - "cross_year_earnings_normalization": "ADJINC to survey-year dollars then I_proj[2014] / I_proj[survey_year]", + "cross_year_earnings_normalization": "ADJINC to survey-year dollars then I_bound[2014] / I_bound[survey_year], where I_bound is realized NAWI through 2014 and I_proj thereafter", "concept_breaks": "bind and harmonize or demote the 2013 same-sex married-couple edit change", "count_alignment_gated": false, "physical_sample_design_frozen_from_training_power_analysis": true, @@ -1504,7 +1506,7 @@ excluded. "hardest_open_decisions": [ "O1/O2/O11/O15: literal flow versus net proxy, component timing, population-universe bridge, projection origin, and first cohort", "O5/O12/O13: atomic downstream packet, stock-to-arrival and repeat-coverage bridges, and fertility/claiming exclusions", - "O4/O14: person versus co-arrival-family units, relationship and weight closure, and RNG-isolated cross-domain markets" + "O4/O14: person versus constructed same-reported-entry units, relationship and weight closure, and RNG-isolated cross-domain markets" ], "certified_surfaces_untouched": [ "gate_m6 registry, thresholds, floors, hashes, and closed-panel support", From 4d4d5c8287fa9f9b2dbd21ee68acf5e9c23bce84 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 19:28:01 -0400 Subject: [PATCH 15/18] docs: reserve global immigrant ID namespace Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 136 ++++++++++++++++++++++-------- 1 file changed, 99 insertions(+), 37 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index d46be33c..09440ce1 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -39,6 +39,11 @@ - Certificate-boundary finding: §2.8.3a, §2.8.2g, and amendment 3h prohibit repairing an unsupported universe by fabricating state or bypassing a live- roster guard → §3.3–3.5, §5.6. +- Global-ID-namespace finding: the run-local engine allocator can alias an + omitted person retained by a global fitted surface; adopt the pending + [PR #221](https://github.com/PolicyEngine/populace-dynamics/pull/221) + §2.8.2i F2 law and assert entrant/domain disjointness before projection → + §3.1–3.2, §3.5, §4.6–4.7, §4.11. - Donor-support finding: MINT's sparse annual cohorts and the public surveys' different universes require floors before any accuracy threshold → §2.1–2.3, §5.3. @@ -324,9 +329,34 @@ entry mechanism. The immigration builder must **compose with**, not replace, that existing mapping. For each shared year it schema-reconciles and concatenates the unchanged PSID opener frame with the immigrant frame, then validates one prior-year coordinate -and global ID uniqueness. It allocates immigrant IDs above the maximum of the -initial IDs **and every pre-existing scheduled ID**. Because all new IDs are above -that union, existing-person and existing-opener sorted ordinals remain unchanged. +and global ID uniqueness. + +The current loop's maximum is run-local and is not a sufficient immigrant-ID +floor. Pending M6 amendment +[PR #221](https://github.com/PolicyEngine/populace-dynamics/pull/221), +§2.8.2i **F2**, proves that a synthetic ID can otherwise alias a real person +omitted from a selected run but retained by a global fitted adapter. This design +adopts that pending law as an implementation dependency even though PR #221 has +not merged. Before any gate split or other subsetting, construct and freeze +`reserved_real_person_ids` as the union of the full anchor and every person-keyed +fitted support consumed by assembly. At minimum this includes the keys of both +earnings fitted-state maps (and therefore every `adapter.domain_person_ids` +member), marital attributes, household attributes/person waves, and disability- +panel person keys. Let `preexisting_schedule_ids` contain every PSID opener ID and +define + +```text +immigrant_id_floor = 1 + max( + reserved_real_person_ids union preexisting_schedule_ids +) +``` + +Freeze that floor unchanged through every subset operation and allocate immigrant +IDs from it in deterministic order. Because the floor also exceeds every +pre-existing scheduled ID, existing-person and existing-opener sorted ordinals +remain unchanged. A different high namespace is admissible only if its manifest +proves it disjoint from the same complete reserved union; a side-local maximum is +never admissible. ### 3.2 Consequences for timing, IDs, and RNG @@ -356,13 +386,20 @@ the cohort control/exposure convention, but it may not assign a Trustees stock o legal-status label to individual donor rows. IDs are assigned outside the loop in deterministic order. They must be finite -integers, greater than every starting-population **or pre-existing scheduled** ID, -collision-free across all years, and invariant to row order. These conditions -preserve every original and PSID-opener sorted-ID ordinal. Projection metadata -must omit a pre-supplied synthetic allocator, or assert its mutable `next_id` is -strictly above the combined maximum before period 1; otherwise the loop does not -protect births from collision. No existing M6 module stream is consumed to -construct the schedule. +integers, begin at the frozen global `immigrant_id_floor`, be collision-free +across all years, and be invariant to row order. The floor, not a recomputed +selected-side maximum, is carried into every subset/diagnostic run. Projection +metadata must omit a pre-supplied synthetic allocator, or assert its mutable +`next_id` is strictly above every reserved real-person and scheduled-person ID +before period 1; otherwise the loop does not protect births from collision. + +Any run claiming full-population/original-person byte identity must additionally +check the precondition +`run_real_person_ids ⊇ fitted_support_person_ids`, where the +run universe includes its initial real people and every real scheduled opener. +A subset run normally fails that precondition and may not inherit the claim; the +global namespace reservation still makes its synthetic IDs collision-safe. No +existing M6 module stream is consumed to construct the schedule. ### 3.3 Amendment 3h / M6 §2.8.2h: live-roster materialization @@ -418,9 +455,9 @@ Therefore the immigration generator must produce both an entry row and an explicit, module-native **EntrantStateBundle**. Merely adding more columns to the entry frame is rejected. -### 3.5 The §2.8.3a / §2.8.2g / 3h domain-law family +### 3.5 The §2.8.3a / §2.8.2g / 3h / pending-3i domain-law family -The sibling M6 design's three laws bind this module: +The sibling M6 domain laws bind this module: - **Earnings §2.8.3a**: the certified forward generator's domain is the intersection with realized 2014 earnings state. Missing/new rows are false in @@ -436,6 +473,12 @@ The sibling M6 design's three laws bind this module: scoring schedule from live-roster materialization; a child may materialize only against a live mother. The broader relationship-closure rule in §3.3 is a new immigration invariant, not part of the 3h certificate. +- **Synthetic IDs, pending §2.8.2i F2**: PR #221 reserves the global real-person + namespace before any gate split and requires every allocated ID to be disjoint + from it. This design applies the same law to immigrant cohorts and then places + the dynamic birth allocator above the complete real-plus-scheduled universe. + Until PR #221 lands, an integration must implement the equivalent explicit + floor; relying on the current run-local default is prohibited. No existing certificate transfers across these bridges. Reuse of unchanged core code may be plumbing at implementation time, but applying it to an entrant @@ -651,12 +694,12 @@ any stochastic calibration use named `purpose_tag` values so adding one draw doe not shift another purpose's addresses. After the full schedule is realized, IDs are allocated in stable order -`(entry_year, unit_slot, member_slot)` beginning above the maximum `person_id` -across the initial population **and the full pre-existing schedule**. The builder -stores the allocation ledger, merges same-year frames without changing their -existing rows, and verifies global uniqueness before calling the engine. -Arrival-unit and household IDs use their own namespaces and may not alias person -IDs. +`(entry_year, unit_slot, member_slot)` beginning at the pre-split global +`immigrant_id_floor` from §3.1. The builder stores the reserved-set digest, floor, +and allocation ledger, merges same-year frames without changing their existing +rows, and verifies global uniqueness and reserved-set disjointness before calling +the engine. Arrival-unit and household IDs use their own namespaces and may not +alias person IDs. The metadata adapter omits `synthetic_id_allocator` so the loop creates it from the combined universe. If another caller requires a supplied allocator, the @@ -665,11 +708,12 @@ the loop's type check alone is insufficient. Changing a source vintage, donor artifact, recent-arrival definition, or schedule seed creates a new schedule identity. The design does not promise entrant or -newborn byte identity across such scenarios. It does promise that, within one -schedule, pre-supplying entrant IDs above the initial maximum leaves every -original person's sorted-ID ordinal unchanged and lets the engine place its -dynamic allocator above every scheduled entrant only under the preceding -metadata guard. +newborn byte identity across such scenarios. Within one schedule, the global +floor leaves every original and pre-existing-opener sorted-ID ordinal unchanged, +and the metadata guard places the dynamic allocator above every scheduled +entrant. A full-population byte-identity claim also requires the checked +`run_real_person_ids ⊇ fitted_support_person_ids` precondition in §3.2; stable +ordinals alone never confer that claim on a subset run. Downstream RNG needs a separate isolation law. C16, fertility, and candidate-9 consume shared ordered generators, so merely adding entrants to their panels can @@ -702,8 +746,15 @@ Before engine invocation the builder hard-checks: - mapping keys are integer entry years in the projection range; - each frame has exactly `year = entry_year - 1`; - pre/post-aging age identities match decision O2; -- person IDs are finite integers, globally unique, and greater than the initial - and every pre-existing scheduled maximum; +- person IDs are finite integers, globally unique, start no lower than the frozen + `immigrant_id_floor`, and are disjoint from `reserved_real_person_ids` and every + pre-existing scheduled ID; +- for every active certified earnings adapter, the literal assertion + `immigrant_ids ∩ adapter.domain_person_ids == ∅` holds; the + `earnings_domain = false` marker is not a bypass for fitted membership; +- the pre-split namespace floor is unchanged after every gate/subset operation, + and any full-population byte-identity claim separately satisfies + `run_real_person_ids ⊇ fitted_support_person_ids`; - all relation endpoints are either scheduled no later than the relation's materialization year or explicitly marked outside-roster; - weights are finite, positive, and reconcile at person and unit level; @@ -803,17 +854,21 @@ characteristic claims, or M7 accounting. Every build writes a machine-readable audit before projection. The audit includes source and derived hashes, retrieval/publication/observation dates, parser and -schema versions, schedule seed, ID ranges, per-year physical rows and weighted -totals, donor-cell effective sample sizes, fallback counts, calibration residuals, +schema versions, schedule seed, the reserved-real-ID-set digest, frozen immigrant +floor and allocated ID ranges, per-year physical rows and weighted totals, +donor-cell effective sample sizes, fallback counts, calibration residuals, top-code/allocation shares, unit-size distribution, state-bundle completeness, and all report-only/certified labels. The builder refuses to run when a binding required by the selected run is missing or mutable, a raw or derived hash differs, a required year is absent, a unit -crosses an unsupported concept, an outside-roster relation is assigned an ID, an -entry is accidentally admitted to the certified earnings domain, or the universe -bridge is absent for a run claiming resident alignment. Network access and runtime -redownload are prohibited on a scored or production run. +crosses an unsupported concept, an outside-roster relation is assigned an ID, the +namespace floor changes after a split, or either +`immigrant_ids ∩ reserved_real_person_ids` or +`immigrant_ids ∩ adapter.domain_person_ids` is nonempty. It also refuses a +full-population byte-identity claim when the §3.2 run-universe precondition fails, +or a resident-alignment claim when the universe bridge is absent. Network access +and runtime redownload are prohibited on a scored or production run. ## 5. Evaluation and proposed `gate_imm` @@ -1025,7 +1080,7 @@ until an acquisition PR records the actual bytes. | `entrant_fertility_history_bridge` | **UNBOUND.** Candidate evidence must name exact SIPP fertility-history or CPS fertility-supplement files, variables, universe, observation years and release vintage. | Map prior parity/birth history and exposure start jointly with entrant family state; never default parity to zero. | **BLOCKING** for entrant fertility risk; decision O13. | | `prior_us_covered_earnings_bridge` | **UNBOUND.** ACS reported year of entry and public survey earnings do not establish first entry or prior U.S. Social Security covered earnings. | Identify repeat-entry/first-entry status, covered quarters and prior indexed earnings with a source, universe and vintage; otherwise retain censored/unknown. | **BLOCKING** for entrant insured status, claiming, AIME/PIA and benefits; decision O12. | | `census_np2023_nim_corridors` | Census Bureau, *[Methodology, Assumptions, and Inputs for the 2023 National Population Projections](https://www2.census.gov/programs-surveys/popproj/technical-documentation/methodology/methodstatement23.pdf)* (Nov. 2023), migration pp. 8–14; Table 1 in the Main Series and each Alternative Scenario, “Projected Population and Components of Change for the United States, [Main Series/High Immigration Scenario/Low Immigration Scenario/Zero Immigration Scenario]: 2022–2100”: [main](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1.xlsx), [high](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-h.xlsx), [low](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-l.xlsx), and [zero](https://www2.census.gov/programs-surveys/popproj/tables/2023/2023-summary-tables/np2023-t1-z.xlsx) workbooks. | Annual net international migration in thousands for main/high/low/zero scenarios; July 1 prior year–June 30 current year. Preserve scenario definitions: alternatives change gross foreign-born immigration, not every migration component. | Report-only cross-model corridors; never gate truth or a positive entrant control. | -| `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: `I_bound[y]` is realized SSA NAWI through 2014 and `I_proj[y]` beyond, estimated only from `<=T*`; see `m6_projection_engine.md:666-708,1723-1756`. | Annual-file `ADJINC` first expresses income in that survey year's dollars. Before cross-year training/holdout comparison bind `earnings_2014 = earnings_y_after_ADJINC * I_bound[2014] / I_bound[y]`; projection-year entrant earnings reverse the ratio from the 2014 base. Never use realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | +| `m6_projected_wage_index` | Existing sibling design §2.7.6.3/§2.8.10: `I_bound[y]` is realized SSA NAWI through 2014 and `I_proj[y]` beyond, estimated only from `<=T*`; re-derived against merged master `c6a3c78` at `m6_projection_engine.md:694-725,2041-2103`. | Annual-file `ADJINC` first expresses income in that survey year's dollars. Before cross-year training/holdout comparison bind `earnings_2014 = earnings_y_after_ADJINC * I_bound[2014] / I_bound[y]`; projection-year entrant earnings reverse the ratio from the 2014 base. Never use realized post-2014 NAWI on a scored path. | Reused by a future entrant-earnings initializer. No new external fetch and no certificate transfer to entrant earnings. | | `emigration_duration_hazard` | **UNBOUND.** Table V.A2 supplies aggregate outflow counts only. The Duleep-Dowhan 2008 hazards and legacy model methods are research evidence, not a current operational binding. | Must identify age, sex, source grouping, time since entry, family/individual unit, re-entry treatment, universe and vintage. | **BLOCKING** for explicit exits and any Trustees net-alignment claim; outside entry-builder v1. | ### 6.3 Binding-specific guards @@ -1236,7 +1291,9 @@ authorizes surgery: 2017/2019 PSID opener row; the immigration builder merges that mapping and never overwrites it; - the eight-member `PeriodModules` order, existing module RNG streams, original- - person ordinals, synthetic-ID allocator semantics, and period trace; + person ordinals, and period trace; synthetic-ID allocation follows pending + PR #221 §2.8.2i F2, or an immigration-side equivalent, rather than the current + side-local default; - M6's current statement that immigrant/open-panel additions are report-only; - M7 trust-fund accounting, M8 rules execution, and any PolicyEngine-US legal eligibility rule; and @@ -1245,8 +1302,9 @@ authorizes surgery: An entrant adapter may call unchanged core code, but it must do so under an entrant-domain label and separate report/gate surface. It may not alter the closed-panel input or score and call the resulting difference “immigration.” -The metadata adapter also must omit a caller allocator or enforce the combined- -maximum guard in §4.6. Any mixed entrant/existing-person market remains the +The metadata adapter also must carry the pre-split global floor and omit a caller +allocator or enforce the complete reserved-plus-scheduled guard in §4.6. Any +mixed entrant/existing-person market remains the report-only O14 product and makes no closed-run byte-identity claim. ## 9. Candidate-blind implementation and certification order @@ -1345,8 +1403,12 @@ excluded. "new_period_module": false, "ids_preassigned": true, "synthetic_allocator_start": "engine default is max(initial and all scheduled person_id) + 1 when caller metadata omits the allocator", - "existing_schedule_merge": "preserve and concatenate every PSID opener frame; allocate immigrants above max(initial plus all pre-existing scheduled ids)", - "caller_allocator_guard": "omit caller allocator or assert next_id exceeds the combined maximum" + "reserved_real_person_namespace": "freeze before any split as full anchor union every person-keyed fitted support, including both earnings maps, marital attrs, household person keys, and disability-panel person keys", + "immigrant_id_floor": "1 + max(reserved_real_person_ids union every pre-existing scheduled person_id); preserve unchanged through subsets", + "existing_schedule_merge": "preserve and concatenate every PSID opener frame; allocate immigrants at or above the global immigrant_id_floor", + "domain_disjoint_assertion": "immigrant_ids intersect adapter.domain_person_ids is empty for every active earnings adapter before period 1", + "byte_identity_precondition": "a full-population/original-person byte-identity claim requires checked run_real_person_ids superset fitted_support_person_ids; subset runs do not inherit the claim", + "caller_allocator_guard": "omit caller allocator or assert next_id exceeds the reserved real-person namespace and every scheduled person_id" }, "provisional_adjudications": { "cohort_control": "G_resident_entry_proxy for a resident-labeled bound run; raw G_ssa_stock only for an explicitly report-only ssa_area_proxy", From df507ca6f58ae07d4102172a78310f1be14793f7 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 19:29:38 -0400 Subject: [PATCH 16/18] docs: classify immigrant runner entrants Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 65 +++++++++++++++++++++++++------ 1 file changed, 53 insertions(+), 12 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 09440ce1..b5cdcb0c 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -44,6 +44,10 @@ [PR #221](https://github.com/PolicyEngine/populace-dynamics/pull/221) §2.8.2i F2 law and assert entrant/domain disjointness before projection → §3.1–3.2, §3.5, §4.6–4.7, §4.11. +- Runner-reporting invalidation finding: the closed-panel entrant report hardcodes + zero immigrants and counts the whole schedule as realized openers; require + row-level `entry_kind` classification in the open-run integration → §3.1, + §4.7, §5.6, §9.1. - Donor-support finding: MINT's sparse annual cohorts and the public surveys' different universes require floors before any accuracy threshold → §2.1–2.3, §5.3. @@ -327,9 +331,12 @@ already publishes later PSID openers through the same key entry mechanism. The immigration builder must **compose with**, not replace, that existing mapping. -For each shared year it schema-reconciles and concatenates the unchanged PSID -opener frame with the immigrant frame, then validates one prior-year coordinate -and global ID uniqueness. +For each shared year it schema-reconciles and concatenates a value/ID-preserving +copy of the PSID opener frame with the immigrant frame, then validates one prior- +year coordinate and global ID uniqueness. The composed copy adds and validates +the reporting discriminator `entry_kind = "psid_realized_opener"`; immigrant +frames carry `entry_kind = "immigration"`. This annotation does not mutate the +source opener mapping or alter any pre-existing opener value or ID. The current loop's maximum is run-local and is not a sufficient immigrant-ID floor. Pending M6 amendment @@ -410,12 +417,14 @@ to master as forensic source is the [3h forensics/adjudication](https://github.com/PolicyEngine/populace-dynamics/issues/42#issuecomment-4984997277) and the merged M6 §2.8.2h text. This sibling design adopts that law as a -dependency while retaining the stated baseline for every code pin: +dependency while retaining the stated baseline for every code pin. The following +is a faithful paraphrase, not a verbatim quotation: -> A scheduled maternal birth may materialize a child only when the mother is -> present in the live post-mortality roster. The frame-independent risk schedule -> may remain the scoring universe; absent-mother events are dropped after the draw -> and reconciled report-only so RNG addresses do not shift. +> **Paraphrase of merged M6 §2.8.2h:** A scheduled maternal birth may materialize +> a child only when the mother is present in the live post-mortality roster. The +> frame-independent risk schedule may remain the scoring universe; absent-mother +> events are dropped after the draw and reconciled report-only so RNG addresses +> do not shift. Entrants are roster-present when their own rows are activated, and their later maternal births obey this exact 3h law. V1 separately proposes a broader @@ -741,6 +750,14 @@ Every scheduled entry frame contains these conceptual groups: No `legal_status` field is inferred. A source-stock component from Table V.A2 may be retained only at aggregate manifest level; it is not assigned to a person. +Every row in the **composed schedule copy** has an explicit `entry_kind` before +reporting: `"immigration"` for this module and `"psid_realized_opener"` for the +pre-existing opener frames. The open-run report partitions counts from that field. +It counts materialized maternal births from their explicit birth provenance (or +from the dynamic-allocation ledger after excluding every scheduled ID), never by +assuming that every non-initial or synthetic ID is a birth. The three classes are +mutually exclusive; total schedule size is not an opener counter. + Before engine invocation the builder hard-checks: - mapping keys are integer entry years in the projection range; @@ -1026,9 +1043,10 @@ died before interview, any post-entry transition, any interaction with the closed population, or any Social Security eligibility/benefit result. It also would not modify or extend the M6 certificate. Entrants remain family-B -open additions under `harness/m6_reporting.py:71-73` and its explicit immigrant -person-row bridge at `harness/m6_reporting.py:104-118` until a later ratified gate says -otherwise. +open additions under the limitation at `harness/m6_reporting.py:71-73`, the +explicit immigrant person-row bridge at `harness/m6_reporting.py:104-118`, and +the family-B ledger actually published by `build_entrant_diagnostics` at +`harness/m6_reporting.py:285-301`, until a later ratified gate says otherwise. ## 6. External bindings @@ -1309,6 +1327,28 @@ report-only O14 product and makes no closed-run byte-identity claim. ## 9. Candidate-blind implementation and certification order +### 9.1 Required integration patch pointers + +The eventual open-run integration must update the M6 runner surfaces that encode +closed-panel entrant assumptions. `harness/m6_runner.py:873-874,909-920` currently +treats every non-initial synthetic ID as a maternal birth, hardcodes +`"immigrant_cohorts": 0`, and sums every frame in the schedule mapping into +`scheduled_realized_openers`. Its fallback and family-B consumer repeat the zero +at `harness/m6_runner.py:1091-1106`. Those are mandatory patch surfaces when the +module lands; the closed-panel path may retain its current result. + +The open-run report must derive mutually exclusive counters from explicit +provenance: immigrant schedule rows where `entry_kind == "immigration"`, realized +PSID opener rows where `entry_kind == "psid_realized_opener"`, and dynamically +materialized births identified by birth provenance or the allocation ledger after +all scheduled IDs are removed. It must never infer opener count from the size of +the merged schedule, infer births from every non-initial ID, or inherit the +hardcoded zero-immigrant fallback. The resulting immigrant count feeds the +existing family-B publisher at `harness/m6_reporting.py:285-301` and remains +report-only. + +### 9.2 Ordered ceremony + A later implementation should proceed in this order: 1. Referee resolves O1–O15 for the chosen implementation slice and ratifies the @@ -1405,7 +1445,7 @@ excluded. "synthetic_allocator_start": "engine default is max(initial and all scheduled person_id) + 1 when caller metadata omits the allocator", "reserved_real_person_namespace": "freeze before any split as full anchor union every person-keyed fitted support, including both earnings maps, marital attrs, household person keys, and disability-panel person keys", "immigrant_id_floor": "1 + max(reserved_real_person_ids union every pre-existing scheduled person_id); preserve unchanged through subsets", - "existing_schedule_merge": "preserve and concatenate every PSID opener frame; allocate immigrants at or above the global immigrant_id_floor", + "existing_schedule_merge": "preserve every existing opener value and ID; tag the composed copy entry_kind=psid_realized_opener, concatenate immigration rows tagged entry_kind=immigration, and allocate immigrants at or above the global immigrant_id_floor", "domain_disjoint_assertion": "immigrant_ids intersect adapter.domain_person_ids is empty for every active earnings adapter before period 1", "byte_identity_precondition": "a full-population/original-person byte-identity claim requires checked run_real_person_ids superset fitted_support_person_ids; subset runs do not inherit the claim", "caller_allocator_guard": "omit caller allocator or assert next_id exceeds the reserved real-person namespace and every scheduled person_id" @@ -1421,6 +1461,7 @@ excluded. "entrant_fertility": "excluded from fertility risk absent a bound parity/history bridge and entrant-aware kernel", "entrant_claiming": "excluded absent insured-status and prior-coverage evidence", "rng_isolation": "required composite partition before any closed-person byte-identity claim", + "entrant_reporting": "open-run m6_runner counters partition schedule rows by entry_kind and births by explicit materialization provenance; whole-schedule opener counts and hardcoded zero immigrants are prohibited", "runtime": "schedule built once per scenario and reused across K engine draws", "legal_status_dynamics": "out of scope", "current_entry_only_outputs": "report_only" From 2ab06187e0b44ee03ea4c15394809d83460761d4 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 19:31:04 -0400 Subject: [PATCH 17/18] docs: correct ACS archive vintages Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 46 ++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index b5cdcb0c..104c15ad 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -48,6 +48,9 @@ zero immigrants and counts the whole schedule as realized openers; require row-level `entry_kind` classification in the open-run integration → §3.1, §4.7, §5.6, §9.1. +- External-metadata finding: correct the 2012/2014 ACS person-archive server + `Last-Modified` dates and mark mutable archive/glossary pins for confirmation + when bytes are hash-bound → §2.2, §2.4, §6.2, O6. - Donor-support finding: MINT's sparse annual cohorts and the public surveys' different universes require floors before any accuracy threshold → §2.1–2.3, §5.3. @@ -204,6 +207,14 @@ emigration cannot be ignored. | CPS ASEC | Census, *[2014 Traditional ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14.pdf)* or *[2014 Redesigned ASEC technical documentation](https://www2.census.gov/programs-surveys/cps/techdocs/cpsmar14R.pdf)*: the cited Redesigned layout has demographics p. 65; six disability items pp. 68–69; `PENATVTY`, grouped `PEINUSYR`, `PRCITSHP`, `MARSUPWT` p. 69; wage/salary and earnings pp. 77, 83. | Report-only marginal and earnings triangulation. | Smaller civilian noninstitutional universe plus Armed Forces members living in civilian housing; grouped entry years; survey-date demographics versus prior-calendar-year income. Traditional and Redesign files must never be silently combined. | | SIPP | Census, *[2014 SIPP Metadata, all sections v2](https://www2.census.gov/programs-surveys/sipp/tech-documentation/data-dictionaries/2014/w1/2014SIPP_Metadata_AllSections_v2.pdf)*: `WPFINWGT` p. 9; marital status p. 23; age p. 30; nativity/citizenship pp. 35–37; grouped `TYRENTRY` and entry-status item `TIMSTAT` pp. 38–39; education p. 42; sex p. 43; disability p. 1368; monthly earnings p. 2766. | Report-only joint-state and initializer plausibility check. | Wave 1 covers the 2013 reference year and a civilian-noninstitutional universe. Later waves do not represent newly arrived immigrant-only households, although new co-residents of original sample people can enter. `TIMSTAT` is neither a legal-history panel nor authority to model status and is excluded from v1 state. | +For the exact ACS person-archive URLs above, the server currently reports +`Last-Modified` dates of Mar. 4, 2013 for the corrected 2010/2011 archives, +Dec. 11, 2013 for 2012, Feb. 12, 2015 for the current 2013 archive, and Oct. 6, +2015 for 2014. These mutable headers must be confirmed at acquisition; the +committed raw SHA-256 values, not an HTTP date, bind the actual bytes. Oct. 27, +2015 is the 2014 Accuracy statement's server date and is not the person archive's +vintage. + The ACS donor predicate is named, not implied: ```text @@ -286,10 +297,11 @@ flow. The table's universe is the Social Security area, not the Census resident population. The report's glossary includes residents of U.S. territories, -certain people abroad, and other groups absent from ACS PUMS. Therefore even -gross inflow is not directly a resident-population control. A named universe -bridge is required before production use (§6.1). Until then, both the gross entry -schedule and net reconciliation are report-only. +certain people abroad, and other groups absent from ACS PUMS. The exact PDF page +pin for that glossary definition is **CONFIRM_AT_FETCH**. Therefore even gross +inflow is not directly a resident-population control. A named universe bridge is +required before production use (§6.1). Until then, both the gross entry schedule +and net reconciliation are report-only. ## 3. Binding repository and domain law @@ -1085,10 +1097,10 @@ until an acquisition PR records the actual bytes. |---|---|---|---| | `ssa_tr2026_v_a2_components` | Social Security Administration, *[The 2026 Annual Report of the Board of Trustees of the Federal Old-Age and Survivors Insurance and Federal Disability Insurance Trust Funds](https://www.ssa.gov/OACT/TR/2026/tr2026.pdf)*, §V.A.3, and Supplemental Single-Year Table V.A2, “[Immigration Assumptions, Calendar Years 1940–2100](https://www.ssa.gov/oact/TR/2026/lr5a2.html),” assumptions set Feb. 2026, report released June 9, 2026. | Annual LPR inflow/outflow/status-adjustment/net; temporary-or-unlawfully-present inflow/outflow/status-adjustment/net; total net; thousands→persons; retain row class, estimate footnotes and rounding. Use historical/estimated 2015–2025 plus intermediate 2026–2100 for the 2014 M6 origin, or intermediate 2026–2100 for a bound 2025 origin. The positive sum is a stock-accounting inflow proxy; the temporary/unlawfully-present component counts year-end stayers. | Positive-inflow control candidate and net reconciliation. Report-only until universe/timing bridges and exit design exist; prohibited as gate-estimation data. | | `ssa_tr2026_v_a2_sensitivity` | Same report/table/vintage, low-cost and high-cost alternatives. | Same component schema; never substitute 75-year average or ultimate value for annual rows. | Report-only scenario sensitivity. | -| `ssa_area_to_census_resident_bridge` | **UNBOUND.** Must reconcile the 2026 report's Social Security-area definition (glossary pp. 247–248) to the ACS/Census resident universe with an exact source and vintage. | Annual inclusion/exclusion or factor by population category; preserve an auditable raw-SSA series beside the bridged series. Identity is not an admissible silent default. | **BLOCKING** for a schedule labeled resident-population aligned. A raw `ssa_area_proxy` may run report-only. | +| `ssa_area_to_census_resident_bridge` | **UNBOUND.** Must reconcile the 2026 report's Social Security-area glossary definition to the ACS/Census resident universe with an exact source and vintage; the exact PDF page pin is **CONFIRM_AT_FETCH**. | Annual inclusion/exclusion or factor by population category; preserve an auditable raw-SSA series beside the bridged series. Identity is not an admissible silent default. | **BLOCKING** for a schedule labeled resident-population aligned. A raw `ssa_area_proxy` may run report-only. | | `projection_origin_population` | Existing realized 2014 M6 initial slice for the recommended report-only integration path; a 2025/2026 resident baseline source and vintage are **UNBOUND** alternatives. | Bind `start_year`, population universe/artifact/hash, first schedule key, first-cohort disposition and continuous control interval. | **BLOCKING** for an origin other than the existing 2014 report-only open run; decision O15. | | `entry_timing_exposure_bridge` | **UNBOUND.** Must document each Table V.A2 inflow component's event/survival timing and the selected population-origin convention with exact report text and vintage. | Translate controls to opening/mid/end-period exposure without applying source-year survival twice; bind scheduled and target-year age meaning. No person-level status assignment. | **BLOCKING** for a production entry schedule; decision O2. | -| `acs_pums_annual_2010_2014_recent_arrivals` | Census Bureau annual 1-year person PUMS `csv_pus.zip` files for survey years 2010–2014, with exact URLs, annual dictionaries and annual Accuracy statements in §2.2; 2014 Subject Definitions “Year of Entry,” pp. 128–129. Current 2010/2011 bytes are corrected Mar. 4, 2013 re-releases (erratum 87); 2012 is Dec. 17, 2013; current 2013 bytes are the Feb. 12, 2015 repost associated with housing-only erratum 97; 2014 is Oct. 27, 2015. | Bind each file/hash/release/correction status separately. Set survey year only from its manifest; namespace units as `(survey_year, SERIALNO)` and validate `SERIALNO` within file. Bind annual `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, `YOEP`, `POBP`, `NATIVITY`, `RELP`, education, disability, employment, income/earnings and allocation flags. Fit 2010–2013; seal annual 2014. The 5-year PUMS and weights are prohibited. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | +| `acs_pums_annual_2010_2014_recent_arrivals` | Census Bureau annual 1-year person PUMS `csv_pus.zip` files for survey years 2010–2014, with exact URLs, annual dictionaries and annual Accuracy statements in §2.2; 2014 Subject Definitions “Year of Entry,” pp. 128–129. The exact person-archive URLs currently return server `Last-Modified` dates of Mar. 4, 2013 for the corrected 2010/2011 bytes (erratum 87), Dec. 11, 2013 for 2012, Feb. 12, 2015 for the current 2013 bytes associated with housing-only erratum 97, and Oct. 6, 2015 for 2014; confirm those headers at acquisition and bind raw SHA-256 hashes. | Bind each file/hash/release/correction status separately. Set survey year only from its manifest; namespace units as `(survey_year, SERIALNO)` and validate `SERIALNO` within file. Bind annual `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, `YOEP`, `POBP`, `NATIVITY`, `RELP`, education, disability, employment, income/earnings and allocation flags. Fit 2010–2013; seal annual 2014. The 5-year PUMS and weights are prohibited. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | | `acs_stock_to_arrival_state_bridge` | **UNBOUND.** No cited ACS cross-section identifies state at the arrival instant or everyone who subsequently left/died. | Must pin a duration/backcast law, survivor/stayer selection adjustment, reported-entry ambiguity treatment, repeat-entry identification and source vintage. An identity mapping is labeled `stock_proxy` only. | **BLOCKING** for literal entry-time characteristics; decision O12. | | `entrant_marital_household_history_initializer` | **UNBOUND.** Candidate evidence is the annual ACS stock donor plus an exact O8 SIPP file or another named history source; source, universe and vintage are not selected. | Map entry marital history/status, spouse/relations outside roster, household seed, exposure start and later entrant-only law jointly. | **BLOCKING** for entrant marital/household domains and every mixed market; decisions O4/O5/O14. | | `entrant_disability_state_bridge` | **UNBOUND.** Candidate ACS disability questions and SIPP work-limit/benefit concepts have no selected module-native mapping source/vintage. | Estimate entry state and an entrant-specific forward law without relabeling survey concepts as M4 status. | **BLOCKING** for entrant disability outputs; decision O5 and a successor gate. | @@ -1201,14 +1213,16 @@ validation. ### O6. Observation date versus publication date at `T*` -The proposed annual ACS files contain 2010–2014 observations, but the 2014 file -vintage is Oct. 27, 2015; corrected 2010/2011 bytes are Mar. 4, 2013; 2012 is -Dec. 17, 2013; and the current 2013 archive is the Feb. 12, 2015 repost whose -erratum affected only a housing-file variable. Ratify an observation-date rule -analogous to the M6 NAWI publication-lag reasoning, or reject every file whose -byte vintage crosses the boundary and redesign an earlier annual holdout. The -five-year pooled file is not an alternative under either rule. The same issue -affects later-published SIPP metadata, which is report-only here. +The proposed annual ACS files contain 2010–2014 observations, but the person- +archive server `Last-Modified` dates are Oct. 6, 2015 for 2014; Mar. 4, 2013 for +the corrected 2010/2011 bytes; Dec. 11, 2013 for 2012; and Feb. 12, 2015 for the +current 2013 archive whose associated erratum affected only a housing-file +variable. Confirm those headers and bind the raw hashes at acquisition. Ratify +an observation-date rule analogous to the M6 NAWI publication-lag reasoning, or +reject every file whose byte vintage crosses the boundary and redesign an earlier +annual holdout. The five-year pooled file is not an alternative under either +rule. The same issue affects later-published SIPP metadata, which is report-only +here. ### O7. CPS ASEC diagnostic vintage @@ -1483,7 +1497,7 @@ excluded. }, { "id": "ssa_area_to_census_resident_bridge", - "source": "unbound", + "source": "unbound; 2026 Trustees glossary PDF page pin confirm_at_fetch", "vintage": "unbound", "role": "population-universe bridge", "status": "blocking_for_resident_alignment" @@ -1505,7 +1519,7 @@ excluded. { "id": "acs_pums_annual_2010_2014_recent_arrivals", "source": "Census annual 1-year ACS PUMS person files, annual dictionaries and Accuracy statements for 2010-2014; 2014 Subject Definitions; errata 87/97; 2013 same-sex married-couple user note", - "vintage": "current 2010/2011 bytes 2013-03-04; 2012 2013-12-17; current 2013 bytes 2015-02-12; 2014 2015-10-27", + "vintage": "current person-archive Last-Modified headers: 2010/2011 2013-03-04; 2012 2013-12-11; 2013 2015-02-12; 2014 2015-10-06; confirm headers and bind raw hashes at acquisition", "role": "annual resident survivor/stayer stock donor; fit 2010-2013 and hold out separately weighted 2014", "status": "proposed_gate_binding_pending_O6_not_arrival_truth_five_year_input_prohibited" }, From 152d087e5ee2bbc750b7b6250409c6edae85abf2 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Wed, 15 Jul 2026 19:36:13 -0400 Subject: [PATCH 18/18] docs: pin training-only gate cohort mix Co-Authored-By: Codex gpt-5.6-sol --- docs/design/immigration_module.md | 208 ++++++++++++++++++++++-------- 1 file changed, 156 insertions(+), 52 deletions(-) diff --git a/docs/design/immigration_module.md b/docs/design/immigration_module.md index 104c15ad..2e69cc32 100644 --- a/docs/design/immigration_module.md +++ b/docs/design/immigration_module.md @@ -3,7 +3,7 @@ - **Design id**: `2026-07-15-immigration-module` - **Roadmap**: [#113](https://github.com/PolicyEngine/populace-dynamics/issues/113), M6 immigration entry cohorts and the versioned Trustees alignment layer. -- **Status**: DESIGN DRAFT (revision 3; adversarial-referee adjudication pending). +- **Status**: DESIGN DRAFT (revision 4; fixes applied, verification pending). No immigration surface is certified by this document. - **Engine baseline**: `75d30dd57d71b91ee0929246b2f3cbb92263b350`. File:line pins refer to that tree unless a different source is named. @@ -16,6 +16,13 @@ ## Revision log (finding → section) +- Revision 4 applies all four SPEC-SOUND referee amendments: global fitted- + namespace IDs and a pinned domain-disjointness assertion; runner reporting + invalidations; corrected ACS archive headers; and a training-only gate cohort- + mix input. It also labels the 3h condensation as a paraphrase, marks the + Trustees glossary page pin confirm-at-fetch, pins the family-B publisher, and + exposes the remaining assignment choice as O16 → §2.2–2.4, §3.1–3.5, + §4.1–4.7, §4.11, §5, §6, O3/O6/O10/O16, §9.1. - Revision 3 replaces invalid collection-year slicing of five-year ACS PUMS with separately weighted annual 1-year files; freezes year-namespaced units, annual replicate designs and cross-year normalization; adds component-aware timing, @@ -71,7 +78,7 @@ referee: status is a reclassification and not a new person. The temporary/unlawfully present inflow counts only people who remain to year-end, so it is not a count of every border arrival. -2. Use recent-arrival ACS donor units for a joint **resident survivor/stayer +2. Pending O16, use recent-arrival ACS donor units for a joint **resident survivor/stayer stock proxy**. A separately estimated stock-to-arrival bridge must backcast or otherwise map that proxy before it can be called entry-time state. The runtime schedule is deterministic conditional on the frozen artifacts, binding @@ -237,9 +244,9 @@ change between reported entry and interview. Directly copying that state onto an entry-year row is only a named report-only initializer. A literal arrival-state claim requires the separately bound stock-to-arrival bridge in §6.2/O12. -### 2.3 Donor-based versus model-based assignment +### 2.3 Donor-based versus model-based assignment (pending O16) -**Provisional adjudication: donor-based joint assignment, with model-based +**Provisional adjudication pending O16: donor-based joint assignment, with model-based calibration and no cloned future.** This preserves observed covariance among age, sex, education, marital/family state, disability indicators, employment, and earnings. A purely parametric set of independent draws is rejected for v1 because @@ -259,8 +266,10 @@ passing marginal cells would not establish a coherent person or family packet. - runtime realization is deterministic conditional on the frozen artifact, controls, and seed. -A later parametric alternative may compete only on the same joint holdout -surface and floors. Lower marginal error alone is insufficient. +A genuinely joint parametric alternative may compete under O16 only on the same +training/holdout boundary, unit-closure law, joint holdout surface, and floors. +Independent marginal hot-decks remain inadmissible, and lower marginal error +alone is insufficient. ### 2.4 Gross inflow, net change, and status adjustment @@ -528,7 +537,9 @@ The conceptual products are: - **`ImmigrationBindingManifest`**: immutable source/vintage/schema/hash records, annual flow controls, universe labels, and scenario identity; - **`ImmigrationDonorArtifact`**: a fitted pool of recent-arrival person or family - units, matching cells, fallback hierarchy, concept mappings, and provenance; + units, matching cells, fallback hierarchy, concept mappings, and provenance, + including the frozen training-only gate duration masses `C[s,d]` and `q[d]` + defined in §5.2; - **`ArrivalStateBridge`**: an estimated duration/backcast and selection law, or an explicit `stock_proxy` identity label that prohibits an arrival-state claim; - **`EntrantStateBundle`**: the entry frame plus module-native initial state and @@ -553,6 +564,8 @@ The campaign's estimation/determinism split is binding: - recent-arrival definition and survey concept map; - donor unit, matching variables, and fallback order; - sampling/calibration loss and weight trimming; +- the training-only gate duration-mass construction, annual pooling branch, + support/demotion rules, and unit-mass convention in §5.2; - any ACS→SIPP joint-history imputation; - the stock-to-arrival duration/selection bridge, return-entry treatment, and fertility/parity and prior-coverage mappings; @@ -566,16 +579,22 @@ The campaign's estimation/determinism split is binding: - schedule realization under an explicit schedule seed; - synthetic IDs and arrival-unit IDs; - conversion to the seam's prior-year frame coordinate; -- cohort weight calibration to the bound control; and +- cohort weight calibration to the mode-specific bound control (a production + flow control or the frozen unit-mass gate vector); and - serialization and audit calculations. -The schedule is built **once per scenario before the K projection draws** and is -reused across those draws. It does not consume any of the eight existing M6 -period-module streams. Sampling uncertainty is studied by separately named -schedule seeds/artifacts; it is not accidentally mixed into the engine's -process-error draws. +**Design law U1 — uncertainty nesting.** A schedule is built once per scenario +and schedule seed before the K projection draws, then reused across those draws. +The K draws therefore represent engine process uncertainty conditional on one +schedule; separately named schedule seeds/artifacts form an outer sampling- +uncertainty dimension. The schedule consumes none of the eight existing M6 +period-module streams. -### 4.3 Annual cohort sizing +### 4.3 Annual cohort sizing for production/report-only scenarios + +Every `G_*` quantity in this subsection is a production or report-only scenario +control. Trustees and Census controls are prohibited in `gate_imm`; gate mode +uses only the training-derived unit-mass input in §5.2. For Trustees calendar year `y`, define the unbridged positive-inflow control @@ -617,7 +636,8 @@ included in baseline stock or the run has an omission/double-count. No 2015–20 gap or silently dropped first cohort is permitted. The schedule uses a manageable synthetic sample and positive calibration -weights; it does not create 1.34 million physical rows in 2026. For each year: +weights; it does not create 1.34 million physical rows in 2026. For each +production/report-only schedule year: - the number of donor units is frozen from training-only support/power analysis before the truth floor, not by the external population count or candidate; @@ -695,10 +715,11 @@ The precise cells are selected and frozen before candidate scoring. Fallbacks coarsen in a published order; they never cross a prohibited concept boundary merely to fill a cohort. Every fallback count appears in the audit. -Long-run composition is held at the donor artifact's calibrated distribution -unless a separately sourced, gate-reviewed composition trajectory is bound. -Trustees aggregate totals cannot be used to manufacture one. Constant -composition through 2100 is therefore a visible extrapolation limitation, not an +**Design law C1 — no unbound composition drift.** Long-run composition is held at +the donor artifact's calibrated distribution unless a separately sourced, gate- +reviewed composition trajectory is bound. Trustees aggregate totals cannot be +used to manufacture one. Constant composition through 2100 is the conservative +absence-of-evidence fallback and a visible extrapolation limitation, not an empirical forecast claim. ### 4.6 Schedule seed, IDs, and reproducibility @@ -887,7 +908,9 @@ schema versions, schedule seed, the reserved-real-ID-set digest, frozen immigran floor and allocated ID ranges, per-year physical rows and weighted totals, donor-cell effective sample sizes, fallback counts, calibration residuals, top-code/allocation shares, unit-size distribution, state-bundle completeness, -and all report-only/certified labels. +and all report-only/certified labels. A gate build additionally records the +training years, `C[s,d]` table, selected `q[d]` pooling branch, support/demotion +ledger, unit-mass check, and derived-artifact hash from §5.2. The builder refuses to run when a binding required by the selected run is missing or mutable, a raw or derived hash differs, a required year is absent, a unit @@ -913,9 +936,11 @@ The candidate estimand is narrow: > recent-arrival stock-proxy marginals and named joint distributions at their empirical noise > floor? -This is not a gate on literal arrival-time state or external cohort counts: exact agreement with a forced -control is tautological. It is not truth for gross arrivals, people who left or -died before interview, legal status, or post-entry trajectories. +This is not a gate on literal arrival-time state or external cohort counts: exact +agreement with a forced control is tautological. Gate mode instead uses the +training-only, unit-mass reported-duration mix pinned in §5.2. It is not truth for +gross arrivals, people who left or died before interview, legal status, or post- +entry trajectories. ### 5.2 Temporal split and leakage fence @@ -932,18 +957,52 @@ files: - score against the separately weighted annual 2014 file using the same recent- arrival predicate, concept map, universe, and annual-weight treatment. +The gate-mode cohort-size/duration-mix input is pinned. Let training years +`S = {2010, 2011, 2012, 2013}` and let O3 freeze the supported reported-entry- +duration bins `D`. Using only each training file's own person weights, compute + +```text +C[s,d] = sum_i PWGTP[s,i] * 1[ + i satisfies the recent-arrival predicate and duration_bin(i) = d +] + +q_equal[d] = mean_s(C[s,d] / sum_k C[s,k]) +q_population[d] = sum_s C[s,d] / sum_s,k C[s,k] +q[d] = the O3-selected branch, with sum_d q[d] = 1 +``` + +Before any 2014 access, store and hash `C`, `q`, the pooling branch, support, and +demotions in `ImmigrationDonorArtifact`. For the sealed 2014 candidate, the gate +pipeline uses the normalized reported-entry stock-cohort masses + +```text +M_gate[reported_entry_year = 2014 - d] = q[d] +gate_total_mass = 1 +``` + +for exact one-year duration bins; any O3-pooled duration bin retains its explicit +bin label rather than inventing a single entry year. These are reported-entry +**stock-proxy** masses, not literal arrivals, engine `entry_year` values, or an O12 +arrival bridge. The gate invokes the complete donor-selection, calibration, +fallback, seed-grid, and schedule-realization pipeline in this normalized stock- +evaluation mode. O10 supplies its physical unit count, weight caps, and +calibration constraints; no absolute population-count target exists in gate +mode. + Households/arrival units keyed by `(survey_year, SERIALNO)` are indivisible. The -truth and candidate normalize to -the same total before characteristic scoring; the total itself is not a gate -cell. No 2014 characteristic, marginal, top-code treatment selected after seeing -the holdout, CPS/SIPP statistic, current Trustees assumption, or Census projection -may affect the fit. The 2010–2014 5-year PUMS is prohibited from both fitting and -truth: its five-year weights represent/rerake to the pooled period, so slicing it -by survey year would neither recover annual truth nor preserve the leakage fence. -The 2013 same-sex married-couple edit change is frozen in the per-year concept -map. Marital/family cells must harmonize to a definition stable across all five -annual files or be demoted before the truth floor; a dictionary crosswalk alone is -not evidence of longitudinal concept invariance. +2014 truth and candidate each normalize to unit mass before characteristic +scoring; absolute total is not a gate cell. Each training-era pseudo-holdout +recomputes `C` and `q` from its fit side only. No 2014 record, weight, total, +marginal, or holdout-informed top-code treatment; no CPS/SIPP statistic; and no +current Trustees assumption or Census projection may construct the gate input. +The 2014 weights enter only truth scoring after lock. The 2010–2014 +5-year PUMS is prohibited from both fitting and truth: its five-year weights +represent/rerake to the pooled period, so slicing it by survey year would neither +recover annual truth nor preserve the leakage fence. The 2013 same-sex married- +couple edit change is frozen in the per-year concept map. Marital/family cells +must harmonize to a definition stable across all five annual files or be demoted +before the truth floor; a dictionary crosswalk alone is not evidence of +longitudinal concept invariance. The annual files are observations at or before `T*`, but at least the 2014 file was released after its observation year. Decision O6 must ratify an observation- @@ -962,17 +1021,19 @@ The ceremony order is mandatory: 1. Using training-only power analysis, freeze the recent-arrival predicate, donor/simulation unit, physical annual sample size, weight caps, calibration constraints, fallback limits, schedule-seed grid and aggregation/conjunction - rule, concept map, matching ladder, gate cells, metrics, and weighting rules - without candidate holdout results. + rule, concept map, matching ladder, `C[s,d]` construction, O3-selected `q[d]` + pooling branch, duration support/demotion rules, unit-mass convention, gate + cells, metrics, and weighting rules without candidate holdout results. 2. Construct a correlation-respecting real-vs-real floor from deterministic, household-disjoint splits or the annual 2014 replicate-weight design. Never split members of one `(survey_year, SERIALNO)` unit. Training uncertainty treats each year's replicate set as a separate block; replicate columns are never concatenated across years as one common design. 3. On training-era pseudo-holdouts only, run the complete donor-selection, - calibration, fallback, and schedule pipeline across the registered seed grid. - Freeze how candidate-pipeline variability combines with the truth-side floor; - no favorable single schedule seed can define a PASS. + calibration, fallback, and schedule pipeline across the registered seed grid, + recomputing `C` and `q` from that pseudo-holdout's fit side only. Freeze how + candidate-pipeline variability combines with the truth-side floor; no + favorable single schedule seed can define a PASS. 4. Publish, for every proposed cell, raw person count, raw unit count, person- weight Kish ESS, cluster/unit-weight ESS, replicate-design variance, denominator, allocation share, top-code share, and both truth-side and @@ -1100,7 +1161,7 @@ until an acquisition PR records the actual bytes. | `ssa_area_to_census_resident_bridge` | **UNBOUND.** Must reconcile the 2026 report's Social Security-area glossary definition to the ACS/Census resident universe with an exact source and vintage; the exact PDF page pin is **CONFIRM_AT_FETCH**. | Annual inclusion/exclusion or factor by population category; preserve an auditable raw-SSA series beside the bridged series. Identity is not an admissible silent default. | **BLOCKING** for a schedule labeled resident-population aligned. A raw `ssa_area_proxy` may run report-only. | | `projection_origin_population` | Existing realized 2014 M6 initial slice for the recommended report-only integration path; a 2025/2026 resident baseline source and vintage are **UNBOUND** alternatives. | Bind `start_year`, population universe/artifact/hash, first schedule key, first-cohort disposition and continuous control interval. | **BLOCKING** for an origin other than the existing 2014 report-only open run; decision O15. | | `entry_timing_exposure_bridge` | **UNBOUND.** Must document each Table V.A2 inflow component's event/survival timing and the selected population-origin convention with exact report text and vintage. | Translate controls to opening/mid/end-period exposure without applying source-year survival twice; bind scheduled and target-year age meaning. No person-level status assignment. | **BLOCKING** for a production entry schedule; decision O2. | -| `acs_pums_annual_2010_2014_recent_arrivals` | Census Bureau annual 1-year person PUMS `csv_pus.zip` files for survey years 2010–2014, with exact URLs, annual dictionaries and annual Accuracy statements in §2.2; 2014 Subject Definitions “Year of Entry,” pp. 128–129. The exact person-archive URLs currently return server `Last-Modified` dates of Mar. 4, 2013 for the corrected 2010/2011 bytes (erratum 87), Dec. 11, 2013 for 2012, Feb. 12, 2015 for the current 2013 bytes associated with housing-only erratum 97, and Oct. 6, 2015 for 2014; confirm those headers at acquisition and bind raw SHA-256 hashes. | Bind each file/hash/release/correction status separately. Set survey year only from its manifest; namespace units as `(survey_year, SERIALNO)` and validate `SERIALNO` within file. Bind annual `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, `YOEP`, `POBP`, `NATIVITY`, `RELP`, education, disability, employment, income/earnings and allocation flags. Fit 2010–2013; seal annual 2014. The 5-year PUMS and weights are prohibited. | Primary resident survivor/stayer stock donor and proposed `gate_imm` truth, conditional on O6; never literal arrival-state truth. | +| `acs_pums_annual_2010_2014_recent_arrivals` | Census Bureau annual 1-year person PUMS `csv_pus.zip` files for survey years 2010–2014, with exact URLs, annual dictionaries and annual Accuracy statements in §2.2; 2014 Subject Definitions “Year of Entry,” pp. 128–129. The exact person-archive URLs currently return server `Last-Modified` dates of Mar. 4, 2013 for the corrected 2010/2011 bytes (erratum 87), Dec. 11, 2013 for 2012, Feb. 12, 2015 for the current 2013 bytes associated with housing-only erratum 97, and Oct. 6, 2015 for 2014; confirm those headers at acquisition and bind raw SHA-256 hashes. | Bind each file/hash/release/correction status separately. Set survey year only from its manifest; namespace units as `(survey_year, SERIALNO)` and validate `SERIALNO` within file. Bind annual `PWGTP`/replicate weights, `ADJINC`, `AGEP`, `SEX`, `YOEP`, `POBP`, `NATIVITY`, `RELP`, education, disability, employment, income/earnings and allocation flags. Fit 2010–2013 and derive/hash the §5.2 training-only `C[s,d]`/`q[d]` duration mix; seal annual 2014. The 2014 file may enter truth scoring only. The 5-year PUMS and weights are prohibited. | Primary resident survivor/stayer stock donor, sole unit-mass gate-mode cohort-mix input, and proposed `gate_imm` truth, conditional on O6; no absolute gate count and never literal arrival-state truth. | | `acs_stock_to_arrival_state_bridge` | **UNBOUND.** No cited ACS cross-section identifies state at the arrival instant or everyone who subsequently left/died. | Must pin a duration/backcast law, survivor/stayer selection adjustment, reported-entry ambiguity treatment, repeat-entry identification and source vintage. An identity mapping is labeled `stock_proxy` only. | **BLOCKING** for literal entry-time characteristics; decision O12. | | `entrant_marital_household_history_initializer` | **UNBOUND.** Candidate evidence is the annual ACS stock donor plus an exact O8 SIPP file or another named history source; source, universe and vintage are not selected. | Map entry marital history/status, spouse/relations outside roster, household seed, exposure start and later entrant-only law jointly. | **BLOCKING** for entrant marital/household domains and every mixed market; decisions O4/O5/O14. | | `entrant_disability_state_bridge` | **UNBOUND.** Candidate ACS disability questions and SIPP work-limit/benefit concepts have no selected module-native mapping source/vintage. | Estimate entry state and an entrant-specific forward law without relabeling survey concepts as M4 status. | **BLOCKING** for entrant disability outputs; decision O5 and a successor gate. | @@ -1138,6 +1199,11 @@ while unclarified/self responses may mean first or most recent entry. `first_entry_year` is prohibited without another source. The concept-map manifest must also name the 2013 same-sex married-couple edit break and its common-definition harmonization or explicit report-only demotion. +The gate-derived artifact must assert source years exactly `{2010, 2011, 2012, +2013}`, finite nonnegative `C[s,d]` and `q[d]`, supported O3 duration bins, and +`sum_d q[d] = 1` within a pinned numerical tolerance. Its provenance must contain +no 2014 row, weight, total, or marginal; each pseudo-holdout repeats the same +assertions with only its fit-side years. The Census parser must preserve its July-to-June event year and resident- population universe. A calendar-year bridge to Trustees may be displayed only as @@ -1146,7 +1212,9 @@ be rewritten to zero net international migration. ## 7. Open decisions for the referee -Nothing in this list is silently resolved by the provisional recommendation. +Every unresolved choice is listed here. Fixed mechanics outside this list are +explicitly labeled design laws: U1 nests schedule uncertainty outside K engine +draws, and C1 prohibits an unbound composition trend. ### O1. Positive SSA inflow, exit scope, and net proxy — hardest @@ -1182,8 +1250,9 @@ persons. The builder may not use age `-1` or a hidden donor-age shift. Ratify the proposed 0–4-year **reported-entry** window or a different duration; decide whether duration-zero/one donors receive priority; and freeze age/source/ education/family matching cells, annual pooling/replicate-block treatment, -same-sex-marriage concept harmonization, and fallback order. Repeat-entry -identification and prior U.S. coverage belong to O12. +same-sex-marriage concept harmonization, and fallback order. The pooling choice +also selects `q_equal` or `q_population` in §5.2 before 2014 is opened. Repeat- +entry identification and prior U.S. coverage belong to O12. ### O4. Person versus constructed same-reported-entry units — hardest @@ -1249,7 +1318,8 @@ Freeze annual physical unit counts, weight caps, calibration margins and maximum fallback share through training-only power analysis **before** truth floors are constructed. The floor may prune an infeasible surface, but it may not candidate-adaptively choose the sample design. No arbitrary “one row per N -people” constant is adopted here. +people” constant is adopted here. In gate mode these choices realize the unit- +mass `q[d]` target in §5.2; they do not introduce an absolute cohort-count input. ### O11. Social Security-area to Census-resident universe bridge @@ -1301,6 +1371,16 @@ population artifact/vintage, first schedule key, control range, and whether the first cohort is baseline stock or a seam flow. It may neither omit 2015–2025 under a 2014 start nor schedule an entry-year-equal-to-start-year frame. +### O16. Joint assignment family + +Choose either the recommended donor-based joint assignment with model-based +calibration or a predeclared genuinely joint parametric challenger. Both must use +the same training/holdout boundary, donor/simulation-unit closure, gate registry, +floors, and seed protocol; both must preserve or validate the named joint state. +Independent marginal hot-decks and cloned donor futures are prohibited under +either branch. A challenger cannot win on lower marginal error while failing the +joint surface. + ## 8. What this design does not change This document and its eventual entrant-side implementation must leave these @@ -1365,7 +1445,7 @@ report-only. A later implementation should proceed in this order: -1. Referee resolves O1–O15 for the chosen implementation slice and ratifies the +1. Referee resolves O1–O16 for the chosen implementation slice and ratifies the external-binding schema. 2. Acquisition PR commits/hash-binds exact source bytes and parsers; the zero- argument binding factory passes independently of any candidate. @@ -1435,8 +1515,8 @@ excluded. ```json immigration-design-parameters { "design_id": "2026-07-15-immigration-module", - "revision": 3, - "status": "design_draft_referee_pending", + "revision": 4, + "status": "design_draft_revision_4_verification_pending", "engine_baseline": "75d30dd57d71b91ee0929246b2f3cbb92263b350", "roadmap_issue": 113, "docs_only": true, @@ -1470,16 +1550,19 @@ excluded. "entry_timing": "component-aware exposure bridge required; year-end-stayer inflow may not receive a second unadjusted source-year mortality filter", "status_adjustment": "aggregate reclassification; not an entrant and not assigned to persons", "emigration": "outside entry-builder v1; mandatory successor before net-alignment claim", - "assignment": "annual 2010-2014 ACS 1-year joint resident-stock donor units plus model-based calibration; literal arrival state requires a separate bound bridge; no cloned future", + "assignment": "pending O16: annual ACS 1-year joint resident-stock donor units plus model-based calibration are recommended; a joint parametric challenger must clear the same boundary, closure, registry, and floors; literal arrival state requires a separate bound bridge; no cloned future", "prior_us_covered_earnings": "unknown/censored absent a first-or-return-entry and coverage bridge; never default zero", "entrant_fertility": "excluded from fertility risk absent a bound parity/history bridge and entrant-aware kernel", "entrant_claiming": "excluded absent insured-status and prior-coverage evidence", "rng_isolation": "required composite partition before any closed-person byte-identity claim", "entrant_reporting": "open-run m6_runner counters partition schedule rows by entry_kind and births by explicit materialization provenance; whole-schedule opener counts and hardcoded zero immigrants are prohibited", - "runtime": "schedule built once per scenario and reused across K engine draws", "legal_status_dynamics": "out of scope", "current_entry_only_outputs": "report_only" }, + "design_laws": { + "U1_uncertainty_nesting": "build one schedule per scenario and schedule seed, reuse it across K conditional engine draws, and vary schedule seeds only as an outer uncertainty dimension", + "C1_no_unbound_composition_drift": "hold long-run composition at the frozen donor distribution unless a separately sourced and gate-reviewed trajectory is bound; constant composition is a disclosed fallback, not a forecast claim" + }, "external_bindings": [ { "id": "ssa_tr2026_v_a2_components", @@ -1520,7 +1603,7 @@ excluded. "id": "acs_pums_annual_2010_2014_recent_arrivals", "source": "Census annual 1-year ACS PUMS person files, annual dictionaries and Accuracy statements for 2010-2014; 2014 Subject Definitions; errata 87/97; 2013 same-sex married-couple user note", "vintage": "current person-archive Last-Modified headers: 2010/2011 2013-03-04; 2012 2013-12-11; 2013 2015-02-12; 2014 2015-10-06; confirm headers and bind raw hashes at acquisition", - "role": "annual resident survivor/stayer stock donor; fit 2010-2013 and hold out separately weighted 2014", + "role": "annual resident survivor/stayer stock donor; fit 2010-2013, derive and hash training-only C[s,d]/q[d] as the sole unit-mass gate cohort mix, and hold out separately weighted 2014 for truth only", "status": "proposed_gate_binding_pending_O6_not_arrival_truth_five_year_input_prohibited" }, { @@ -1608,12 +1691,19 @@ excluded. "fit_collection_years": [2010, 2011, 2012, 2013], "holdout_collection_years": [2014], "unit_key": ["survey_year", "SERIALNO"], - "annual_pooling_rule": "freeze equal-year-mass versus population-mass treatment from training only", + "absolute_count_input": "none", + "gate_total_mass": 1, + "duration_mass_counts": "C[s,d] uses only annual PWGTP from fit years 2010-2013 for the O3-supported reported-entry-duration bins", + "duration_mix": "q[d] is O3-selected q_equal or q_population, finite and nonnegative, sums to one, and is hash-frozen before any 2014 access", + "reported_entry_cohort_proxy": "M_gate[reported_entry_year=2014-d]=q[d] for exact one-year bins; pooled bins retain their labels; never literal arrival or engine entry_year", + "annual_pooling_rule": "O3 freezes equal-year-mass versus population-mass treatment from training only", "replicate_design": "year-specific blocks; annual 2014 truth uses only its own replicate set", "cross_year_earnings_normalization": "ADJINC to survey-year dollars then I_bound[2014] / I_bound[survey_year], where I_bound is realized NAWI through 2014 and I_proj thereafter", "concept_breaks": "bind and harmonize or demote the 2013 same-sex married-couple edit change", + "control_leakage": "Trustees, Census, CPS, SIPP, and every 2014 record, weight, total, or marginal are prohibited from constructing C or q; 2014 weights enter truth scoring only", "count_alignment_gated": false, "physical_sample_design_frozen_from_training_power_analysis": true, + "physical_sample_design": "O10 freezes physical units, caps, margins, and fallback share from training-only power analysis for the unit-mass target", "schedule_seed_grid_and_aggregation_frozen_before_truth_floor": true, "floors_before_thresholds": true, "operating_characteristic_before_lock": true, @@ -1623,7 +1713,7 @@ excluded. "hardest_open_decisions": [ "O1/O2/O11/O15: literal flow versus net proxy, component timing, population-universe bridge, projection origin, and first cohort", "O5/O12/O13: atomic downstream packet, stock-to-arrival and repeat-coverage bridges, and fertility/claiming exclusions", - "O4/O14: person versus constructed same-reported-entry units, relationship and weight closure, and RNG-isolated cross-domain markets" + "O4/O14/O16: person versus constructed same-reported-entry units, joint assignment family, relationship and weight closure, and RNG-isolated cross-domain markets" ], "certified_surfaces_untouched": [ "gate_m6 registry, thresholds, floors, hashes, and closed-panel support", @@ -1682,6 +1772,20 @@ excluded. "add blocking marital-household, disability, and earnings initializer bindings", "synchronize the machine-readable binding list and preserve mortality and claiming among untouched surfaces" ] + }, + { + "revision": 4, + "date": "2026-07-15", + "kind": "spec_sound_referee_fixes", + "changes": [ + "adopt pending PR 221 section 2.8.2i F2 by reserving the global fitted real-person namespace before splits and asserting immigrant IDs are disjoint from every earnings adapter domain", + "name the m6_runner closed-panel entrant counters invalidated by integration and require row-level entry_kind classification for immigrants, realized PSID openers, and materialized births", + "correct the ACS 2012 and 2014 person-archive Last-Modified dates and require header confirmation plus raw-hash binding at acquisition", + "pin gate mode to a unit-mass reported-entry-duration mix C[s,d]/q[d] derived only from 2010-2013 ACS training weights, with O10 supplying physical sample design", + "add O16 for donor-versus-joint-parametric assignment and label uncertainty nesting U1 and no-unbound-composition-drift C1 as explicit design laws", + "mark the amendment 3h condensation as a paraphrase, the Trustees glossary PDF page pin confirm-at-fetch, and the actual family-B publisher line span", + "re-derive M6 wage-index design pins against merged master c6a3c78" + ] } ] }