scm: load a repository from a path, with the three failure owners kept apart

[gunbai-bot]

The load half of the SCM read path. gunbc.scm.repository_envelope decodes a JsonValue and is pure; this is the effectful seam above it — path to bytes, bytes to document, document to envelope — so the decoder stays testable without a filesystem and the read path's only host effect lives in one place. DESIGN §3: the codec owns the interface shape, the host effect is one realization bound to it.

Why four arms

RepositoryLoad has four arms because the failures have three different owners:

arm	owner	remedy
RepositoryFileUnreadable	the operator	check the path you typed
RepositoryDocumentUnparseable	serialization	these bytes are damaged
RepositoryDocumentRefused	the repository schema	this is not a repository I know
RepositoryLoaded	—	—

Collapsing any two is the not-applicable-rendered-as-malformed mode DESIGN lists among its recurring failures: they have opposite remedies. Telling a user their repository is corrupt when they mistyped a path sends them looking for damage that is not there, possibly with a destructive repair.

There is deliberately no Absent => empty_repository() arm. That spelling reads as helpful and is the empty-observation narrow — it renders I could not observe anything as the verdict there is nothing here. A log built on it would print an empty history for a repository that exists at a slightly wrong path; a commit built on it would mint a first commit into a repository that already has a hundred. No arm here can produce an envelope without having decoded one.

Evidence: green by execution, plus a discriminating red

Four hand-authored fixtures drive the four arms, each claim asserting the arm it reached — so collapsing any two fails here. The fixtures are hand-authored rather than produced by encode_repository, so a change to the encoder cannot silently move what this file calls a valid document.

Mutation receipt. load_repository consults read.success rather than inferring absence from empty content, because an empty file and an absent file both yield empty content and only the success channel separates them. Replacing that consultation with a constant turns exactly one claim red:

BASELINE            p_valid=0  p_absent=0  p_trunc=0  p_schema=0
MUT (ignore success) p_valid=0  p_absent=1  p_trunc=0  p_schema=0   <- RED absent
RESTORED CONTROL    p_valid=0  p_absent=0  p_trunc=0  p_schema=0

So the success channel is load-bearing and the absent-file arm is genuinely covered rather than decorative.

The absent arm's fixture is a named nonexistent path, scm_rl_absent_path = "...this_file_is_never_created.json" — so the absence is authored and greppable rather than incidental. If anyone ever creates that file, the arm goes loud instead of silently reclassifying into a different outcome.

The absent-path fixture is under the checkout root deliberately. A /tmp path would be refused by the interpreter's hermetic carve-out (v1_interpreter hermetic_checkout_input_disposition_under) as a host effect rather than answered as a failed read, and the claim would be measuring the sandbox instead of this module. Disposition is SubstrateInputsOnly, matching the tailscale_acl_witness precedent for reading a committed fixture.

Compile: 0 blocking, 0 advisories in the new file (48 files emitted over the closure).

Why no LoadStanding projection

gunbc.scm.load_standing answers what a loader may do next at a publication boundary — whether a damaged generation may supersede a head slot. Three of these four arms have no publication meaning at all; a mistyped path is not a standing about a document. A consumer that is at a publication boundary calls repository_envelope_load_standing on the decode cause it holds, which is that function's job. Manufacturing a standing for "file missing" would invent the entailment DESIGN names as authority substitution.

Scope

Load only. The CLI half is deliberately not here — it needs an output channel that does not yet exist, and the shape of that is under a separate ruling (model the presentation, bind N handlers; not a stdout channel because stdout is the medium that hurts today).

🤖 Generated with Claude Code

---

Filed against this carrier, not repaired here

RepositoryFileUnreadable carries error: String, and that is a real debt in this module. By the mechanical test governing the read-command layer — if the result carrier contains a human-readable string, it has already chosen a channel — a host error message inside a refusal arm is exactly that. Every binding downstream either re-parses that prose or contradicts it.

It is filed rather than fixed because the repair is not a rename: the string is the operating system's, arriving through extdeps.filesystem.filesystem_io's cited error output channel, so grounding it means modeling the failure classes a read can actually have (absent, permission-denied, not-a-file, io-error) as a typed coproduct at the extdeps boundary and mapping the host string into it once. That is a boundary-authority change with its own consumers, not a change to this seam, and doing it inside a load-model PR would put a filesystem taxonomy in gunbc.scm.

Recorded here so the debt has a home and a stated shape rather than being discovered again by the next reader. It is also the reason the read-command module's header (in #9443) narrows its no-human-readable-string claim to what that module authors instead of claiming it of the whole type — the claim was false transitively through this arm, and saying so there without filing it here would have been a complaint without an owner.

An unstated soundness premise, now stated

scm_rl_an_absent_file_is_unreadable_not_empty proves the path is unreadable, which is what the arm carries. It does not prove no file exists — those coincide here only because this_file_is_never_created.json is never created by anything in the repository. That premise was load-bearing and unwritten; an added fixture that touches the path would make the claim quietly weaker without failing. The same premise underwrites scm_sv_a_refused_save_leaves_no_file in #9434, whose name asserts absence while its body observes unreadability.

Not repaired, because the alternative — asserting non-existence directly — needs a file-absent observation the filesystem boundary does not currently expose separately from a failed read, which is the same missing distinction the error: String debt above describes. One gap, two symptoms.

---

The filesystem boundary gap, stated at the right grain

Three findings on this PR trace to one authority, but "the filesystem models no read failure" was my first wording and it is imprecise. extdeps.filesystem.filesystem_io does model a generic refusal — FilesystemReadRefused { error: String }. What is missing is two separable capabilities, and fixing either alone leaves the other standing:

1. Semantic discrimination. Today this population is one raw host string:

file absent · permission denied · path is a directory · not a file · other I/O failure

That single collapse is why RepositoryFileUnreadable must carry host prose, why an absent-file witness can only prove unreadability, and why absence and permission-failure cannot receive different typed remedies. The cause vocabulary should be derived from the host's own typed error classification rather than by parsing prose — typed cause as authority, host message as optional detail, never as the classification.

2. Hermetic production. Even the existing generic arm cannot be produced by an authored fixture for a path that must fail. Committed successful reads have a route; a deliberately failing read does not. That is this PR's route gap.

The two are independent:

typed causes, no hermetic negative fixture  →  better runtime model, route gap remains
hermetic mock returning success=false       →  route gap closes, prose conflation remains

A terminal cut should supply both. One caution for whoever takes it: the negative fixture must be explicitly authored, not inferred from an absent fixture — making "no fixture" implicitly mean "file absent" would reproduce the empty-observation narrow at the mock layer, which is the exact class this witness exists to guard.

Dissolution receipt, mechanical: when that boundary lands, the two floor_route_gap rows added here go stale and red the build; delete exactly those rows; the two identities must then reach their subject and pass. The discriminating mutation is to swap the hermetic absent-response for a successful empty-file response — the absent-file claim and the keystone must go RED while the three committed-fixture claims stay GREEN. A permission-denied fixture is the control proving the new classifier does not simply label every refusal "absent".

Only then can the absence-oriented witness descend to a typed cause instead of resting on the authored premise, recorded above, that nothing in the repository creates the named path.

[gunbai-bot]

Fixed in 55abeb29644, and the finding was correct in a way that reached further than the one file.

Verified before fixing. Witness discovery enrols test fn / test data; 992 files under dag/test/claim/ use test fn, mine were among the 29 with none. So no claim in this file was ever executed by the required floor — and nothing in a green run could have said so, because an unenrolled claim does not fail, it is never asked. That is specification-without-execution in the file whose entire job is to be the executing consumer.

Promoted every -> Bool claim, not just the keystone you named — four claims plus the keystone. Fixing only the keystone would re-create the same defect one level in: a failure would name the aggregate rather than the claim that broke.

Verified by execution after the change: compiles 0 blocking, and all four claims return true, so the promotion enrols them without altering what they assert.

The same defect was in my other two witnesses and both are fixed on their owning branches — scm_repository_save_witness_test (51ace207f96, #9434) and scm_read_command_witness_test (46eebff53ba, #9443). Fourteen claims across three files, none enrolled. I found those by sweeping my own lane after your review rather than waiting for two more reviews to name them individually.

One thing worth stating plainly since it bears on how my other receipts should be read: the mutation grids I ran against these claims during development were real — I invoked the functions directly and the discriminating inputs flipped as predicted — but they measured behaviour CI would never have checked. The measurements were sound; the protection they implied did not exist. Both are true and neither repairs the other.

A pre-existing population beyond this PR, reported rather than fixed since it is not my lane: four other witness files declare their keystone as plain fn and are inert by the same mechanism — clock_freshness_witness.dag, diagnostic_redfish_witness.dag, http_pilot_rest_witness.dag, env_freshness_witness.dag. Routed to my parent as a class.

— sent from gentle-eagle-360

[gunbai-bot]

CI is red and the failure is not from this PR — declining to push a fix, with the evidence.

The failing job is required-witnesses-floor (job 98609308225). Verbatim:

required-ci: parse OK 4200 file(s) parse-clean
required-ci: declarations FAIL IMPORT-MEMBER-ABSENT dag/product/fabric/contention.dag:23:19:
  `product.fabric.contention` imports `grant_duration_seconds` from
  `product.fabric.supply`, which declares no such name

dag/product/fabric/ is untouched by this PR — the diff is dag/gunbc/scm/repository_load.dag and dag/test/claim/scm_repository_load_witness_test.dag. The cause is on main: #9395 added contention.dag calling grant_duration_seconds, #9397 renamed that accessor in supply.dag to grant_duration_bound_seconds returning Second? and did not update the caller. Each was green against a base lacking the other; they edit different files, so git merged them cleanly and together they break main. No textual merge could have caught it.

Compiling contention.dag as an entry locally gives five blocking diagnostics, and three are the missing name while two are exhaustiveness obligations — occupancy_basis_of is missing UnobservedGrantDuration, and the affordability match is missing QuoteNotPriceableWithoutDuration. So this is not a mechanical rename: the accessor returns Second? because the underlying fact became partial, and the annotation in supply.dag states that QuoteNotPriceableWithoutDuration is not a fifth way of being unaffordable. Picking a default or a wildcard arm to make it compile is the fabrication that rename exists to prevent, in a domain this PR does not own. It is assigned to the owning lane.

Every open PR against current main fails this way, including ones whose branch does not contain the offending commit — the pull_request event evaluates the merge with current main, so branch ancestry exempts nothing. This PR is the demonstration: its branch does NOT contain the offending commit, and it fails identically. I had claimed the opposite earlier in this thread and was wrong -- git merge-base answers about the branch, and CI compiles the merge.

No fix will be pushed here. This PR carries an approval (review 56868) and answered the enrollment finding in review 56857; it becomes mergeable when main is repaired, without any change to this diff.

— sent from gentle-eagle-360

[gunbai-bot]

Fixed in d28050af32b. This CI failure was mine — unlike the earlier ones on this PR, which were main's fabric break.

main is repaired, so the floor reached the fold for the first time and reported:

planned=11897 executed=11897 terminal=11897 passed=11755
failed=0  route_gap_unenrolled=2  route_gap_held=110
verdict=FloorRefused unexpected_failures=0

Two good things and one defect, all from the same run.

The good: my claims appear in the roster, planned and executed. That closes the question this PR's enrollment commit left open — I had verified the test fn rule at the producer (scan_test_decl_lines does strip_prefix("test fn ")) and verified the claims locally, but that the floor now discovers and runs them was unestablished until a floor did it. It has.

The defect: route_gap_unenrolled=2.

ROUTE-GAP scm_rl_an_absent_file_is_unreadable_not_empty never reached its subject:
  the hermetic route has no arm for Read (operation declares no mock_response)
ROUTE-GAP scm_repository_load_keystone_holds  — same cause, the keystone ANDs it

Which two is the informative part. The other three claims pass: they read committed fixtures, which the hermetic route serves. The absent-file claim reads a path that deliberately does not exist, and there is no arm for a read that must fail. Putting that fixture under the checkout root was right as far as it went — it keeps the claim out of the host-effect carve-out — but a nonexistent file has nothing to serve, and I did not carry that reasoning through to the failing case.

The refusal offers three routes and none is available here: extdeps.filesystem.filesystem_io declares zero mock_response arms, and the precedent shape (extdeps.git.inspect) keys them per operation, so one arm would answer every Read identically and break the three claims that legitimately read fixtures; a published mock case is for corpus-governed services; a wet lane is the wrong instrument for a hermetic floor.

So both identities are enrolled in v2.workflow.floor_route_gap, which is explicitly not a skip list — an enrolled gap is counted and held, never green, and a route that is later supplied reds the build as a stale row.

What this is not: coverage. An enrolled route-gap claim never reaches its subject, so it asserts nothing at runtime — the same shape as the unenrolled fn claims this PR just fixed, one level over. The difference is narrow but real: this one is visible and counted and reds the moment a route appears, where an unenrolled claim was never asked and nothing could tell. I would rather state that plainly than let the enrollment read as protection.

The gap is upstream: the filesystem boundary models no read failure that a hermetic route or a typed consumer can reach. That is the same authority behind the error: String debt in RepositoryFileUnreadable and the unreadable-vs-absent premise recorded in this PR's description — three symptoms, one boundary.

— sent from gentle-eagle-360