chore(canonical-key): retire substrate-reader legacy fallback branches (ROADMAP L178)

[cipher813]

ROADMAP: L178 — Retire canonical-key backward-compat shims (Wave-1 cleanup, P2)

Companion to alpha-engine-data #271.

Gate fired 2026-05-18. Canonical latest.json sidecars produced for all three substrates on 2026-05-16 ~08:17–08:20 UTC; zero legacy log emissions in the research-runner Lambda over the last 7 days.

Removed

• data/substrate/reader.py::read_news_aggregates + read_analyst_revisions — legacy {as_of_date}.parquet fallback + now-unused as_of_date positional arg.
• read_insider_transactions_window — legacy per-filed_date walk-back loop (was window_days+1 GETs against {date}.parquet keys); now a single canonical sidecar read + window filter on filed_date.
• Stale docstring note on _read_via_latest ("so legacy-fallback callers can degrade").

Internal call sites updated

• SubstrateReader.snapshot_for_ticker + read_substrate_for_population — drop as_of_date arg from the two news/analyst readers (it was only for the retired legacy fallback). as_of_date continues to flow to read_insider_transactions_window for window filtering (a legitimate use).

Tests

Existing tests were planting legacy {date}.parquet files and expecting them to be read — that was the canonical contract this PR retires. Re-shaped to canonical fixtures:

• Added _put_canonical(s3, prefix, df, run_id) helper that mirrors the producer's run_id + latest.json shape.
• 4 round-trip / rollup tests migrated to _put_canonical.
• Renamed test_falls_back_to_legacy_date_key_when_no_sidecar → test_legacy_date_key_is_ignored_when_no_sidecar and flipped its assertion (legacy key alone → empty). Net regression guard.
• Added test_insider_legacy_per_date_keys_are_ignored — two legacy per-filed_date parquets with no canonical sidecar must yield empty (no walk-back).
• Tightened read-budget pin in test_only_one_s3_read_per_parquet_for_whole_population from "≤100 calls" to "== 3".

Suite: 1373 passed (+1 regression guard), 45.6s.

Public API unchanged in shape

data.substrate exports — SubstrateReader, SubstrateSnapshot, read_substrate_for_population — keep identical signatures. Gitignored fetch_data callers don't need a coordinated edit.

Composes with

• alpha-engine-data #271 (companion / producer-side cleanup).
• alpha-engine-research feat(substrate): migrate reader to canonical latest.json indirection #175 / alpha-engine-data #234 (canonical-shape migration this PR follows up on).

🤖 Generated with Claude Code