feat(wave3): price_cache_read_prefixes helper + sf_preflight reader migration + sector_map.json write-both gap fix (ROADMAP L1401)

[cipher813]

ROADMAP: L1401 — predictor/ S3 namespace rationalization Wave 3 — data-repo half of the PR3+ reader migrations + producer-side sector_map.json gap fix.

Three things in one PR

1. Read-side helper (new)

builders/_price_cache_writeboth.price_cache_read_prefixes() — companion to the existing price_cache_write_prefixes. Read order is WRITE order REVERSED: [reference/, predictor/] so the new prefix is consulted first, legacy is the soak-window fallback. PR4 cutover edits both helpers in one lockstep one-line change each.

2. sf_preflight backfill-source-freshness check

Migrated to iterate the helper instead of hardcoding the legacy key. Behavior change: a missing legacy key alone no longer fails the check (post-PR4 state); only when BOTH prefixes are unreadable does it report fail.

3. collectors/constituents.py — sector_map.json write-both gap fix (caught by audit)

sector_map.json is now written to 3 keys: data/ + predictor/price_cache/ + (NEW) reference/price_cache/. PR1 #270's write-both helper scoped only the ticker-parquet writes (yfinance / FRED / chronic-gap); the separately-emitted sector_map.json from this collector wasn't reaching the new prefix on an ongoing basis. The 2026-05-19 22:13Z one-shot backfill made it fresh at that moment — without this fix it would have gone stale after the next weekly producer run, and the read-new-first contract (already shipped in alpha-engine-backtester#230) would silently serve stale data.

Sites NOT migrated in this PR (deferred to a focused follow-up)

The remaining 3 reader sites are more invasive and warrant their own PR now that the helper is in place:

Site	Why deferred
builders/backfill.py (_load_full_cache)	LIST + bulk read across the full 10y tree; needs a careful list-from-new + add-legacy-only-extras pattern
builders/daily_append.py	PRICE_CACHE_PREFIX constant threaded through many per-ticker GETs; mechanical but wide
collectors/slim_cache.py	default-arg propagation; single touch but cross-cuts the slim Wave-4 retirement path — needs sequencing

Each remaining site should iterate price_cache_read_prefixes() and break on first hit (mirrors sf_preflight here).

Audit miss caught

collectors/constituents.py:114 was initially listed as a Wave-3 reader site (per the L1401 "data ×5" list) but is actually a writer site — the ROADMAP entry was mislabeled. Catching this surfaced the missing 3rd write target (the producer-side fix in §3 above). Net result: better than the original scope — the read-new-first contract in alpha-engine-backtester#230 is now safe.

Tests (+4 new, suite 1387 → 1391 green)

• test_read_helper_default_returns_new_first_legacy_second — pins read order.
• test_read_helper_explicit_legacy_returns_new_first_legacy_second — explicit-legacy default semantic.
• test_read_helper_custom_prefix_returns_single — test/override opt-out (mirrors write-side).
• test_sector_map_writes_to_all_three_paths — locks the 3-key write contract with byte-equal bodies.

Composes with

• alpha-engine-data#270 (producer write-both, this PR's prerequisite).
• alpha-engine#197 (IAM ARN add for reference/price_cache/).
• alpha-engine-backtester#230 (Wave-3 backtester reader, sibling PR — and the consumer that needed §3's fix).
• Wave-3 PR4 cutover (drops the fallback branch in both helpers).

🤖 Generated with Claude Code