Manifest must declare {maturity, source, required-schema-version} + stamp them — faoapi fail-visible selection contract (faoapi ADR-033 / #244)

[Polichinel]

Filed by the faoapi seat. Cross-repo contract needed to unblock the FAO global delivery (run-0 incident, faoapi #243).

Why

faoapi is adding fail-visible selection gates (faoapi ADR-033, epic #244): it will refuse to serve a run to FAO unless the run manifest declares the run is (a) production-grade, (b) stamped with a real source, and (c) renderable by the deployed schema — surfacing the reason in /health + /provenance rather than silently serving stale/test data (which is exactly what happened with run-0: a 139-day test artifact served behind 200 OK). This is faoapi's consumer-side enforcement of views-models ADR-017 §5 tier-rule.

For a delivered run to actually reach FAO, the producer (this repo — the un_fao manager + the vpp ADR-013 wire manifest) must declare that metadata on the manifest.

Ask — three declared fields on the run manifest

1. maturity (graduate / candidate / … per views-models ADR-017). faoapi serves only graduate. Today rusty_bucket is candidate/shadow → correctly refused until it graduates (views-models #146). (Interim: today's deployment_status: deployed accepted during the dual-vocabulary window.)
2. source / provenance — the producing ensemble/pipeline, not "unknown". faoapi refuses unstamped provenance (source="unknown" is what's live today).
3. Required schema/contract version — extend the existing manifest contract_version with the served-schema version faoapi must be able to render; faoapi refuses a run it can only render degraded.

Work

• Amend vpp ADR-013 (the wire contract) to add these declared fields to the run manifest.
• Stamp them in the un_fao manager / wire sink (views_postprocessing/unfao/managers/unfao.py) when building the manifest.

Related decision on this repo's side — C-169 (historical co-delivery)

In contract mode, _save_contract ships the forecast run only; the global historical is coverage-validated (_check_coverage) but not uploaded. So faoapi's /historical/* + bulk s_actual go stale under a contract cutover (faoapi register C-169, ADR-028 pointer). Decide: add historical delivery to the contract path, or record that FAO stops receiving historical.

Refs

faoapi ADR-033, faoapi #244 / #243; views-models ADR-017 (maturity), #146 (rusty_bucket graduation), #127 (region → land_gaul); vpp ADR-013.

Acceptance

• vpp ADR-013 amended: manifest declares {maturity, source, required-schema-version}.
• un_fao stamps all three on the manifest.
• C-169 (historical co-delivery) decided and recorded.

[Polichinel]

Reframed (2026-07-28) — faoapi does not gate on maturity; eligibility stays upstream

Following the views-models seat's ADR-017 reframe: faoapi is the delivered half of ADR-017's "in production = graduate AND delivered," so it must not re-judge eligibility. faoapi serves the newest complete manifested run for its line and reads no deployment/maturity label. The manifest fields are still wanted — but faoapi's use of each changes:

• source — faoapi verifies present (refuses an unidentifiable run — audit, not eligibility) and surfaces it.
• required schema version — faoapi verifies renderable (capability gate).
• status/maturity — faoapi surfaces it (informational, in /provenance + a response flag) so an interim/shadow run isn't mistaken for graduated production; it is not a faoapi gate. It's carried for provenance/audit and for ADR-017's upstream governance.

So the eligibility decision (what may reach the bucket) stays here / at the delivery boundary, exactly as ADR-017 intends. The C-169 historical co-delivery decision is unchanged. Ref faoapi ADR-033 §2/§8 (revised).