[MaxGhenis]

This is the first part of milestone D1 of the income-and-resources design (#559: the D1 row of the milestone table): readers for the PSID family-file waves already staged. The wealth supplements and pension-section items come in later parts. The tier counts were updated at the coordinator's slot, and the independent reviews approved (see below).

PSID use follows the project's data-access record. This build read PSID metadata only, namely setup files and codebooks. It opened no microdata and computed no statistic from PSID records.

What it adds

• src/populace_dynamics/data/psid_income_wealth_registry.py: 1,463 verified fields. Waves covered:
  • income: 1999, 2001, 2003, 2015, 2017, 2019, 2021 and 2023;
  • wealth: 2015, 2017, 2019, 2021 and 2023.
• What each field records:
  • variable, label and inclusive column positions, from the wave's pinned .sps setup (with its SHA-256);
  • value domain, missing codes, top codes and definition notes;
  • its page in the pinned codebook PDF (with its SHA-256).
• What it leaves out: codebook frequencies.
• src/populace_dynamics/data/psid_income_wealth.py: income and wealth readers, labelled like family_income.py. Before reading, they verify the setup bytes, labels and columns, and they refuse unregistered waves, concepts, setups, labels and columns.

Invariants

• Unregistered waves, concepts, setup bytes, labels and columns raise.
• Families keep input order and appear exactly once.
• Documented missing codes, top codes, losses and cents keep their specified handling.
• Income identities use each wave's own components and the legacy $10 tolerance.
• WEALTH1 equals assets less debts. WEALTH2 adds home equity.

Open questions

• Missing annual amounts in early releases. Some early releases lack generated annual SSI amounts and recipient-specific Social Security splits. The raw amounts keep their reporting periods, and the readers refuse unavailable annual concepts.
• WEALTH2 accuracy descriptions. All five cross-reference WEALTH1 despite their WEALTH2 labels. The flags stay raw, and named alternatives remain open.
• 2001 aggregate description. Its prose says seven variables but enumerates five. The identity uses the five.
• Spouse "other assets," 1999 and 2001. These may contain rent; this stays an open source question.
• Private helpers. The reader imports family_income's private _identity_counts and _normalized helpers. The review should decide whether to make them public.

Tests

Tier	Added
unit	94
integration_psid	21

• Unit tests: 94 passed (-n 4). They build invented records.
• integration_psid tests:
  • they verify the staged setup files and build invented records from their layouts;
  • they skip cleanly when the metadata root is absent (21 skipped);
  • they passed against the staged metadata in the build.
• Lint: black -l 79 and ruff are clean.
• Tier counts: updated at the slot. In tests/tier_counts.json, unit goes from 18,339 to 18,433 and integration_psid from 1,450 to 1,471. The table in tests/README-tiers.md matches (total 25,003).

Since the build

• 0d704e36 merges origin/master at fe5ab5ab cleanly.
• 1ec99fb0 keeps the birth-evidence seal. The two new modules are listed in POST_REVIEW_SOURCE_EXCLUSIONS and in the test's expected tuple, and a new assertion checks that neither is reachable from the birth-evidence reducer. That fixes test_reducer_input_identity_matches_reviewed_branch.
• The seal, U2-isolation and invented-record tests pass locally (111 passed). tests/test_tier_policy.py was expected to fail until the tier-count slot.
• A fresh independent review (GPT-6.1 Sol) approved 1ec99fb0 with no high or medium findings. Its prescribed runs passed 111 and 21 tests. It judged the private helper imports safe as used.
• CI at 1ec99fb0 passed lint and the seal. Two failures remained, both expected and outside this PR's code: test_tier_policy, which waits for the tier-count slot, and Track B's holdout-registry append-only check, which waits for Track B's fix on master.

At the slot

• 4f2dc624 merges master at 9a344a1a cleanly. Its tree equals git merge-tree --write-tree 1ec99fb0 9a344a1a.
• 5dd8464b recounts the tiers: 94 more unit tests and 21 more integration_psid tests, which are the two new modules. 7ca55400 updates the README tier table to match.
• CI passes at 7ca55400 (Tests run 40180470423): all four shards, both graph-integration jobs, pytest (3.14), lint and build. The tier-policy test is in the suite and no shard failed.
• An independent delta check (Opus 5.5) approved 7ca55400. It checked the merge tree, that D1a's own files are unchanged since 1ec99fb0, the counts against a static count of the two modules, the README table and CI's head.

Description updated by the Microcosm Dynamics coordinator at landing (10:59Z, 2026-10-25) to match head 7ca55400; the lane's text is otherwise unchanged.

axiom: n/a: survey-file readers and metadata registry for the microsim; no PolicyEngine country-model or RuleSpec encoding changed

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
social-security-model	Ready	Preview	Oct 25, 2026 9:24am UTC

[MaxGhenis]

Merged by the Microcosm Dynamics coordinator at 11:00:20Z on 2026-10-25, as merge commit 1ec57a5d, with --match-head-commit 7ca55400ac0da4e16bb63aa87f85626e33bbdf16. This PR held the tier-count slot.

Gates at the merged head:

• CI: gh pr checks 575 exited 0. The latest Tests run, 40180470423, is for 7ca55400 and passed: all four shards, both graph-integration jobs, pytest (3.14), lint and build. Marking the PR ready started no new run.
• Merge state: MERGEABLE and CLEAN. It was not a draft, and no review requested changes.
• Review: a fresh GPT-6.1 Sol review approved the substantive change at 1ec99fb0 (see the description). An independent Opus 5.5 delta check then approved 7ca55400, after seven checks:
  1. the merge tree equals git merge-tree --write-tree 1ec99fb0 9a344a1a;
  2. after the merge, only the two tier-count files change;
  3. D1a's own files have the same blobs as at 1ec99fb0;
  4. the +94 unit and +21 integration_psid counts match a static count of the two new modules and CI's per-shard totals;
  5. the README table matches tier_counts.json;
  6. CI's run is for this head;
  7. master's later move to 7e050df5 touched only docs/parity-ledger.md.

The description. The coordinator updated it at landing to match the head. The tier counts were described as unchanged, which was no longer true, and the PR was still labelled WIP. The coordinator also added an "At the slot" section. The lane's other text is unchanged.

The slot now passes to #573.