refactor(unfao): S3 — one representation seam; store metadata gets its own home

[Polichinel]

Closes #151 · Epic #148 · Register C-65 closed

What extraction.py actually was

Two unrelated things in one module:

	fate
cells_of, months_of, drop_months_above, unmapped_cell_count	deleted — unreachable since #149, already implemented frame-natively in frame_extraction.py
file_metadata	moved — it unpacks a store document and touches no representation

They shared a module only because both "unpack something", which is not a reason to change together (CCP). ADR-012 called extraction.py "the single pandas-aware module" — the representation change had already landed beside it.

file_metadata moves to unfao/store_metadata.py, sibling of source_metadata.py, so the pair reads producer facts / store facts and each module carries one concept.

Tests followed the code — none were dropped

• test_extraction.py → test_store_metadata.py, keeping the file_metadata cases.
• test_frame_extraction.py was a parity suite proving both seams returned identical primitives — the right test while both existed. With one seam gone parity has nothing to compare against, but the absolute expectations were already written into the assertions ({1,2,3}, [100,101]), so they are now asserted directly. Values unchanged; they simply no longer route through a deleted module to be checked.
• test_input_integrity_e2e.py now feeds the invariants primitives, which is how the delivery actually calls them. It had been building synthetic pandas frames and pushing them through the pandas seam to reach representation-free rules — testing a chain the delivery no longer has, and holding the file's last pandas import hostage to it. Its docstring now names where each representation-specific half is covered (test_frame_extraction, test_historical_builder, test_store_metadata).
• test_input_integrity_design_contract.py ① named extraction.py as "the seam"; now names frame_extraction.py and asserts both halves — the seam exists and its retired pandas sibling has not come back, because two seams for one concept is the CRP violation D-11 predicted.

One note worth keeping

That design-contract file recorded ② "no premature Extractor Protocol (YAGNI/ISP) — a migration, not a coexistence." It is now marked vindicated: the coexistence ended, the second implementation was deleted rather than abstracted over, and a Protocol introduced at the time would have outlived the thing it existed to unify. That is WET-before-DRY paying out, and it is worth having in writing for the next seam.

Verification

ruff clean · 289 passed, 41 xfailed · the 5 failures are the known local pyarrow byte-parity tests; CI authoritative · no file under wire/ or fixtures/ touched.

Register: 71 concerns, 31 open, 40 resolved. Integrity guard green.

🤖 Generated with Claude Code