Add academic_year period type to the source-package contract

[juaristi22]

Closes #131.

Lane: ledger-contract-maintainer (.github/ledger-agents.yml) — judges ledger-contract + ledger-boundary. This is the one contract change the UK target migration needs, isolated per #131 so no data wave drags through contract review. Unblocks the SLC packages in #132 (wave 1) and #133 (slc_repayments).

What changed

• ledger/core.py — academic_year joins ALLOWED_PERIOD_TYPES, with a comment documenting the period-integer convention for split-label years: the stored integer is the opening year of the publisher's label — UK FY2024-25 → fiscal_year 2024 (the existing packages/hmrc/vat_firm_targets_2024_25 precedent), AY 2024/25 → academic_year 2024. Publishers that label a fiscal year with a single year keep that label year (US federal FY2025 → 2025).
• docs/schemas/consumer_fact.v1.schema.json + policyengine_ledger/schemas/consumer_fact.v1.schema.json — byte-identical description added to period.type documenting the vocabulary and the opening-year convention. Deliberately a description, not an enum: the single enforcement point for the vocabulary stays validate_fact; the schema documents, it does not duplicate the gate.
• Tests — test_ledger_core.py: academic_year facts validate; unknown period types still fail with malformed_period. test_ledger_consumer_contract.py: full round trip — two academic_year facts → write_consumer_facts_jsonl → build_consumer_artifact (profile shipped through the artifact) → load_consumer_artifact (schema-validates every row) → resolve_profile_targets at {type: academic_year, value: 2024} resolves the exact fact on fact basis.

Behavior notes

• CONSUMER_FACT_SCHEMA_SHA256 derives from the packaged schema bytes, so it moves with this change. Newly built artifacts carry the new sha; load_consumer_artifact will reject artifacts whose manifests pin the old sha — the designed exact-contract behavior. Existing consumer artifacts need a rebuild with the matching wheel.
• Period-integer alignment downstream (e.g. policyengine-uk-data's AY 2024/25 → calendar 2025 mapping) is a consumer concern; facts store what the publisher asserted.
• No existing package or fact changes behavior: the vocabulary only widens, and the schema edit is documentation-only for row validation.

Checks

• uv run ruff check ledger policyengine_ledger db scripts tests (repo-pinned, CI scope) — clean.
• Full uv run pytest -q — green on this branch (614 passed, 1 skipped).
• Deterministic checks per the lane: schema validation, consumer-contract validation, package import compatibility, raw-facts boundary validation — all exercised by the suite above.

🤖 Generated with Claude Code

[juaristi22]

Adversarial review complete — verdict: ready-with-nits, all findings addressed in 2b2dab1.

What was attacked and survived: schema copies byte-identical with self-deriving sha (rejection of old-sha manifests reproduced at runtime); no other period-type enumeration anywhere in the repo; the UK FY2024-25→2024 precedent verified against the committed hmrc package; lane compliance clean on both judges.

What the review caught and is now fixed:

• The round-trip test proved period-type-agnostic plumbing, not the vocabulary gate — a probe with a bogus school_year type passed it end to end. The test now asserts validate_facts on the academic-year facts directly.
• No negative existed for cross-type resolution anywhere in the repo; the test now proves resolving the academic-year artifact at {fiscal_year, 2024} raises PeriodContractError — the silent-misuse family (populace#212) that UK sources make likely, since fiscal/tax/academic years share integer values.
• The core comment now cites an attested US example (cbo FY2024→2024) and warns that the EES helper _academic_year_end names value columns by end-year — source-layout naming that must not leak into fact periods when the SLC packages are written. Schema description gains the single-label-year clause (both copies, byte-identical).

🤖 Generated with Claude Code

[vahid-ahmadi]

Small and well-shaped: one vocabulary entry, the same description added to both copies of the schema (good — those two files drifting apart would be a nasty bug), a positive and a negative test on the validator, and a round-trip test through the consumer artifact including the PeriodContractError on a mismatched type. The convention itself — store the opening year of a split label, keep the label year when the publisher uses one — is the right call and is now written down in the place people will actually read it.

Two things:

1. The ALLOWED_PERIOD_TYPES comment cautions about a helper that doesn't exist.

Caution: the EES helper _academic_year_end (ledger/sources/rows.py) names value
COLUMNS by the academic year's END year

I can't find _academic_year_end anywhere — not on main, and not in #137, #139, or #141. If it's landing in a later PR, the forward reference will read as stale until then; if it was renamed or never merged, the caution points at nothing and the reader can't check the claim. Either way the most valuable half of that comment (column naming uses the END year, fact periods must not) survives without the symbol name, so I'd either drop the identifier or link the PR that introduces it.

2. The round-trip test asserts the convention on a fact that couldn't exist. test_academic_year_rows_round_trip_through_consumer_artifact takes _soi_agi_fact() — IRS SOI adjusted gross income — and gives it academic_year periods, with source_record_id strings like irs_soi.ay2023.table_1_1.all.adjusted_gross_income. It exercises the plumbing correctly, but as documentation it teaches the wrong thing: AGI is never an academic-year quantity, and someone reading this test to learn when to reach for the new type gets no signal. A neutral synthetic fact, or one shaped like the SLC/EES student-support rows this vocabulary is actually for, would carry the same coverage and explain itself.

Landing the vocabulary ahead of any producer is the right sequencing for a contract change, so no objection there — just worth a line in the description saying which package will be the first consumer (the SLC rows in #131, I assume, per the checklist row in #141).

[juaristi22]

Both review points addressed in 60e0a8f — thank you, both were real.

1. _academic_year_end does exist — the comment was pointing at a dead path. The helper has been in the harness since the very first commit (376d4cc) and now lives at chronicle/sources/rows.py:971; the caution cited the pre-rename ledger/sources/rows.py, which is why searching came up empty. The comment now cites the current path and shows the behavior inline ("2024/25" → 2025), so the claim is checkable: the EES lane names value columns by the END year while this vocabulary stores the OPENING year — exactly the leak the caution exists to prevent when the SLC packages get written.

2. The round-trip test now teaches with the fact it was built for. The fixture is no longer AGI-in-costume: it's shaped like the SLC/EES student-support rows (slc.ay2023.student_support.maintenance_loan_recipients — maintenance-loan recipients, England, person entity, count unit, administrative provenance, AY 2023/24 → academic_year 2023), with the profile side switched to a uk/slc target. Same coverage as before — the vocabulary gate via validate_facts, the JSONL round trip, resolution at {academic_year, 2024}, and the cross-type PeriodContractError probe — but a reader now gets the when-to-use signal for free. 46 contract tests pass.

🤖 Generated with Claude Code