Read restamped Chronicle facts at their data year before aging

[MaxGhenis]

Waiting on Max's ruling (d462; d464 is the same call). This moves published target values. Do not merge without that ruling.

Adopted 2026-10-12. The owner session ended, so this PR was taken over and brought up to date:

• merged origin/main, which re-pinned the US feed to 51aa40f (Bind state × AGI-band SOI targets and re-pin the US feed for TY2023 state bands (#940) #1102, issue State top-tail income mass is uncalibrated: CO M+ AGI at 24% of SOI in buildp-acs-local (fails progressive-bracket scoring) #940) and split tests by environment (Refactor CI test execution and wheel inspection #998);
• added the share narrowing that open PR Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 needs;
• re-pinned on the new feed.

The original change is unchanged. Details are under Adoption.

Summary

The pinned US Chronicle feed (51aa40f) stamps five source packages' pinned files as ty2023. That is 26,893 facts from the TY2020 W-2 table and the TY2022 congressional-district, state and IRA tables. 51aa40f is c5e5bf8 plus one package, so it carries the same restamps. Target aging starts from the stamp.

On the route-A national_state surface, this puts the W-2 Box 7 tips amount target at $28.28B. Aged from its data year, the same fact gives $34.29B; the stamp makes it 17.5% lower.

This PR reads restamped facts at their data year for aging and the period contract. PolicyEngine/chronicle#292 (merged 2026-09-28) refuses these builds at the source. This PR stays correct after the feed is re-pinned onto it.

The restamp

Mechanism (Chronicle source_package.py at c5e5bf8):

• artifact_year pins which manifest file a package reads.
• Every {year} label (period, record ids, vintage, legal vintage) renders from --year.
• us/chronicle_feed_scope.json builds these five packages with --year 2023.

Package	File	Data year	Facts stamped ty2023
soi-congressional-district-2022	22incd.csv	TY2022	26,880
soi-w2-statistics-2020	20in04w2all.xlsx	TY2020	5
soi-state-2022	22in54us.xlsx	TY2022	4
soi-ira-roth-contributions-2022	22in06ira.xlsx	TY2022	2
soi-ira-traditional-contributions-2022	22in05ira.xlsx	TY2022	2

Evidence for the data years:

• The files themselves: title cells ("Tax Year 2020", "Tax Year 2022"), and, for the CD file, a match against the TY2022 county file.
• Package metadata and publisher file names.
• For the W-2 tips rows, shared source cells: the ty2023 amount, return_count and taxpayer_count equal their ty2020 twins cell for cell, with the same sha256 and values.

Chronicle#117 reported the CD case in July; the other four came out of this investigation. As of 2026-09-25, IRS had published no W-2 table newer than TY2020 and no CD file newer than TY2022.

When it started. The pin before 2026-09-18 already carried 26,891 of these facts. The 2026-09-18 re-pin added the ty2023 tips amount and return count. Before that, the only tips amount was the ty2020 row, which the code would have aged on the chained SOI wages bridge. That older pin cannot compile on main, so this is read from the code, not observed. The restamped row won latest-vintage selection and aged on the direct 2023 CBO ratio instead.

Which layer owns it

Chronicle "records every fact's publisher reference period" (Chronicle AGENTS.md). PolicyEngine/chronicle#292 refuses a pinned build whose --year changes labels but not what is read. At Chronicle main, the ten scoped pairs these packages fed produce no row, so a re-pin there needs its own decisions (docs/us-chronicle-feed-repin.md, "The 2026-10-04 re-pin").

Microcosm. It is pinned to 51aa40f until that re-pin. This PR is the consumer-side correction for the feed microcosm uses today.

• After a re-pin onto Add county-crosswalked FNS SNAP data as a second congressional-district benchmark #292: a truthfully stamped fact matches neither detection rule, so nothing is corrected. The pinned-feed register test then fails until the stale entries are deleted.
• Rejected alternative: re-stamping the feed at load time. That would also flip a rebase control and change 51 route-A targets.

What changes

us_runtime/source_vintage.py (new).

Detection (detect_restamped_facts). Either rule flags a fact:

• content: its source.source_sha256 is a registered file and its period is after that file's data year;
• structure: its source.raw_r2_key year is earlier than its period.

Publisher projections are exempt. US_LATER_PERIOD_OBSERVATION_EXEMPTIONS (empty) admits truthful later observations, for example a multi-year release keyed by its publication year (BEA's 2024-keyed SAINC.zip has a 2025 column).

Register (US_RESTAMPED_SOURCE_PACKAGES). One entry per package: data year, stamped periods, file, sha256 and evidence. source_vintage_corrections refuses any detected restamp without a matching entry (UnreviewedRestampError).

Guards on the readings that still see the stamp:

• Latest-vintage selection refuses a restamp that would outrank a truthful fact dated after its data year (RestampShadowsNewerVintageError).
• A restamped fact inside the CBO projection series or the SOI chain series is refused (RestampedAgingIndexError).

Correction (apply_source_vintage_corrections). Values are never changed. The stamp is kept in source_vintage_stamped_period.

• For specs backed by a restamped fact, source_period becomes the data year.
• For specs rebased onto a restamped control, so does uprating_to_period.
• New: a restamped row rebased as a share of a restamped total of the same package, stamp and data year (the total its rebase names in soi_share_total_source_record_id) also gets uprating_from_period at the data year. Its uprating_to_period, where its aging starts, stays at the control's period (below).
• It refuses where it cannot vouch for the result:
  • a fiscal-year comparable period that differs from the stamp;
  • any other rebased restamp: no named total, a truthful total, or a total from another package, stamp or data year;
  • a multi-fact spec with a restamped member;
  • a pooled uprating index.

Compile. compile_us_fiscal_target_registry computes the corrections once, checks the aging indexes, passes the corrections to selection, and applies them after the target profile, before aging and the period contract.

Docs. Comments in fiscal_targets.py and target_aging.py, a "Restamped packages" section in docs/us-chronicle-feed-repin.md, and a changelog fragment.

Effect on the pinned feed

This is the release compile: target_period=2024, age_targets=True, the packaged CD crosswalk, then Medicaid substitution. Main is at 51a263726 and the feed at 51aa40f. The dumps and the diff script are in ~/PolicyEngine/_reviews/w2-source-vintage-1030-20261012/compile/ (analyze_main_vs_pr1030.txt).

	main	this PR
compiled targets	33,250	33,250
national_state targets	6,102	6,102
national_state registry	e1f9906bf0e0	61f5cac06310
W-2 Box 7 tips amount (national_state)	$28,280,884,269 (direct, ×1.05579)	$34,287,530,779 (chained, ×1.28003)

national_state: one value moves, the tips amount, by +21.2%. No spec enters or leaves the surface. 53 specs change metadata only:

• 51 Historic Table 2 net-capital-gains return counts rebased onto the CD US row. They now read as a same-year TY2022 rescale.
• The 2 state_2022 counts. Counts do not age.

Full surface: 13,176 CD-file dollar targets age from TY2022. The moves below are relative to aging from the data year under the current series policy.

Measures	Move
The 23 measures on the CBO AGI series (AGI, income tax, EITC amounts, interest, dividends, pensions, SALT and others)	+3.05%
Net capital gains: the SOI chain records the TY2022-to-TY2023 fall	−23.9%
Qualified dividends: mostly a series switch	+8.4%
Schedule C and partnership income: mostly a series switch	−0.5%

With no SOI bridge for qualified dividends, Schedule C or partnership income, aging falls back to the AGI chain from 2022.

13,614 count specs change metadata only, and so do 9 rebased counts that are CD-classified and full-surface only.

Every figure except the hashes and the two target counts is the same as on the old c5e5bf8 feed (5,694 targets, d315c75804ef → 884bc45ef335).

Merge order with #1036, #1040 and #1224

#1036 chooses the capital-gains control by concept. #1040 (stacked on #1036 and carrying #1224's commits) makes the CD capital-gains rows shares of the CD US row times the Table 1.4 control. Both wait on Max (d468, d539). Each order was compiled on a local merge of this branch:

	#1036 alone	#1036 + #1030	#1040 alone	#1040 + #1030
compiled targets	33,250	33,250	31,784	31,784
national_state	882f4764a248	9ce9c3ff865f	84504a7afd57	d29c1e6d43e3
full	f09571684885	b71c84f41821	6e1ac91262bc	de2f83baa9b7
specs with a control correction	—	0	—	0
admitted restamped shares	—	0	—	974

With #1036 alone, every value and counter matches main + #1030. The 51 Historic Table 2 counts rebase onto Table 1.4, so the 60 control corrections, and the 51 metadata-only national_state changes, are gone.

With #1040, all 974 CD capital-gains shares are admitted and keep exactly #1040's values. The CD state capital-gains amounts sum to $1,270.86B either way. The −23.9% net-capital-gains line above disappears, and 12,200 CD dollar targets move, the same AGI-series and series-switch moves as above. The 51 Historic Table 2 counts no longer change, because their control is Table 1.4.

Without the narrowing, #1030 refuses every compile that carries #1040's shares. On the local merge, #1040's test_congressional_district_capital_gains_ignore_the_package_stamp passes with the narrowing and fails with #1030's original blanket refusal ("…and was rebased; review the rebase…").

On the local #1040 + #1030 merge, the pinned-feed run of test_us_fiscal_targets.py and test_us_source_vintage.py gives 246 passed and 2 failed. The two failures are pure pin values, the full version and the counter below. The order-free test, the register test, the tips test and #1040's own pinned tests all pass.

Whichever lands second must re-pin these #1030 pinned values; the order-free tests need no change:

• the registry count, national_state version and docstring in test_pinned_feed_national_state_surface_restores_the_fences;
• the counter in test_pinned_feed_corrects_the_translated_congressional_district_specs:
  • after Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040: 10,900 / 11,772 / 1,300 / 1,350 / 2 / 1, in the test's key order (from 11,772 / 12,208 / 1,404 / 1,404 / 2 / 1);
  • after Choose the capital-gains rebase control by concept and period, not feed order #1036 alone: unchanged;
  • 60 control corrections become 0, and 0 admitted shares become 974 after Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040;
• the figures in docs/us-chronicle-feed-repin.md "Restamped packages" and the changelog.

Adoption (2026-10-12)

• Merge of origin/main (610 commits). Three conflicts:
  • the _latest_dynamic_target_references docstring now carries both State top-tail income mass is uncalibrated: CO M+ AGI at 24% of SOI in buildp-acs-local (fails progressive-bracket scoring) #940's per-vintage state AGI bands and the restamp-shadow guard.
  • the pinned-feed fixtures moved into test_support/microcosm_build/us_fiscal_targets.py. pinned_feed_facts lives there now and the surface fixture builds on it.
  • test_us_source_vintage.py moved to tests/engine_free/us/. tools/ci_test_plan.py verify passes.
• Share narrowing (bab55cb97), adapted from the reviewed patch in ~/PolicyEngine/_reviews/cd-cg-concept-20260927/lane-a/:
  • Under Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 every one of the 974 CD capital-gains specs is a restamped fact carrying uprating_factor, so Read restamped Chronicle facts at their data year before aging #1030 as written refused every pinned compile (P1 in Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040's review).
  • A share divides a row by the US row of the same restamped file, so the stamp cancels, and its level and period are the Table 1.4 control's. Its aging must therefore start at uprating_to_period (2023). Starting it at 2022 would apply the Table 1.4 2022-to-2023 fall twice (×0.761).
  • The refusal message now names the share total and reading period it rejected.
• Shadow guard and State top-tail income mass is uncalibrated: CO M+ AGI at 24% of SOI in buildp-acs-local (fails progressive-bracket scoring) #940's bands (03ceca6ad, from the round-3 review). A state AGI band's selection key ends in its period, and State top-tail income mass is uncalibrated: CO M+ AGI at 24% of SOI in buildp-acs-local (fails progressive-bracket scoring) #940 then keeps one whole vintage per state and measure. The guard compared candidates per key, so it could not see a restamped band vintage displacing a truthful vintage of another period or other bounds. It now compares flagged bands per state and measure. No restamped package on the feed carries band rows (checked), so no compile changes. The new test fails on the previous guard.
• Docstring: the module no longer says the CD row wins the capital-gains control tie (Choose the capital-gains rebase control by concept and period, not feed order #1036 makes that impossible). It says a restamped control keeps a selection its stamp won, which holds under either rule.
• Re-pin on 51aa40f. test_pinned_feed_capital_gains_returns_control_reads_its_data_year named the CD US row as the control. It becomes test_pinned_feed_rebased_specs_read_restamped_inputs_at_their_data_year, which holds whichever control the compile picks:
  • every spec rebased onto a restamped control reads that control's data year;
  • every rebased restamp is a same-package share whose aging starts at the control's period.

Invariants

• Values untouched. The correction never changes a spec's value, name, period, order or surface membership (Hypothesis property; pinned diff).
• Exactness. A spec changes if and only if it is backed by, or rebased onto, a corrected fact at that fact's stamp. Every moved period lands on the data year. It is idempotent (property).
• Share admission. A rebased restamp is admitted if and only if its share total is a correction of the same package, stamp and data year, and its uprating_from_period is the stamp or the data year. Otherwise the compile refuses (exact oracle in the property).
• Aging start. uprating_from_period moves only for an admitted share. uprating_to_period moves only for a restamped control, never for a share (property).
• Differential, W-2. A restamped fact ages exactly as its honest twin at the data year (synthetic compile test). On the pinned feed every affected spec's aging start is the data year.
• Differential, shares. An admitted share ages to exactly the value of the same share stamped truthfully at 2022, on the direct CBO ratio from the control's period (new unit test). It does the same for Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040's compile-level stamp test, and for all 974 shares on the pinned feed.
• Detection rule. A fact is detected exactly when it is an observation and matches the content rule or the structure rule (property). On the pinned feed both rules agree on all 26,893 rows.
• Fail closed. The compile refuses in each of these cases:
  • an unregistered restamp, or one whose stamp or file year disagrees with its entry;
  • a restamp that would shadow newer data;
  • a restamp inside an aging index;
  • a restamp reaching a spec the correction cannot vouch for.
• Counts never age. No count value moves (pinned diff).

Tests

Run locally with the pinned feed present, at the heads noted. CI has no feed and skips the pinned-feed tests. Logs are in ~/PolicyEngine/_reviews/w2-source-vintage-1030-20261012/tests/.

Run	Result
test_us_fiscal_targets.py, test_us_source_vintage.py, test_us_spine_blindness.py (at 03ceca6ad, the head)	705 passed, 0 skipped, pinned-feed tests included
With MICROCOSM_US_CHRONICLE_FACTS set and the us extra installed (at the head): test_release_target_parity.py, test_us_acs_local_release_tool.py, test_us_acs_local_sparse_cd.py, test_us_chronicle_feed.py, test_us_fiscal_refresh_builder.py (both whole-registry pinned-feed compiles included), test_us_modal_stage_puf_support_base.py, test_us_release_gate_preflight.py, test_us_soi_state_agi_bands.py, test_us_congressional_district_{vintage,geography,vintage_crosswalk}.py	804 passed; 1 skipped (it needs a built CD plan registry)
On the local #1040 + #1030 merge: #1040's 15 capital-gains share tests, including the stamp test	all pass
ruff check, ruff format --check, tools/ci_test_plan.py verify	clean

New tests in this round (test_us_source_vintage.py):

• an admitted same-package share and its idempotence;

• seven parametrized refusals: no total, a truthful total, another package, another stamp, another data year, another reading period, no reading period;

• a value-level differential: one share stamped ty2023 then corrected, and the same share stamped truthfully at 2022, both aged to 2024. The aging start at the data year is pinned as a ×(T1.4 2023/2022) error;

• the Hypothesis property now draws uprating_factor, uprating_from_period and share totals in three modes. Free draws them at random. Well-formed gives each rebased restamp its own same-vintage total. Near miss gives it exactly one defect among package, stamp, data year and reading period. Two runs of 500 examples at the head gave:

  • 79 and 55 first-pass admitted shares;
  • 70 and 65 refused calls;
  • 114 and 53 control corrections.

  The counts are in tests/property_coverage.txt.

• test_restamp_shadow_guard_compares_state_agi_bands_per_state_and_measure (test_us_fiscal_targets.py).

Mutation sweep (executed). Ten mutants of the narrowing, run against this PR's unit tests plus #1040's stamp test on the local merge (mutants/report.md):

Mutant	Killed by the suite	Killed by the property alone
M1 blanket admission	yes	yes
M2 aging start moves to the data year	yes	yes
M3 uprating_from_period not moved	yes	yes
M4 data year not compared	yes	yes
M5 reading period not checked	yes	yes
M6 package not compared	yes	yes
M7 stamp not compared	yes	yes
M8 missing total admitted	yes	yes
M9 reading period: data year only	yes	yes
M10 blanket refusal (pre-narrowing)	yes	yes

The sweep ran at local-merge head c50c08663, which carries this branch at 4bcf9cc1c. The two files it mutates and runs, source_vintage.py and test_us_source_vintage.py, are byte-identical at the head 03ceca6ad. M2, M9 and M10 also fail #1040's stamp test and the new aging differential. M10 is #1030's original blanket refusal.

Not changed here

• Historic Table 2 capital-gains returns control. On main the CD US row wins a same-period tie on feed order. Choose the capital-gains rebase control by concept and period, not feed order #1036 (d468) chooses the control by concept instead; with it, no restamped row is a capital-gains control.
• SOI_CONGRESSIONAL_DISTRICT_RECORD_SET_ID names the ty2023 record set, so it must change at a re-pin onto Chronicle main.
• BEA regional state personal income stamps CY2024 data as cy2023, and neither rule can detect that direction. No target compiles from it, but bea_regional.state_wages_salaries is a deferred parity family. Activating it before a re-pin would calibrate 2024 wages as cy2023.

Review

• Rounds 1 and 2 (2026-09-27, before adoption): independent Opus 5.5 agents found no P0 or P1. Round 2 approved with nits, all closed in 94f055a6d.
• Round 3 (adoption): GPT-6.1 Sol on a Subfleet hard-tier lane, a read-only static review of f87844fa8 (review-sol.md in the evidence folder). APPROVE WITH NITS, no P0-P2. Its findings:
  • it checked the narrowing (including self-denominator and twin totals, simultaneous share and control corrections, and idempotence), the other rebase families, the property oracle, merge order, pins and merge preservation, and found no defect;
  • P3: the mutation evidence was produced at a later head than the one reviewed. The final sweep is now tied to the head (above);
  • a dormant limitation: the shadow guard could not compare state AGI-band vintages. Fixed in 03ceca6ad.
• Round 3 delta (f87844fa8..03ceca6ad: the guard fix, test-only changes and one docs line): APPROVE, no P0-P3 (review-sol-delta.md). It confirmed that the coarser band key cannot cause a false refusal on main, Choose the capital-gains rebase control by concept and period, not feed order #1036 or Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040, that (state, measure) is the selector's competition grain, that each near miss changes exactly one admission condition, and that the relaxed CD assertion keeps main's check.

axiom: n/a: microcosm target-compile infrastructure (fact vintages and aging), not a policy rule

🤖 Generated with Claude Code