Tracking: FAO input-integrity epic — execution checklist

[Polichinel]

Epic: #51 · branch: sprint/fao-input-integrity

Execution checklist for the FAO input-integrity sprint, corrected to the post-/falsify design (representation-agnostic invariants in delivery/, pandas isolated to unfao/extraction.py, guards called-not-inherited). Cross off in order.

Order of execution

• S0 — Scaffold the delivery/ contract package + unfao/extraction.py seam + package hygiene #61 — S0 Scaffold delivery/ + unfao/extraction.py seam + package hygiene · implementation (foundational)
• S1 — Coverage contract: complete-coverage invariant + cell-count logging (C-34) #53 — S1 Coverage contract: complete-coverage invariant + cell-count logging (C-34) · implementation
• S2 — Observed-range guard: no fabricated zeros, clip to last_valid_month_id (C-26) #52 — S2 Observed-range guard: no fabricated zeros, clip to last_valid_month_id (C-26) · implementation blocked (pipeline-core companion: surface last_valid_month_id)
• S3 — Forecast-file identity invariant (C-25) #54 — S3 Forecast-file identity invariant (C-25) · implementation
• S4 — land_gaul completeness pin: 64,736 + 82 excluded gids + FAO disclosure (C-30) #55 — S4 land_gaul completeness pin: 64,736 + 82 excluded gids + FAO disclosure (C-30) · implementation (after S1; live run gated on views-models#127 + datafactory land_gaul)
• S5 — Structured delivery provenance invariant (C-15, supersedes #12) #56 — S5 Structured delivery provenance invariant (C-15, supersedes Add shapefile version and error count to upload metadata (C-15) #12) · implementation
• S6 — End-to-end input-integrity test suite (through the manager seam) #57 — S6 End-to-end input-integrity test suite (C-25/26/30/34/15) · testing

Dependency graph

#61 S0 ──► #53 S1 ──► #55 S4
       ├─► #52 S2  (also blocked on pipeline-core companion)
       ├─► #54 S3
       └─► #56 S5
{#53,#52,#54,#55,#56} ──► #57 S6

Design contract (enforced)

tests/test_input_integrity_design_contract.py (xfail-strict) encodes the three tightenings: ① two homes (delivery/ vs unfao/extraction.py), ② primitives-not-Protocol, ③ called-not-inherited (manager LSP/SDP/SAP deferred to C-40). Each stub flips RED when its piece is built correctly, forcing the marker off.

Cross-repo dependencies

• pipeline-core companion (from S2 — surface last_valid_month_id).
• views-models#127 (REGION → land_gaul) + views-datafactory land_gaul region (register D-10) — gate S4's live run.

Related / superseded / deferred

• Parent umbrella [UMBRELLA] FAO global delivery: lookup-based enrichment (ADR-011) + global coverage #20. Supersedes Add shapefile version and error count to upload metadata (C-15) #12 (C-15). Same-root cure: C-40 (manager de-inheritance — deferred). Not in this epic: timeouts (C-13 Add timeout to Appwrite download and upload operations (C-13) #11, C-28), multi-store (C-33), the per-cell coverage mask (Case B).

Done when

Epic #51's acceptance criteria hold: invariants in a pandas-free delivery/, pandas isolated to unfao/extraction.py, guards called-not-inherited, all five checks enforced, package hygiene done, design-contract stubs real, suite green — the pipeline is ready for the land_gaul global switch with no silent-bad-data paths.

[Polichinel]

Delivered and merged to development via #64 (input-integrity sprint S0–S6). ruff clean, 126 passed / 44 xfailed. Closing — the auto-close keyword did not fire because #64 merged into development, not the default branch. Live-run validation of the residual contracts (C-25 identity name/loa, C-43 enrichment equivalence) is tracked in the risk register and exercised by the go-global run (views-models#127).