[MaxGhenis]

WIP: round 7 approved 695798ed with four low findings and four notes, answered in 6e96c64d and merged with master at 085a33b9; the round-8 delta review is next. This is milestone D2 of the income-and-resources design (#559, the D2 row of the milestone table). It adds readers for the SIPP releases of 2018 through 2025 (reference years 2017–2024). The tier-count update waits for the coordinator's slot.

What it adds

• src/populace_dynamics/data/sipp_income.py: read_sipp_income_months, a person-month reader.
  • Concepts are selected explicitly, and pipe-delimited files are read with usecols.
  • Quotes are literal characters (quoting=csv.QUOTE_NONE), so the reader sees the same physical records as the layout validator.
  • Identifiers stay strings, and value domains are strict.
  • It can attach the calendar-year replicate weights.
• src/populace_dynamics/data/sipp_income_registry.py: canonical concepts and each release's Census definitions: labels, source and storage types, codes, ranges, universes, ownership level, period, corrections and user notes. It needs no network access at run time.
• data/external/sipp_income/: the evidence and its tooling.
  • Evidence: the captured Census metadata, 107.5 MB in 228 tracked files, none over 4.2 MB.
  • Tooling: the dictionary parser, the registry generator, the concept selection, the cross-release crosswalk, label and domain checks, refusals and source rulings.
  • CRLF files are marked -text, so git stores the bytes the registry hashes.
• Tests: tests/income_resources/test_sipp_income.py, test_sipp_income_evidence.py and test_sipp_income_refusal_properties.py.

Concepts: 561 are selected, covering:

• SSI and Social Security receipt and amounts;
• assets, debts and net worth, with each item's ownership level;
• retirement accounts and pensions, with employer offer and participation from 2021;
• disability;
• citizenship, nativity and year of entry;
• living arrangement;
• the design and linkage variables (panel, wave, month, person and household identifiers, the monthly weight, the variance stratum and half sample, and 241 calendar-year replicate weights).

Verification sources: the Census variable API verifies the 2022–2025 releases. Its 2018–2021 endpoints return 404, so each of those releases is verified against its own dictionary and storage schema.

Every disagreement between sources is either refused or carries a named ruling:

• source_rulings.json names 13 domain rulings covering all 64 release-and-variable disagreements in domain_checks.json, with both sources' locations and intervals;
• the registry generator refuses a disagreement that lacks an exact, cited, settled ruling.

User notes: the inventory lists 355 Census user notes and indexes. 101 are stored (93 notes and 8 indexes). Eight notes quoted individual survey cases, so they are kept as exclusions: their URL, title, release and variables stay, but not their bodies. The capture script refuses those URLs before any request. A guard, record_bearing_note, refuses to store any new page holding a case record in any form it lists:

• an identifier column, or a cell that has a cell of digits alone below it and begins with an identifier name or, in a first-row or header cell, names one anywhere;
• an identifier name followed by a digit with only spaces or simple marks between, or by a run of three or more digits that is not a year, with at most 40 characters and no period between;
• a table row with a cell that begins with an identifier name, or in a first-row or header cell names one anywhere, and, in any other cell, even one that names an identifier too, a run of three or more digits that is not a year, even in a variable-definition table;
• a table row, or a preformatted line, of three or more numbers;
• a run of nine or more digits in the text a reader sees, or of 14 or more, an SSUID's length, anywhere in the page;
• a preformatted block with an identifier and a digit.

The two rules that follow an identifier name read three things, all with entities decoded: the visible text with HTML comments; the page source with its tags, attributes and scripts; and each quoted attribute value other than href and src, and each quoted string in a script, one at a time. In the text and comments a tag counts as a space. In the source, the 40 characters also hold no angle bracket, quote or equals sign, and href and src values, whose slugs name identifiers without values, are removed from every tag outside scripts and styles and from their opening tags. A tag opens with a letter, ! or /. Script and style contents, up to their end tag or the end of the page, are read as they stand, so no < in script code hides a src assignment. The table and preformatted rules read each cell's or block's text without its tags; the row-header exemption also reads a header cell's scope attribute. The nine-digit rule skips comments and noscript blocks, whose tracking numbers are not page content.

These forms are out of scope: a value before its identifier name; <br>-separated CSV text without an identifier; div grids; an identifier name and its value in different attribute values or script strings, or one of them in a string and the other in script code; a script string after an unpaired quote mark, as in a comment such as // it's; an identifier compared with a value in script code, as in PNUM < 101; an attribute value that holds a raw >, which ends its tag; a value in an href or src value, unless it is a run of 14 or more digits; and a cell outside a table's first row and header cells that names an identifier after other words. The table rules in turn refuse some definition and index tables that name an identifier in a heading cell with digits below it, or beside a run of three or more digits that is not a year in its row; such a page stops the capture loudly.

Invariants

• Only a verified release, concept, source type and value domain may enter. Every verified source must admit a value, apart from the API's documented missing sentinels.
• A domain on which sources disagree enters only under an exact, cited, settled ruling.
• One input person-month yields one output row, in input order. A quote never joins two physical records, and a carriage return never splits one: the reader yields one row per LF-delimited data line, or refuses. A malformed layout is refused.
• Person identifiers are strings, stable within a panel across months, waves and releases.
• Source codes and weights pass through unchanged. There is no household or joint allocation and no annualization.
• The corrected 2018–2021 TSSSAMT requires a file downloaded on or after Census's 2025-07-24 correction.
• Replicate joins need verified, unique, complete keys and matching base weights.
• No metadata is borrowed from another release. The frozen tables reproduce the hashed evidence without network access.
• No stored page shows a form record_bearing_note refuses.
• Each guard rule, and each limit on what the identifier rules read, has a minimal invented page and a twin that differs only in what it reads (33 pairs): disabling the rule admits its page, and dropping the limit refuses its twin. The exemptions and the bounds on link-target removal are pinned by invented record and definition pages instead.
• Each ruling member's PDF citations, with a page or without, are exactly one {year}_dictionary.pdf#page={page} per page its dictionary entry holds.

Each invariant has a Hypothesis property or an example test. The domain rule and Census's own crosswalks give differential tests.

Open questions

Each of these refuses the affected concepts rather than guessing; refused_concepts.json and source_rulings.json list every case.

• Early monthly Social Security receipt (ESSSMNYN, 2018–2020): it has no verified codes. Annual receipt and amounts remain.
• ESSI_BRSN, 2021–2022: the category order conflicts.
• The 2020 joint asset and debt families: they disagree with Census's correction note.
• Disability definitions: 2020 TDIS6AMT and EDIS8MNYN conflict.
• Missing codes or ranges: 2021 TSSI_ERSN and EBOATOWNER3 lack value codes, and the 2021 interview address identifier has an inverted printed range.
• SSI0 inputs not yet verified: no RMD identifier or retirement-fund access input has been found.

Tests

Counted by collection over the three test modules:

Tier	Tests
unit	183
artifact	216

All 399 pass locally with two workers at 085a33b9, and so do 12 of the 13 birth-evidence seal tests. The other, the reachability test's track-U assertion, needs modules this sparse clone leaves out. CI runs that test and the U2 isolation tests.

Review

• Round 1 was stopped before it finished, for a reason unrelated to the code.

• Round 2 (fresh, at 1f51b60a): REVISE, with one high and two medium findings.

  • High: eight stored user notes quoted individual survey cases.
  • Medium: a quote in an unselected field could join two physical records, silently dropping person-months.
  • Medium: 64 admitted domain disagreements had no named rulings.

• Fix (eb77fc19):

  • removes the eight bodies and adds the exclusions and guard;
  • sets QUOTE_NONE, with a minimized regression and a quote property;
  • adds the 13 rulings and the generator's refusal;
  • adds properties for the vintage gate, malformed layouts, replicate keys, source conflicts, ownership, periods and evidence pins.

  The regenerated concept, definition, release, replicate, correction and variable-to-note tables are identical to 1f51b60a's. The note table keeps all 101 entries: the eight exclusions have an empty body path and the status excluded_record_bearing. The evidence pins lose the eight bodies and change only for source_rulings.json and user_notes_manifest.json.

• Round 3 (delta, at eb77fc19): REVISE, with two medium and two low findings.

  • Medium: the capture guard missed record forms such as long-format value tables, row headers, prose with words between an identifier and its value, preformatted blocks and plain-text CSV.
  • Medium: a lone carriage return in an unselected field split one physical record into two person-months for pandas while the layout check saw one.
  • Low: the THEQ_BUS ruling misdescribed the dictionary's printed range.
  • Low: the generator did not check a ruling's PDF page citations.

• Fix (7521c6d8):

  • the guard refuses the forms then listed under User notes. Tests add 16 invented record pages (the round-3 guard missed 13), 4 invented definition pages it still admits, and three properties. Every stored note still passes;
  • _check_layout strips one LF, then one CR, and refuses any other carriage return. Tests add the review's minimized regression, a CRLF file and a carriage return in the quote property's alphabet;
  • the THEQ_BUS reason now says the printed upper bound is malformed and the lower bound differs from the API's. The pin of source_rulings.json is regenerated, and no other table changes;
  • the generator checks PDF citations against the dictionary pages, and the damage property adds a wrong page and another release's PDF.

• Round 4 (delta, at 7521c6d8): APPROVE, with seven low findings and four notes.

  • Low: three guard rules had no test that failed without them, because every invented record page also tripped the digit-run rules.
  • Low: the identifier rules skipped scripts and attributes, which are stored but not shown.
  • Low: a year beside an identifier name refused definition pages and index links.
  • Low: the three-number rule missed Census's negative-dollar form and preformatted lines. (Round 4 also listed <br> CSV text and div grids; those stay admitted and out of scope.)
  • Low: the notes, the docstring and the round-3 commit message overstated three rules.
  • Low: the PDF citation check ignored citations without a page.
  • Low: no test pinned the 40-character window.

• Fix (04a2b89a):

  • each guard rule now has a minimal refused page and an admitted twin (eight pairs);
  • the identifier rules read the page source, and a 14-digit run refuses anywhere;
  • years from 1900 to 2099 are exempt from the 40-character and same-row rules, with admitted year pages and a property;
  • numeric cells admit the signed-dollar, Unicode-minus and bracketed forms, and preformatted lines of three numbers refuse;
  • every .pdf citation is checked, and each damage case must fail at its own check;
  • a test pins the window at 40 characters;
  • the THEQ_BUS reason, the reader's docstring and the notes are corrected. Only the source_rulings.json pin changes in the registry.

  17 of the 129 evidence tests fail against 7521c6d8's guard, and 16 mutants are all caught. Every stored note still passes. (Round 5 corrected four claims in this fix's message: the eight twins covered five rules and three readings, not every rule; the 16 mutants had two for the window width and none for the digit-below rule or the row-header and definition-table exemptions; only pageless_pdf passes generation under the parent check, while pageless_other_release_pdf stops on a file missing from the invented folder; and 14 of the 16 invented record pages, not all, carried the invented SSUID. The heading correction also needs "that is not a year".)

• Merge (ffc4d485): origin/master at 1ec57a5d (D1a, PSID income and wealth readers and field registry (D1a) #575). The birth-evidence check keeps D1a's exclusions and reachability assertion, then D2's.

• Round 5 (delta, at ffc4d485): APPROVE, with five low findings and five notes.

  • Low: reading the page source refused pages that only name an identifier, and index links: the 40-character window ran across attribute boundaries, and the adjacency rule fired on link slugs.
  • Low: mutants of the new rules survived every test, because the source twins were each refused by both source rules.
  • Low: four claims about the tests overstated them (listed above).
  • Low: the notes and this body overstated which rules read the source, and the same-row rule's condition.
  • Low: some record forms were still admitted; the review gave a fix for an identifier inside a heading.

• Fix (c1a3c7b6):

  • in the source, the window holds no quote or equals sign, and href and src values are removed from tags before the identifier rules read it (the 14-digit rule still reads them). The review's pages that only name an identifier are now admitted definition pages; a 14-digit run in a link target is still refused;
  • twins now cover every rule and each source-reading limit (17 pairs), with record pages for the year exemption's lookahead and its absence from the adjacency rule, a row header outside a definition table, two numbers per preformatted line, and a property over preformatted lines;
  • a first-row or header cell that names an identifier anywhere, with a cell of digits alone below it, is refused;
  • the notes, the docstring and the reader's carriage-return sentence are corrected;
  • found by this fix's own mutants: the visible-text window stopped at an angle bracket, though the text holds no tags by then, so a decoded < or > between an identifier name and a value admitted the page. The window there now stops only at a period, as the round-3 rule meant ("within 40 characters of the same sentence"); the source reading still stops at tags. A twin pins it, 18 pairs in all.

  With ffc4d485's guard, 9 of the 153 evidence tests fail, the same 9 in each of three Hypothesis seeds. All 32 guard mutants are caught in seeds 0 and 7, each of the 18 twins isolates its rule or limit, and every stored note still passes. (Round 6 corrected two claims in this fix: the 18 twins did not cover the heading-cell rule, each mark that stops the source window alone, unquoted href and src link targets, or adjacency in the text alone; and the other L5 forms were out of scope only in this body, not in the docstring. Two of the "now admitted" definition pages, tracking_number_in_link_target and row_header_outside_definition_table, were already admitted by the parent.)

• Merge (60b67f82): origin/master at d8302233 (SM1, SM1: differential mortality by lifetime earnings, education and race (normalized within age-sex-year cells) #570). It has no conflicts; git auto-merged the birth-evidence check and its script, which both branches changed.

• Round 6 (delta, at 60b67f82): APPROVE, with three low findings and four notes.

  • Low: the new source limits admit an identifier and its value in different attribute values or script strings, or split by a quote or equals sign within one, and values in link targets; the docstring's "stay inside one attribute value or string" overstated the window.
  • Low: nine of the review's ten mutants of the changed rules survived, so the twin claims overstated the tests.
  • Low: a header cell that names an identifier after other words, with a value elsewhere in its row, was admitted.
  • Notes: the heading-cell rule refuses some definition and index tables; an angle bracket in a script comparison hid a src assignment from the source reading; four wording corrections; PNUM > 100 is now refused.

• Fix (c8dfe4f1):

  • the docstring, the notes and this body list the forms the source limits admit as out of scope, with the review's other residual forms;
  • twins pin each mark that stops the source window alone, unquoted href and src link targets, adjacency in the text reading alone, and both heading-cell rules, 26 pairs in all. Record pages pin the heading-names rule's two cell conditions, and a definition page pins its limit to those cells;
  • a first-row or header cell that names an identifier anywhere now also counts for the same-row rule, as the review proposed;
  • a tag opens with a letter, ! or /, so a comparison in a script no longer hides a src assignment;
  • the notes, the docstring and the test comments are corrected.

  With c1a3c7b6's guard, 2 of the 165 evidence tests fail, the same 2 in each of three Hypothesis seeds: the two that pin this fix's code changes. All 44 guard mutants are caught in seeds 0 and 7, each of the 26 twins isolates its rule or limit, and every stored note still passes. (Round 7 corrected two claims in this fix: a minified comparison, a CDATA marker or a</b in a script still hid a src assignment, and the bounds on link-target removal were pinned only against a < followed by a space or digit.)

• Merge (695798ed): origin/master at 0f69bbb2 (OP1, OP1: open-population harness around the sealed loop #566, and its report fix, Fix review r10's report findings for OP1 #589). It has no conflicts; git auto-merged the birth-evidence check and its script, which both branches changed.

• Round 7 (delta, at 695798ed): APPROVE, with four low findings and four notes.

  • Low: a < followed by a letter, / or ! in a script still opened a "tag" whose href and src values were removed, so a minified comparison, a CDATA marker or a</b hid a src assignment.
  • Low: the source window stops at any angle bracket, raw or decoded, which the lists did not say, and the out-of-scope list left out angle-bracket splits and script comparisons.
  • Low: the same-row rule skipped any other cell that began with an identifier name, which no list stated.
  • Low: the review's mutants of the tag pattern and of the same-row rule's cell conditions survived.
  • Notes: the heading-cell rules also refuse some definition and index rows that hold a value in their row; the quote twins' comma is load-bearing; a condition was always true; round 5's L4b page is now refused.

• Fix (6e96c64d):

  • the source reading splits out script and style elements, keeps their contents as they stand, and removes href and src values only from their opening tags;
  • the identifier rules also read each quoted attribute value other than href and src, and each quoted string in a script, one at a time, decoded and joined by periods;
  • the same-row rule reads every other cell, even one that begins with an identifier name;
  • record and definition pages pin each of the review's surviving mutants, and seven new twins pin the new rules and limits, 33 pairs in all. Two older twins now use forms that only the source reading refuses;
  • the docstring, the notes and this body name the angle-bracket limit, the new out-of-scope forms and the rows the table rules refuse.

  With 695798ed's guard, 26 of the 201 evidence tests fail, the same 26 in each of three Hypothesis seeds: the ones that pin this fix's code changes. All 67 guard mutants are caught in seeds 0 and 7; this fix's own checks found four of them unpinned, and record pages now pin them. Each of the 33 twins isolates its rule or limit, no page the parent guard refuses is admitted, and every stored note still passes.

• Merge (085a33b9): origin/master at 172f690f (Held-out data registry: round 7's follow-ups (unset event path, record ids, zero push boundary) #580 and the commits before it). It has no conflicts and changes no D2 path.

• Round 8 (delta, at 085a33b9): next.

The eight removed bodies remain in this branch's earlier commits. A squash merge keeps them out of master's history.

Status

• The build ran in three attempts; two stopped on network errors. Commits 0482dc31 and 5bdd595b hold the later attempts' edits. 1f51b60a lists the two reader modules among the birth-evidence check's post-review exclusions; dac0d5f9, ffc4d485, 60b67f82, 695798ed and 085a33b9 merge master.
• One CI failure is expected: the tier-count test, until the slot.

Data

No SIPP microdata was downloaded, opened or used to compute a statistic, because a SIPP release will be held out for the SSI gate. Tests use invented records and committed metadata.

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 26, 2026 12:02pm UTC