Track A v2: implement mechanisms D and S on invented data (a2-ratified-1, §17 items 2–4)

[MaxGhenis]

Implements Track A v2, a2-ratified-1 (docs/design/urban2010_track_a_v2.md, ratified by Max's ruling d513 and #480). It covers §17 items 2–4: implementation in new modules, the §12 invented-data tests, and the invented dry run of all 68 tabulations with forced-refusal recording. Nothing here touches real data. No PSID is read, and no projection, benefit or tabulation runs on real inputs. §11 freezes everything before real-data work, and that comes later through its own registration.

What's in it

• src/populace_dynamics/track_a_v2/, a new package:
  • mechanism D, the statutory DI computation years (§4, DI only per d513 item 8);
  • mechanism S, DI/spouse dual entitlement with the fixed H filing function (§5, d513 items 5 and 9);
  • estimands and definedness (§7);
  • the frozen 68-row matrix with fixed headlines D×R0 and D×F0 (§8);
  • membership guards (§9);
  • refusal order and the attempt record (§10);
  • a provenance manifest (§6).
• Scripts:
  • track_a_v2_dry_run.py, which is invented-only and heads every output INVENTED DATA - NOT A COMPARISON;
  • track_a_v2_registered.py;
  • track_a_v2_structural_count.py;
  • track_a_v2_hash_manifest.py.
• Protection registries: new modules are exact post-review exclusions in scripts/first_estimates_birth_evidence.py and its tests. tests/ss/test_statutory_aime.py registers track_a_v2/benefits.py as a legacy-convention user (§4.3: D is DI-only, so retirement stays legacy).
• Records:
  • docs/design/urban2010_track_a_v2_implementation.md, the implementation report with 19 conservative readings where the spec was silent;
  • …_invariants.md, with 117 stated invariants;
  • …_reads.txt, the exposure ledger.
• Untouched: engine/loop.py, engine/steps.py, gates.yaml, committed runs, and the v1 modules under cola_track_a/, fra68_track/, ss/ and estimates/cola_age_profile.py.

Invariants (property-tested with Hypothesis, where the spec states a property)

These are examples; the full list is in docs/design/urban2010_track_a_v2_invariants.md:

• the computation-years formula: elapsed years less a capped fifth, with a minimum of 2;
• D selects the N highest years;
• nonnegative earnings are monotone, D ≥ L, and N is bounded;
• same-e AIME differences equal the difference of floors;
• own benefit plus excess conserves the total against an unchanged worker;
• L replays v1 exactly, and shared caches and invocation order cannot leak D;
• DS composes D's own PIA with S's fixed age-62 timing;
• an existing attempt directory is never overwritten;
• refusal order is deterministic.

Verification

• pytest tests/track_a_v2: 456 passed, rerun on the rebased tree.
• Birth-evidence seal tests plus the Track B R1 tests: 197 passed.
• Black and ruff are clean.
• Tier recount: unit 4,304 (3,848 + 456), artifact 3,152.
• The lane's full unit tier: 3,983 passed and 6 failed, all in unchanged tests. They are:
  • three timeouts, under a load average of about 294;
  • three refusals of the local Axiom engine's provenance receipt, which a disk cleanup removed; a separate session is diagnosing this.
  • All four test files involved are byte-identical to master.

Open item (not blocking this PR)

§16.7 authorizes a structural pre-count that computes "projection and counts only: no benefits, weight sums or tabulations". The frozen projection does weighted transition arithmetic internally (engine/di_entitlement.py:690). So track_a_v2_structural_count.py currently refuses before loading population data instead of guessing. Max is asked to clarify whether "no weight sums" bars weight-sum outputs or the projection's own internal arithmetic.

🤖 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	Sep 29, 2026 3:38am UTC