Test that a fact's period is the tax year its source table names

[MaxGhenis]

Summary

Adds tests that compare a fact's period with the tax year its source table's title names. No package, parser or schema changes.

The case behind it: the microcosm US feed carried five facts with period 2023 and vintage tax_year_2023 whose source is IRS SOI Table 4.B for Tax Year 2020 (20in04w2all.xlsx). #292 fixed the package on main. These tests check the result against the publisher's own title, and they catch a wrong literal year, which #292's guard cannot see.

What I checked at the source (10 October 2026)

• IRS's Form W-2 statistics page (last reviewed 27 January 2026) links Table 4 for 2020 and 2019 only. 21in04w2all.xlsx through 24in04w2all.xlsx return 404. There is no TY2023 Table 4.B to add. IRS's prior-releases page carries tax years 2008 to 2018 in one workbook (18inallw2.xls), so 2020 is the latest year published.
• A fresh download of 20in04w2all.xlsx has the sha256 the manifest pins (1178d776…cfc442f).
• Cell A1 of sheet "Table 4.B" reads "Table 4.B. Summary of Items for Taxpayers with Form W-2, by Return and Earner Type, Tax Year 2020".
• The five values are in that sheet (money amounts in thousands):

Fact	Cell	Published value
Box 7 social security tips, returns	B13	6,038,613
Box 7 social security tips, taxpayers	C13	6,105,713
Box 7 social security tips, amount	D13	$26,786,522,000
Box 12 D 401(k) elective deferrals, amount	D22	$277,859,181,000
Box 12 AA designated Roth contributions, amount	D41	$32,302,509,000

How the ty2023 rows came about

At c5e5bf8, the commit microcosm pins, packages/irs_soi/w2_statistics_2020/source_package.yaml set artifact_year: 2020 and rendered period, record_set_id, source_record_id_prefix, vintage and legal_vintage from {year}. Microcosm's scope built the package at --year 2023 for three record sets, so the Tax Year 2020 cells went out with ty2023 labels.

On main today the package builds the same five TY2020 facts at every --year from 2019 to 2025 (a test below asserts it).

What this adds

tests/test_chronicle_source_table_year.py:

• Registry test. For every pinned package whose artifact.source_table names exactly one tax year, every tax-year fact built at the artifact year must carry that year as its period, in its tax_year_<year> vintage and in the ty<year> tokens of its record ids. One package qualifies today (irs_soi/w2_statistics_2020). HMRC titles such as "tax year 2023-24" name two years and are left alone.
• W-2 title. The declared source_table equals cell A1 of the workbook, so the year the registry test reads is IRS's.
• W-2 values (differential). The five facts equal a direct openpyxl read of the sheet, and both equal the published values above.
• W-2 at every build year. --year 2019, 2021, 2022, 2023, 2024 and 2025 build facts identical to the 2020 build.
• The title reader. Sixteen example titles, plus every combination of 3 prefixes, 5 suffixes, 5 years and 7 connectors: one named year reads back, and two different years never read as one.

docs/agent-source-package-harness.md gains a paragraph on the new check under "Pinned artifacts and year labels".

Invariant

When a package's source table title names exactly one tax year, every tax-year fact the package builds at its artifact year has that year as its period, in its tax_year_<year> vintage and in its record ids.

Mutation checks (run locally, then reverted)

Mutation of the W-2 package	New tests	#292's test_chronicle_artifact_year_restamp.py
The c5e5bf8 file ({year} labels)	6 fail (every non-2020 build year)	not run
period: '2023' as a literal	2 fail	all pass
vintage: tax_year_2023 as a literal	2 fail	not run

The second row is the gap these tests close: a literal wrong year is the same file read under the same labels at every build year, so a guard that compares one build with another has nothing to flag.

Related

• feed/us-c5e5bf8-w2-2020 (f98acf4, tag microcosm-us-feed-w2-ty2020-v1) is c5e5bf8 plus only the W-2 package file as Refuse pinned-artifact builds that only relabel another year (#117) #292 left it. Stamp the W-2 item facts with Tax Year 2020; the 2024 tips target moves from $28.28B to $34.29B microcosm#1192 re-pins the US feed to it: the 2024 W-2 tips target moves from $28,280,884,269 to $34,287,530,779, and no other target changes. It is a pin base, not for merging.
• At main (3dce46a6), ten pairs of microcosm's pinned scope are no longer declared: these three W-2 pairs, the congressional-district file, the two IRA tables and four state_2022 rows. The W-2 pairs move now; the others are microcosm#1030's.

Tests

• uv run pytest tests/test_chronicle_source_table_year.py: 27 passed (10.6 s).
• uv run ruff check chronicle policyengine_chronicle db scripts tests: clean.

🤖 Generated with Claude Code