M6 design amendment: forward earnings generator spec (unblocks #173)

[MaxGhenis]

M6 design amendment — forward earnings generator spec (unblocks #173)

Adds §2.7 to docs/design/m6_projection_engine.md (design doc revision 2),
specifying the forward earnings generator the engine build left external. Docs-only,
DRAFT; no gates.yaml edit, no floor, no test.

Why (Sol's honest blocker, PR #173)

The engine build composed steps 1–8 and passed the §2.6 re-certification margin
check, but blocked on forward earnings. The certified gate-1 candidate-11 generator
(run_gate1_candidate11.py, byte-identical to candidate-10) is a backward
biennial imputation chain: it anchors each person's chronologically latest real
earnings, predicts wave t−2 participation from later earnings, and draws earlier
ranks conditional on later ranks. M6 starts from realized 2014 and needs
forward earnings. Sol correctly refused to invent an inverse conditional, a
future-marginal extrapolation, or a two-year→annual kernel (each a different
stochastic law than gate-1 certified), shipping only the admissible ≤2014 refit
plumbing and an explicit external earnings seam (CertifiedEngineInputs still
requires an externally supplied earnings generator). This amendment specifies that
generator so the build can proceed.

What §2.7 specifies

1. The forward law — a biennial forward conditional-rank chain 2014 → 2016 → 2018 (scored on the {2016, 2018} cells of §4.1; realized 2014 is the anchor).
   It mirrors the certified conditioning structure reversed in time and is fit
   ≤2014 from scratch — not an inversion of the backward conditional; the
   scored path stays biennial (no annual kernel for any gated cell); it applies
   a ≤2014-fit conditional out-of-sample rather than extrapolating a marginal.
   This retires all three of Sol's refused choices. Transfers from candidate-11/10:
   k-NN k=25, distance weights 1/0.5/0.25, fixed λ=0.1 donor blend (Q0-exempt),
   the u_w shrunk-permanent rank, the RegimeGatedQRF participation sign gate, the
   zero-anchor full re-entry pool, the weighted single-record draw. Newly chosen
   (justified from ≤2014 diagnostics only, candidate-blind wrt the holdout, per Candidate 2 design: latent-permanent conditioned chained QRF (research memo) #42
   comment 4948637741): the forward donor pools on ≤2014 forward tuples, the
   forward participation-gate fit, the initial-2014 anchor, and the start-of-chain
   memory ramp.
2. Annualization — the odd years {2015, 2017, …} are filled non-scored
   (participation carried from the prior biennial wave; positive level log-linear
   interpolated on the NAWI-indexed level between biennial brackets), feeding only
   the pe-us seam / AIME / claiming. The scored earnings-moment cells read only
   the biennial forward draws.
3. Certification framing — the forward generator is a different stochastic
   law than gate-1 certified, so it is not covered by gate_1 and is
   first-certified by gate_m6; §4.2's refit enumeration and decision 10's
   certified-claims language are updated to record this (no gate_1 certificate
   transfers to it).
4. Implementation contract for the engine lane — inputs (realized ≤2014
   history, ≤T* latent-permanent u_w, age, injected RNG), outputs (biennial
   forward draws for {2016, 2018} + the non-scored annual series), RNG stream
   slots under the §3.2 F3 (module, period) tree (consumed only at biennial steps,
   spawning candidate-7's gate/donor/re-entry sub-streams), and the
   CertifiedEngineInputs seam the build (M6 engine: wave-loop composition per verified design (build only) #173) left external.

Not in scope

No gates.yaml edit, no floor artifact, no test, no code. The forward generator is
implemented by the engine lane against the §2.7.4 contract and first-certified in
the gate_m6 scored run.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
social-security-model	Ready	Preview, Comment	Jul 13, 2026 4:03pm

[MaxGhenis]

Adversarial review — forward earnings generator spec (revision 2, §2.7; commit df9ccb6)

Verdict: MAJOR REVISION. The forward law itself is sound: it is a genuine ≤2014-derivable time-mirror of the certified conditioning structure (not an inversion, not a marginal extrapolation, not an annual kernel — Sol's three refused choices are all retired), the transfer table is code-true bar one provenance mis-citation, the annualization is provably isolated from every gated cell, and the "first-certified by gate_m6, no gate_1 transfer" framing is correct in the design doc. But two MAJOR items must be fixed before this seeds the build: (1) the §2.7.4/§2.7.5 implementation contract does not match PR #173's real EarningsGenerator seam, so the engine lane cannot implement with "zero further design choices" as claimed; (2) the in-flight gate_m6 block draft (draft_cleared_ready_for_lock_flip, pinned to the pre-amendment design) would lock with a covers that understates what a pass certifies. Neither is a blocker — both are contract/record restatements, not a redesign of the law.

Transfer table — verified against the certified code (not the doc's citations)

claim	code check	result
k-NN k = 25	run_gate1_candidate7.py:165 K_NEIGHBORS = 25 (imported byte-for-byte by c10)	✅ true
distance weights 1 / 0.5 / 0.25	candidate7:168-170 W_NEXT=1.0, W_NEXT2=0.5, W_ANCHOR=0.25	✅ true
λ=0.1 donor blend, Q0-exempt (Q0 third term stays |u_A(donor)−u_A(target)|)	run_gate1_candidate10.py:231 LAMBDA_FIXED = 0.1; docstring :28-35 (non-Q0 third term 0.1·u_w+0.9·u_A; Q0 memory-exempt)	✅ true
RegimeGatedQRF sign-gate architecture	real populace-fit class — run_gate1_candidate2.py:96 import, :307 RegimeGatedQRF(seed=seed); gates via fit_participation_gate/_gate_sign_draw	✅ true (external dep, correctly not in-repo)
zero-anchor full re-entry pool (no restriction)	candidate10:18 "no re-entry-pool restriction"; _reentry_draw from run_inner_sweep	✅ true
weighted single-record draw, no smoothing/jitter	candidate7:383 _knn_draw	✅ true
age as only other covariate (marital-blind)	prior round: 0 marital hits in c11; age_bin the covariate	✅ true
backward direction (anchor = chronologically latest; predict t−2 from later; draw earlier|later; two-step-plus-anchor)	run_gate1_baseline.py:137 build_backward_pairs; candidate7:214,1105 anchor = "chronologically last observed period"; candidate10:255-267 "backward k-NN chain"	✅ true
u_w shrunk-permanent rank = "candidate-3 z-decomposition"	candidate10:65-66 "the u_w decomposition is candidate 8's (PR #58)"; candidate8:27-38 u_w = Φ(ŵ/σ̂_w) built on "the SAME candidate-3 decomposition (Stage 1c correlated-noise)"	⚠️ mis-cited (finding 3)

The object that transfers (the u_w shrunk-permanent rank coordinate) is real and does transfer; only its lineage is loosely attributed.

Findings

1 — MAJOR. The §2.7.4/§2.7.5 implementation contract does not match PR #173's real earnings seam; the engine lane cannot implement with "zero further design choices." The actual slot the build left external is EarningsGenerator.generate(frame: pd.DataFrame, year: int, rng) -> np.ndarray (origin/m6-engine:src/populace_dynamics/engine/steps.py:164), invoked every projection year by apply_earnings(... model=inputs.earnings) (assembly.py:292-293; apply_earnings docstring "Draw annual earnings"). The doc instead specifies a different function — (realized_history, u_w, age, rng) → biennial_forward_draws, "a pure function ... with no engine state beyond its ≤2014 fit," consuming "RNG ... for each biennial step." Three concrete mismatches:

• Signature/abstraction: the real seam is per-year, frame-in / ndarray-out. The doc's 4-named-input / biennial-bundle-out signature must be re-expressed as generate(frame, year, rng), stating which frame columns carry realized_history, u_w, and age.
• Annual call vs biennial draw: generate is called for odd years too. The parity branch (draw on even, deterministic-fill on odd, §2.7.2) is implied but never connected to the real per-year protocol — the generator must branch on year internally, which the contract should state.
• "No engine state" is false for a chain: the 2018 step conditions on the drawn 2016 rank (rank_{t+2} | rank_t, rank_{t−2} ⇒ for 2018, rank_t = drawn 2016), which the engine threads through the evolving frame (assembly._merge_period_columns), not "realized ≤2014 history." The contract's input list omits this prior-draw conditioning input and mis-states statelessness. Fix: restate §2.7.4/§2.7.5 against generate(frame, year, rng), name the frame columns, specify parity branching, and specify that the prior drawn biennial rank re-enters via the frame.

2 — MAJOR. The in-flight gate_m6 block draft would lock with a covers that understates what a pass certifies. docs/design/gate_m6_block_draft.yaml (master 1818784, status: draft_cleared_ready_for_lock_flip, design_commit: 1d83a221 / design_pr: "170" — i.e. pinned to revision 1, pre-amendment) gates 6 earnings cells on gated_earnings_reference_years: [2016, 2018] and its headline-prominence not_certified/spec_selection_in_sample record covers only the surface selection (coarsening + decompounding). It nowhere records that (a) the earnings generator producing those {2016,2018} draws is the §2.7 forward law, first-certified here and not gate_1-certified, or (b) the forward generator's structural spec-selection (mirroring a full-window-selected certified spec, §2.7.1) — a limitation distinct from the surface-selection one already listed. A reader of the locked block would reasonably assume the gated earnings use the gate_1-certified generator; the amendment reveals they do not. Under the block's own amendment-1 standard ("a PASS statement must claim exactly the scored surface"), locking as-is misstates scope. The amendment updates only m6_projection_engine.md; it must flag as a lock-flip dependency that the block draft's covers/not_certified fold in the §2.7.3 forward-law framing and re-pin design_commit to df9ccb6.

3 — MINOR. u_w provenance mis-cited. §2.7 (and §10 JSON transfers_from_candidate11) attribute "the u_w shrunk-permanent rank" to "candidate-3 z-decomposition." The u_w = Φ(ŵ/σ̂_w) shrunk-permanent rank is candidate-8's construct (run_gate1_candidate8.py:27-38, PR #58); it is built on candidate-3's Stage-1c correlated-noise decomposition. c10 itself says "the u_w decomposition is candidate 8's (PR #58)." Credit candidate-8-on-candidate-3 (the coordinate transfers correctly regardless).

Checks that pass (recorded so the revision does not re-litigate them)

• ≤2014 derivability of every new choice (question 2) — SATISFIED. Forward donor pools (candidate-7's pool rule applied to ≤2014 forward tuples), forward participation-gate coefficients (≤2014 forward pairs, RegimeGatedQRF architecture/features transferred), the anchor flip (structurally forced — 2014 is the only real forward anchor), and the start-of-chain memory ramp (fixed from the ≤2014 wave calendar: 2014→2016 one-step-plus-anchor, 2016→2018 full two-step) are each determined by ≤2014 data + the mirror rule with no holdout-informed degree of freedom. The Candidate 2 design: latent-permanent conditioned chained QRF (research memo) #42 spec-selection disclosure is present and honest (out-of-sample for fitted parameters, in-sample for structural choice). Note: "candidate-blind wrt the holdout" is a design commitment the floors/pass-verification ceremony must confirm against the actual fit (no code exists yet).
• Annualization isolation (question 3) — SATISFIED. The scored earnings cells read only the biennial {2016, 2018} draws (block draft gated_earnings_reference_years: [2016, 2018]); the odd-year participation-carry / log-linear-interpolation values carry non_scored_annualization and feed only the pe-us seam / AIME / claiming, none of which is a gated cell (gated = marital/disability/mortality flows + biennial earnings moments). The interp-vs-carry flag is genuinely immaterial to certification (it moves only report-only AIME/benefit levels), so §2.7.2's "floors ceremony need not adjudicate it" is correct.
• Certification framing, doc side (question 4) — COHERENT. §2.7.3, §4.2, and decision 10 consistently state no gate_1 certificate transfers and a gate_m6 pass is the forward law's sole certification; §4.2 correctly narrows the certified backward chain's admissible ≤2014 refit to plumbing, with earnings left external (confirmed: CertifiedEngineInputs.earnings is a standalone field, not in from_refit_bundle's required bundle set {family, household, modifier, disability, claiming_pmfs}). The gap is only the block-draft artifact (finding 2), not the doc's internal logic.
• RNG slots (question 5, RNG part) — code-true. candidate10:239 SUBSTREAM_CODES {gate:1, donor-draw:2, re-entry-draw:3} and _substream two-element SeedSequence([seed, code]) (:242-252) match §2.7.5's "three canonical sub-streams ... two-element SeedSequence([·, code]) draw order."

Read-only adversarial review; no repo edits, no merge/ready. Every cited line re-checked against df9ccb6, origin/m6-engine, and master 1818784.

[MaxGhenis]

Revision — design referee round addressed (commits d6abb16 + 85f95e7)

All three findings from the adversarial review (comment 4959673982, MAJOR REVISION)
are addressed. The forward law itself was verified code-true (the referee's transfer
table checked out bar the one provenance mis-cite); the fixes are contract/record
restatements, not a redesign. Docs-only; no gates.yaml edit, no floor, no test.

Finding → change

#	Sev	Finding	Fix
1	MAJOR	§2.7.4/§2.7.5 contract didn't match PR #173's real EarningsGenerator seam	respec'd to generate(frame, year, rng) -> np.ndarray (verified against origin/m6-engine:steps.py:164-169, assembly.py:86,292-293) — §2.7.4
1a	—	signature/abstraction (per-year, frame-in/ndarray-out)	§2.7.4 gives the Protocol verbatim + names the frame columns read (earnings, realized-2014 cols, u_w, age, sex)
1b	—	annual-call-vs-biennial-draw parity	§2.7.4 parity branch: biennial draw on even reference years, deterministic carry on odd; §2.7.5 RNG consumed only on even years via the per-year person_generator(EARNINGS) stream
1c	—	"no engine state" is false for a chain	§2.7.4 names the drawn-prior-2016-rank threading — recovered inside generate by re-ranking the frame's carried earnings column (threaded by _merge_period_columns); generator holds no cross-year state. §2.7.2 annualization corrected to carry-forward (the forward per-year seam has no lookahead; interpolation only via batch+backfill) — resolves the rev-1 interp-vs-carry flag
2	MAJOR	block draft would lock with an understated covers	docs/design/gate_m6_block_draft.yaml: covers + new not_certified.forward_earnings_law_not_gate1_certified record that a gate_m6 PASS first-certifies the §2.7 forward law (gate_1 doesn't cover it; no certificate transfers) incl. its structural spec-selection distinct from the surface one; design_pr 170→175, design_commit re-pinned off stale 1d83a221 to this PR's design commit (d6abb16) + design_commit_note
3	MINOR	u_w provenance	cited as candidate-8's u_w = Φ(ŵ/σ̂_w) (PR #58) built on candidate-3's Stage-1c decomposition — §2.7 transfer bullet + §10 ledger

The corrected seam contract, in three sentences

The forward generator implements PR #173's EarningsGenerator.generate(frame, year, rng) -> np.ndarray protocol — per-year, frame-in / ndarray-out — called by
apply_earnings every projection year with each person's engine-owned
ProjectionModule.EARNINGS stream, and it is stateful through the frame, not a
pure function: generate branches on year, drawing the biennial forward value on
even reference years ({2016, 2018}, consuming the candidate-7 gate/donor/re-entry
substreams) and returning the deterministic carry-forward value on odd years, with
the return written to frame["earnings"] and carried to the next year by
_merge_period_columns. The chain's drawn-prior-rank conditioning (rank_{t+2} | rank_t, …) is not an argument but is recovered inside generate by re-ranking the
carried earnings column (0 = non-participation), with the earlier lag and anchor
from the realized-2014 columns, so no chain state lives outside the frame.

Block-draft delta

covers now states the gated {2016,2018} earnings cells ride on the §2.7 forward
law (a different stochastic law than the gate_1-certified backward chain, first- and
sole-certified by gate_m6); a new not_certified margin
forward_earnings_law_not_gate1_certified records this plus the forward law's
structural spec-selection (distinct from the surface-selection margin);
design_pr 170→175, design_commit 1d83a221→d6abb16 with a note that it pins this
PR's amended design and finalizes to the squash-merge at the lock flip. Verified:
tests/test_gate_m6_floors.py passes (23/23) against the edited block — mortality
drift stays named first, all six required not_certified margins remain.

Anything I could not verify against #173's code

Nothing. Every seam fact was re-derived from origin/m6-engine: the generate
signature (steps.py:164-169), the per-year call + frame["earnings"] write
(apply_earnings, steps.py:205-238), the per-person EARNINGS stream
(steps.py:212-224), the standalone external slot (CertifiedEngineInputs.earnings,
assembly.py:86; earnings_step, :292-293), and the cross-year threading
(_merge_period_columns, assembly.py:151-169). The only design commitment the code
cannot yet confirm — noted in the doc — is "candidate-blind wrt the holdout," which
has no implementation yet and is the floors/pass-verification ceremony's to confirm.

[MaxGhenis]

Verification round (round-diff) — forward-earnings revision (d6abb16 + 85f95e7)

Verdict: VERIFIED (ready to merge). All three findings from the MAJOR-REVISION review (comment 4959673982) are genuinely resolved — not renamed — and every seam fact was re-derived from origin/m6-engine directly, not taken from the doc's citations. The one derived correction (carry-forward is forced) checks out and is actually stronger than the doc states. One MINOR, non-blocking precision nit is noted at the end; it does not reopen any finding.

Finding 1 (MAJOR — seam contract) — RESOLVED, re-verified against the real engine

§2.7.4/§2.7.5 now specify PR #173's real protocol, and each fact holds in code:

• Protocol EarningsGenerator.generate(self, frame: pd.DataFrame, year: int, rng) -> np.ndarray — steps.py:164-169, quoted verbatim in §2.7.4. ✅
• Per-year, frame-in / ndarray-out, per-person age ≥ 15, engine-owned stream, frame write — apply_earnings (steps.py:205-238): docstring "Draw annual earnings from the refitted chained generator"; eligible = ...age >= 15; person_rng = context.person_generator(ProjectionModule.EARNINGS, person_id); model.generate(frame.iloc[[index]], context.year, person_rng); out["earnings"] = generated. All match §2.7.4/§2.7.5. ✅
• Stateful through the frame / drawn-prior-rank via re-rank — the period loop for period_index, year in enumerate(range(start_year+1, end_year+1)) (loop.py:203) is forward, one year at a time, no lookahead, and current = self.modules.earnings(current, …) (loop.py:249) threads the frame across periods, so the drawn 2016 level survives in current["earnings"] to the 2018 step's re-rank. The generator holds no cross-year state. ✅
• Backward-chain / external-slot facts confirmed: refit.py:75-76 predicts earnings_tm2 (two years earlier) — the certified backward chain; CertifiedEngineInputs.earnings (assembly.py:86) is the standalone external slot (earnings_step, :292-293), not in from_refit_bundle's required set. ✅

The new "carry-forward forced" correction (§2.7.2) — VERIFIED coherent and, in fact, doubly forced. The forward per-year loop has no lookahead, so at the 2015 call the 2016 draw does not exist → interpolation-toward-next is impossible without drawing 2016 early on the wrong period stream; carry-forward is the only seam-faithful rule. This is coherent with §2.7.2 and still provably non-scored (gated earnings read only the biennial {2016,2018} draws; odd-year values carry non_scored_annualization and feed only the report-only seam/AIME/claiming). Stronger than the doc claims: carry-forward is also required for chain integrity — 2017 must hold the 2016 level unchanged so the 2018 step re-ranks rank_t = 2016; interpolating 2017 would corrupt that re-rank. The batch-then-backfill interpolation alternative preserves the chain (biennial draws computed first) and is correctly flagged as a non-default departure. Consistent throughout.

Finding 2 (MAJOR — block-draft covers) — RESOLVED, test 23/23

docs/design/gate_m6_block_draft.yaml (now edited in-branch, not merely flagged):

• covers adds that the gated {2016,2018} earnings cells ride on the §2.7 forward law, "a DIFFERENT stochastic law than the gate_1-certified BACKWARD chain… gate_1 does NOT cover it and no gate_1 certificate transfers." ✅
• New not_certified margin forward_earnings_law_not_gate1_certified (line 132), distinct from spec_selection_in_sample (line 127): records first-certified-here, no gate_1 transfer, the forward law's structural spec-selection, and "A PASS statement must say the gated earnings use an M6-first-certified forward law, not the gate_1-certified generator." ✅ Claims-exact.
• design_pr 170→175, design_commit 1d83a221→d6abb16 with a design_commit_note re-pinning off the stale pre-amendment commit and finalizing to the squash-merge at the lock flip. ✅
• Mortality still first, only-added: mortality_drift is margins[0] (line 82); all six REQUIRED_NOT_CERTIFIED margins remain; the new margin is purely additive (not in the required set, allowed by the <= subset check). I ran tests/test_gate_m6_floors.py myself — 23 passed — and check_not_certified asserts margins[0] == "mortality_drift", the required-subset, and a non-empty detail per margin. ✅

Finding 3 (MINOR — u_w provenance) — RESOLVED

§2.7 now reads "u_w = Φ(ŵ/σ̂_w) shrunk-permanent rank — candidate-8's construct (PR #58, run_gate1_candidate8.py:27-38) built on candidate-3's Stage-1c correlated-noise decomposition"; §10 ledger updated to u_w_shrunk_permanent_rank_candidate8_PR58_on_candidate3_stage1c. Matches the code. ✅

Candidate-blind non-verifiable — honestly scoped

§2.7.1 keeps "justified from ≤2014 diagnostics only, candidate-blind with respect to the holdout" as a design commitment, and the revision comment correctly scopes it as having no implementation yet and deferred to the floors/pass-verification ceremony. Not overclaimed as verified. ✅

One MINOR, non-blocking precision nit (does not reopen finding 1)

§2.7.4 (and the §10 JSON) attribute the cross-year carry of the earnings column to _merge_period_columns. In the real engine the earnings column is not threaded by _merge_period_columns — apply_earnings writes out["earnings"] in place (steps.py:237) and the frame is carried by the loop's current = self.modules.earnings(current, …) reassignment (loop.py:249); _merge_period_columns threads the marital/disability/household update-frames (assembly.py:226/285/315), which produce separate updates DataFrames, whereas earnings does not. The chain-integrity conclusion the doc draws (the drawn 2016 level survives in the frame to the 2018 re-rank) is correct and verified; only the named mechanism for the earnings column is imprecise. Harmless to the engine lane (the real code threads the frame correctly regardless), so it does not block merge — worth a one-line fix in passing.

Round-diff verification, read-only; no repo edits, no merge/ready. Every seam fact re-derived from origin/m6-engine (steps.py, loop.py, assembly.py, refit.py); block test run locally (23/23).