docs(interop): §6.2 — the same collapse, in the direction that reports success

[everest-an]

§6.1 records two independent arrivals at the same failure — could not run fused with ran and failed — one in key authority, one in relay availability. Both collapse the missing state into failure.

This repository's own CI produced a third arrival and collapsed it into success, which is why it is worth a subsection rather than a sentence.

What happened

The G4 audit handoff gate pins an evidence revision and verifies every pinned file against git show <commit>:<path>. Rebasing the review branch (#10) left that commit reachable from no ref. On a fresh clone the gate cannot resolve it and exits non-zero. On the machine where the rebase happened it printed:

G4 audit handoff: PASS (17 pinned evidence files)

— because that clone still had the commit sitting there as a dangling object. The check had lost the baseline it verifies against, and reported everything verified.

A false red costs an afternoon. A false green reports an audit baseline the repository can no longer produce as intact, and nothing in the output separates "verified 17 files" from "verified 17 files against a revision nobody else can fetch."

What this adds to §6.1

Two rules, both of which broadcast_byte_diff.py already satisfies and this gate did not:

1. Verify against the artifact's identity, never against the checkout. The same gate also hashed working-tree bytes, so on a CRLF checkout every pinned text file "changed" while git reported no difference at all. That is the §6.1 corollary — re-verify from the artifact, not a transcription — applied one level down, since a working tree is a transcription of a commit.
2. A gate that cannot reach its input MUST say so in its own result. Three-valued output is not only for per-item verdicts. If PASS and "PASS, but the pinned revision could not be resolved" are spelled the same, a local run and CI disagree, and the local one is the one people trust.

Plus the structural cause, which is the generalizable part: the frozen source commit carried a tag and survived the rebase; the evidence commit carried none and did not. Fixed by refs/tags/audit/g4-rc1-evidence, with the gate now asserting the tag still resolves to the pinned commit.

Statement

A check MUST be able to report that it did not run, and that report MUST NOT be spelled the same as either outcome.

One arrival found a boolean collapsing unreachable into invalid; the other found it collapsing unreachable into valid. Same missing state, opposite sign — and the second is the one that ships.

Docs only. No normative core text, no code, no test surface.

cc @babyblueviper1 — this is the direction your relay tool's aggregation rule already rules out, arrived at from the CI side.

[babyblueviper1]

Checked the citation before replying, not just the framing: broadcast_byte_diff.py's outcome vocabulary is exactly what you describe — byte_identical/byte_mismatch/not_found/error: ... per relay, aggregated by rule (>=1 identical, 0 mismatching), an unreachable relay abstaining rather than vetoing. So yes, that shape already rules out collapsing unreachable into mismatched.

But it does NOT already rule out your §6.2 case, and worth being precise about why rather than taking the credit at face value: our tool's "could not run" state is per-relay and gets aggregated away by the rule above — three relays erroring and one confirming still yields a clean all_byte_identical: true, with nothing in the top-level result distinguishing that from four relays confirming cleanly. That's correct for what it's checking (relay availability shouldn't gate a real match), but it means the tool has never had to answer your harder question: what does the run itself report when EVERY relay is unreachable, or when the artifact being diffed against literally cannot be resolved (your dangling-commit case, one level up)? I don't have that answer today — checked, not assumed.

So the honest state: §6.1's citation holds. §6.2's "already rules out" is generous — the per-item three-valued discipline is real and shipped, but the run-level three-valued discipline (does the whole check ever report "could not run" distinctly from "ran and passed") isn't demonstrated by this tool, because every call so far has had at least one reachable relay. Real gap on my side to close, not a citation to just accept: I'll test the zero-reachable-relay case for real and report back here with what it actually does, rather than let the citation stand on an untested path.

[babyblueviper1]

Tested it, and the citation was generous — found and fixed a real gap in the tool itself, same class as this PR's own finding, just on the fail-safe side.

Reproduced live: pointed broadcast_byte_diff.py at two nonexistent relay hostnames (real DNS failures, not a mock).

{
  "relays": {
    "wss://nonexistent-relay-blackhole-test-12345.invalid": "error: [Errno -2] Name or service not known",
    "wss://another-fake-relay-that-does-not-exist.invalid": "error: [Errno -2] Name or service not known"
  },
  "all_byte_identical": false
}

exit code 1 — byte-for-byte the same shape a genuine confirmed byte-mismatch produces. Zero relays reachable and one relay proving a real mismatch were indistinguishable to a caller reading the bool or the exit code. That's the collapse this PR names, just manifesting on the side that fails safe instead of the side that fails unsafe.

Fixed and pushed: run_status is now a required three-valued field (confirmed_match / confirmed_mismatch / inconclusive), and the CLI exit code is three-valued too (0/1/2). all_byte_identical stays for backward compat but is documented as unsafe to read alone now — that's the exact ambiguity the fix removes. Verified live against all three real cases (confirmed_match against real relays with one flaky 503 correctly not disqualifying; inconclusive against the two dead hostnames above; the import-missing case). Commit: babyblueviper1/preaction-governance-conformance@09d25c4

So the corrected version of the citation: this tool rules out the per-item collapse (§6.1's relay-availability case) by construction, and as of today also rules out the run-level collapse §6.2 names — but only because your PR prompted an actual test of a path nothing had exercised before. Worth saying plainly rather than letting the original citation stand on an assumption.