S6 (#187) — detect coordinate-registry drift; existence is not reachability

[Polichinel]

Closes #187. Closes register C-57. Part of epic #181.

The gap

The registry is the authority for the 13 names appwrite_env declares, and it lives in views-appwrite, referenced never copied. That is the right call — one owner, no drift-by-fork. What it left is C-57's gap: nothing mechanical could tell you the two had diverged.

appwrite_env now declares the edition it was verified against — SEAM_CONTRACT_VERSION = "1.3.0", SEAM_CONTRACT_COMMIT = "47172af". A version string and a sha are not coordinate values. What is recorded is which edition was read, which is exactly what makes drift detectable. Bumping them asserts someone re-checked.

Checked 2026-08-02: no live drift today. This builds the detector while the answer is known-good, which is the cheap moment.

Four checks, each mutation-proven

check	mutation	result
every name exists, with the class the registry declares	rename APPWRITE_UNFAO_BUCKET_ID here	4 failures
[meta] version matches the pin	pretend v1.2.0	1, naming the version to re-verify against
the pin is reachable from views-appwrite main	pin the withdrawn b54928f	1
no coordinate value copied into code	constant / dict value / kwarg	1 each

Run with -B after discovering stale bytecode was lying mid-campaign: both shas are 7 characters, so the .pyc size+mtime check passed and Python served a cached module contradicting its own source. Everything was re-verified from clean.

Existence is not reachability

That distinction is the point of this story, and it cost a merged PR three hours ago. #196: S3 pinned a commit resolved with rev-parse HEAD on a checkout sitting on an unmerged branch. The commit existed. Both cited files existed at it. Every check anyone had written passed. It had never reached main, declared a version never ratified, and was withdrawn.

A pin is a claim about what the contract says. Only reachability supports that claim, and now something asserts it.

The value-copy check took two wrong narrowings

First: a substring text scan flagged three "leaks" — file_metadata (a function name in contract/store_metadata.py), production_forecasts and unfao_bucket (only in refusal labels and docstrings). None was a copy. A guard failing on def file_metadata(record) gets deleted, and then the real rule is unguarded.

Second: narrowing to assignments and default arguments caught zero of these:

CONFIG = {"bucket": "unfao_bucket"}              # dict value
AppwriteConfig(bucket_id="unfao_bucket")         # keyword argument

The kwarg is the shape this repo would actually produce — AppwriteConfig(bucket_id=os.getenv(...)) is how every store is configured, and swapping one os.getenv for a literal is the violation.

Right axis: exact equality on string constants, not statement shape. Verified — it catches dict values, kwargs and constants, while all three false positives fall out on their own (a function name is not a Constant; "unfao_bucket datastore" ≠ "unfao_bucket"; docstrings excluded).

When a guard cries wolf, check whether the matching is wrong before assuming the scope is.

Review findings — all three addressed

F1 (warning) — the narrowing above. Fixed and re-proven.

F2 — _EXPECTED_CLASS derived class from the _API_KEY suffix: the exact inference the registry forbids ("class is DECLARED here, never inferred from a name's prefix"), inside the test enforcing the registry. Now written out, with a completeness check so an unclassified name fails rather than going unchecked.

F3 — tomllib is stdlib from 3.11 and pyproject declares >=3.11; CI runs 3.11 and executes these. This box runs 3.10, below the declared floor, so they skip locally — the local suite is quietly weaker than a green pytest -q suggests. Recorded against C-46's residual, since "a gate that does not run" is what that entry is open for and S7 (#188) should decide the CI question once for both.

tests/conftest.py

Sibling-repo resolution S7 will adopt for views-datafactory: declared env var, conventional path relative to this repo, never an absolute path to one machine, and a skip naming what to set. Second incident, which is this repo's named trigger for extracting.

Verification

ruff check .                                     # clean
pytest -q                                        # 298 passed, 3 skipped, 41 xfailed, 5 known pyarrow (C-72)
pytest -q  (with tomllib available)              # 301 passed — the gated checks run
VIEWS_APPWRITE=/nonexistent pytest -q            # skips cleanly, never errors
git diff --stat origin/main -- tests/fixtures/   # empty

Register: 74 concerns, 19 open, 55 resolved.

🤖 Generated with Claude Code