S6 — Detect coordinate-registry drift against the Appwrite Seam Contract (C-57) #187

Part of epic #181. Closes register C-57 (Tier 3). Depends on S3.

Background

views_postprocessing/unfao/appwrite_env.py declares 15 environment-variable names. Their authority is the Appwrite Seam Contract's coordinate registry, which lives in another repository:

../views-appwrite/docs/ADRs/platform/coordinate_registry.toml

The registry is deliberately referenced, never copied — its own header forbids copying, and this repo's CLAUDE.md states the same rule platform-wide. That is the right call: one owner, no duplicated values, no drift-by-fork.

But it leaves a gap that C-57 names precisely: nothing mechanical will tell you when the two diverge. The registry is versioned ([meta] version = "1.3.0", ratified by þing-02 on 2026-07-31) and it changes — it has already retired one contract name (see S3) and it carries five planned secret slots that will land:

[secret.APPWRITE_READ_API_KEY]     status = "planned — operator issues (D4)"
[secret.APPWRITE_WRITE_API_KEY]    status = "planned — operator issues (D4). Blocked on the create_* gating (§5.5)."
[secret.APPWRITE_PROVISION_API_KEY] status = "planned — operator issues (D4). NEVER given to a long-running process."

Checked 2026-08-01: there is no live drift today. All 15 names this repo declares are present in the registry with matching class, and the secret slot it uses (APPWRITE_DATASTORE_API_KEY) is still the current one. So this story builds a detector, it does not fix a break. Doing it now, while the answer is known-good, is the cheap moment — the alternative is discovering the drift during a failed delivery.

Work

Declare, in appwrite_env.py, the registry version this repo's declaration was verified against:

#: The Appwrite Seam Contract version these names were verified against.
SEAM_CONTRACT_VERSION = "1.3.0"

That is a version string, not a coordinate value — it does not copy the registry, it records which edition of it was read. Cite the pinned URL alongside it.

Then add a gated drift test that, when a views-appwrite checkout is resolvable, parses the registry and asserts:

1. every name in CONNECTION_ENV / PROD_FORECASTS_ENV / UNFAO_ENV exists in the registry;
2. each is declared with the class this repo treats it as (connection / target / secret) — the registry declares class explicitly and forbids inferring it from the prefix, so read it, do not derive it;
3. the registry's [meta] version equals SEAM_CONTRACT_VERSION, with a failure message that says "the registry moved to X; re-verify this repo's declaration and bump the constant".

Check 3 is the one that earns the story. Checks 1 and 2 catch a rename; check 3 catches anything else, including additions this repo ought to adopt.

Never assert on a value. The registry contains non-secret coordinate values; this test must compare names, classes and the version only. Copying a value into a test is the same violation as copying it into code — tests/test_redaction_guard.py governs the surrounding discipline.

Gating. Use the same declared resolution S7 establishes for views-datafactory. Do not hardcode a path; do not silently pass when the sibling is absent. Skip with a reason that names the env var to set.

Acceptance criteria

• SEAM_CONTRACT_VERSION declared, with a pinned-URL citation.
• The drift test passes today against registry 1.3.0.
• It fails, with an actionable message, if a declared name is missing, misclassified, or the registry version moves.
• No coordinate value appears anywhere in the test or the module.
• The test skips cleanly (never errors) when views-appwrite is not resolvable.

Testing

Suggested home: tests/test_env_declaration.py (owns this module) or a new tests/test_seam_contract_drift.py if the gating machinery makes the former unwieldy. Prefer extending the existing file — one concept, one home.

Prove the detector bites, per this repo's standing practice:

def test_the_drift_check_would_catch_a_rename(tmp_path):
    """A gated test that cannot fail is decoration —
    cf. test_clone_readiness.py::test_the_guard_would_actually_catch_a_violation."""

Feed it a synthetic registry with one name renamed and assert the check fails. That part needs no views-appwrite checkout, so it runs in CI.

Validation:

ruff check .
pytest -q tests/test_env_declaration.py
pytest -q                                   # with ../views-appwrite present: drift test runs
grep -rn "691b14fc\|fra.cloud.appwrite" tests/ views_postprocessing/   # must be empty — no values copied

Dependencies

Depends on S3 — both edit appwrite_env.py's docstring and citations, and S3 establishes the current contract name this story's constant refers to. Sequence them to avoid a conflict.

Uses the resolution helper from S7 if S7 lands first; otherwise S7 adopts whatever this story establishes. Whichever is second must not leave two ways to find a sibling repo.

Files

• views_postprocessing/unfao/appwrite_env.py — the declaration
• ../views-appwrite/docs/ADRs/platform/coordinate_registry.toml — the authority (read only)
• tests/test_env_declaration.py — the governing test file
• tests/test_redaction_guard.py — the no-values discipline
• Register C-57