Re-scoped 2026-08-12 — shrunk. The first draft bundled a platform/ module extraction. That is now explicitly deferred. What remains is three small fixes to failures a contributor would actually hit.
Part of #241, Gate 2 — does not block PR #240. Registers C-91.
What is NOT in this story any more
Extracting a platform declarations module (C-88). The case for it: scripts/build_gaul_lookup.py:73 hardcodes "VIEWS_DATAFACTORY" because a script may not import from tests/, and tests/seam_registry.py became a fifth declaration home outside conftest.py.
One duplicated string is cheaper than a new package for a solo maintainer. WET before DRY: two copies that are understood beat one abstraction that is guessed, and the shape of that abstraction is still a guess. C-88 stays open with its existing trigger — a third consumer needing one of these declarations.
Work — three fixes, all small
1. A stale clone gets one diagnosis, not four errors and three stories.
registry_at runs git rev-parse --verify <pin>^{commit} first, so a clone that predates the pin — or is shallow, or --single-branch, which matters because views-appwrite's default branch is not main — raises "does not resolve to a commit … an empty ref reads the index and a branch reads a moving tip". That names neither cause and never says git fetch. Four tests error with it, while test_the_pinned_commit_is_reachable_from_the_contract_repos_main detects the identical condition and skips with the right remedy.
Distinguish "this ref is not a frozen commit" (a pin defect, our fault) from "this clone cannot answer" (say git fetch), and make the two checks agree on which one skips. Note C-81 tracks the skip count, so a new unconditional skip is not free.
2. rows() refuses a scalar row instead of raising AttributeError.
seam_registry.py:150 guards a null section and not a scalar row, so body.get("class") raises on a table whose entries are strings. Verified: views-appwrite's [test_environment] holds status and fact as top-level strings. Nothing breaks today because that table is IGNORED — but when the partition check fires on a new upstream table, its own remediation message tells the maintainer to classify it CONSUMED, and doing that for a table written that way returns a traceback pointing into a dict comprehension. From the module whose docstring says a helper justified by failing legibly must not hand back a bare traceback.
3. The scratch repo stops being able to hang the suite.
tests/test_env_declaration.py:820 sets user.name/user.email and inherits everything else, then runs git commit with check=True, capture_output=True and no timeout. With commit.gpgsign = true it fails with a bare CalledProcessError (git's explanation is swallowed). With a passphrase-protected key it blocks on pinentry with stdin inherited: the whole run hangs, with no diagnostic. conftest.git_output, which this helper bypasses, caps at 30 seconds.
Add -c commit.gpgsign=false -c core.hooksPath=/dev/null, an explicit timeout, and surface stderr on failure. Three flags and a keyword argument.
Acceptance criteria
Labels
story, implementation
Re-scoped 2026-08-12 — shrunk. The first draft bundled a
platform/module extraction. That is now explicitly deferred. What remains is three small fixes to failures a contributor would actually hit.Part of #241, Gate 2 — does not block PR #240. Registers C-91.
What is NOT in this story any more
Extracting a platform declarations module (C-88). The case for it:
scripts/build_gaul_lookup.py:73hardcodes"VIEWS_DATAFACTORY"because a script may not import fromtests/, andtests/seam_registry.pybecame a fifth declaration home outsideconftest.py.One duplicated string is cheaper than a new package for a solo maintainer. WET before DRY: two copies that are understood beat one abstraction that is guessed, and the shape of that abstraction is still a guess. C-88 stays open with its existing trigger — a third consumer needing one of these declarations.
Work — three fixes, all small
1. A stale clone gets one diagnosis, not four errors and three stories.
registry_atrunsgit rev-parse --verify <pin>^{commit}first, so a clone that predates the pin — or is shallow, or--single-branch, which matters because views-appwrite's default branch is notmain— raises "does not resolve to a commit … an empty ref reads the index and a branch reads a moving tip". That names neither cause and never saysgit fetch. Four tests error with it, whiletest_the_pinned_commit_is_reachable_from_the_contract_repos_maindetects the identical condition and skips with the right remedy.Distinguish "this ref is not a frozen commit" (a pin defect, our fault) from "this clone cannot answer" (say
git fetch), and make the two checks agree on which one skips. Note C-81 tracks the skip count, so a new unconditional skip is not free.2.
rows()refuses a scalar row instead of raisingAttributeError.seam_registry.py:150guards a null section and not a scalar row, sobody.get("class")raises on a table whose entries are strings. Verified: views-appwrite's[test_environment]holdsstatusandfactas top-level strings. Nothing breaks today because that table isIGNORED— but when the partition check fires on a new upstream table, its own remediation message tells the maintainer to classify itCONSUMED, and doing that for a table written that way returns a traceback pointing into a dict comprehension. From the module whose docstring says a helper justified by failing legibly must not hand back a bare traceback.3. The scratch repo stops being able to hang the suite.
tests/test_env_declaration.py:820setsuser.name/user.emailand inherits everything else, then runsgit commitwithcheck=True,capture_output=Trueand notimeout. Withcommit.gpgsign = trueit fails with a bareCalledProcessError(git's explanation is swallowed). With a passphrase-protected key it blocks onpinentrywith stdin inherited: the whole run hangs, with no diagnostic.conftest.git_output, which this helper bypasses, caps at 30 seconds.Add
-c commit.gpgsign=false -c core.hooksPath=/dev/null, an explicittimeout, and surfacestderron failure. Three flags and a keyword argument.Acceptance criteria
git fetch, consistent between the reachability check and the pinned reader.rows()on a scalar-row section raisesRegistryReadErrornaming section and key.commit.gpgsign=trueand a globalcore.hooksPathset — demonstrated by running with them set, not by inspection.timeout.Labels
story,implementation