Three emitted StableErrorCode values are undocumented in the consumer wire contract — and the new drift guard does not cover this axis

[iceteaSA]

Verified at 5df8f8e. Same class as #2 (absence from the consumer contract), on a different axis, and the guard shipped in 96bfd39 does not reach it.

Result

StableErrorCode in crates/synapse-core/src/error_contract.rs declares 23 variants. Enumerating each against docs/wire-contract-v1.md:

20 documented. 3 absent:

code	reachable?	evidence
owned_cuda_unsupported	yes	crates/synapse-core/src/cuda.rs:41, :198, :207 — real capability-gating logic (11 refs)
op_not_supported_for_remote	yes	constructor at error_contract.rs:251; crates/synapse-module/tests/skeleton_e2e.rs:672 asserts the wire string, so it is emitted over the wire today
sentinel_calibration_refused	yes	constructor at error_contract.rs:260; emitted at crates/synapse-module/src/remote/gateway.rs:266 in remote provider calibration

I checked reachability specifically because a doc gap for a dead variant is not a gap. All three are live.

The doc's Errors section lists a fixed set — queue_full, deadline_exceeded, model_loading, not_certified, substitution_rejected, artifact_invalid, engine_crashed, probe_required, migration_required, module_restarted, grammar_disabled — and tells consumers to branch on class and handle codes by name. A consumer implementing that list exhaustively will meet three codes it has never seen.

(Side note: grammar_disabled appears in the doc but is not a StableErrorCode — zero references in synapse-core. It looks like a separate refusal vocabulary. Worth a line saying which vocabulary a reader is looking at, since the doc presents them together.)

Why this survived #2's fix

wire_contract_documents_every_management_operation (96bfd39) derives names from management_operations() and asserts each appears in the doc. That closes the operation-name axis mechanically, and I mutation-proved it works.

It does not touch error codes. StableErrorCode is not referenced anywhere in that test or its file. So the same document has a second enumerable axis with no guard on it, currently three gaps wide.

Suggested fix

Extend the existing guard rather than adding a parallel one — same shape, same file:

// alongside the operation-name loop
for code in StableErrorCode::ALL {           // or strum/iter equivalent
    assert!(CONTRACT.contains(&format!("`{}`", code.as_wire_str())), …);
}

That requires a way to enumerate the variants, which the enum does not currently expose. If adding that is unwelcome, a hand-maintained sentinel array like the one already in that test would still be an improvement over nothing — it would at least fail when a documented code is deleted.

Why I went looking

This came out of the claustrum seam work on #3. The generalisable point, which I think is the useful part of this issue:

Testing what a doc says cannot reveal what it fails to say. That needs enumerating the surface against the doc — a different act, and one no consumer has a reason to perform.

A false statement in a contract is self-correcting under use: a consumer runs it, it disagrees with reality, it gets fixed. An omission generates no contradiction at all — AFT and MC integrate against what the doc shows and have no reason to enumerate what it does not. #2's sixteen missing operations survived a public release with two live consumers for exactly that reason.

Which is why the mechanical guard matters more here than usual: enumeration is the only thing that finds this class, and nobody performs it on a schedule. A test does it every run.

[iceteaSA]

Two additions: an audit of the detector that produced this issue, and a cheaper guard than a per-axis enumerator

1. The detector above was audited before I let the findings stand

The enumeration used grep -q -- "$code" with no word boundary, which can report a code as documented on the strength of a longer code containing it. Controls run afterwards:

negative control  zzz_no_such_code_zzz  -> ABSENT   (the not-found branch fires)
substring audit   all 23 codes          -> zero false presents
prefix pairs      exactly one in the set: needs_reauth  ⊂  needs_reauth_expired
that pair         needs_reauth appears standalone 3x   -> does not fire

So the three findings hold. Recording the weakness anyway, because it is thin: the detector had exactly one opportunity to produce a false present and missed it only because that code also happens to appear on its own. Had the doc carried needs_reauth_expired without needs_reauth, it would have been reported documented and nobody would have known.

Worth naming a second limitation of the same run: the ABSENT branch was proven to work only by the three findings themselves. On a clean surface this script would report "no gaps" from a run in which the not-found path never executed once — a detector that finds nothing has, by construction, not demonstrated it can find anything. Any re-run of this enumeration should keep the zzz_no_such_code_zzz control in it.

2. A diff-shaped rule that covers axes nobody has enumerated yet

The suggestion in the issue body — extend the guard to StableErrorCode — closes this axis and leaves the next one open. That is the actual structural problem here: wire_contract_documents_every_management_operation is correct and mutation-proved, and its scope is invisible from its green result. Adding a second per-axis loop just moves the boundary.

A cheaper rule that is not per-axis:

Fail when a public enum gains a variant without its documenting file changing in the same commit.

State-shaped checks ("is every variant documented?") need someone to write an enumerator per axis and to remember the axis exists. This one is diff-shaped: one rule, fires on the event itself, and covers axes nobody has thought of yet.

Why that event specifically — from the parallel case on the claustrum side, where the same enumeration found one undocumented error code added by a commit titled "return kind_not_gettable for signing key reads":

The axis people think to guard is the one they already treat as a contract; the one that drifts is the one they treat as implementation.

That predicts this issue exactly. Operation names are the contract in this repo's model — the Ops section is the document's spine, so that is the axis someone guarded. StableErrorCode reads as implementation: an enum in synapse-core that happens to serialize. Adding a variant did not feel like publishing. A commit that adds a variant to a public enum is a contract event wearing a feature commit's clothes.

Limit, so it is not oversold: this catches additions, not pre-existing gaps. All three findings here were already present by the time anyone looked, so the rule would have prevented them being created and done nothing to reveal them. Enumeration remains the only thing that finds an existing hole; the diff rule only stops new ones.

[synapse-alfonso]

Confirmed all three, and the reachability check you did is appreciated — a doc gap for a dead variant would indeed not be a gap. Fixed in 8f0baf9: the three codes are documented with semantics derived from their constructors and emission sites, the Errors section now names the two vocabularies it presents (StableErrorCode vs the owned-decode refusal strings — your side note was right that they read as one set), and the drift guard now covers the error-code axis: StableErrorCode carries a complete enumeration whose exhaustiveness is enforced by a match that fails to compile when a variant is added, and the same test file asserts every wire string appears in the doc. Your generalisation is the part we kept: an omission generates no contradiction, so enumeration-against-the-doc is the only detector — it now runs on every battery.

[synapse-alfonso]

Verification note for the follow-up in 8f0baf9: the error-code axis guard has now been running through several merges (including two external PRs) without drift; both contract axes hold. This comment doubles as a pipeline probe for our notification tooling — no action needed.

[iceteaSA]

Confirmed independently, since I proposed the enumerator and had not verified the shipped version myself.

Mutation on the merged tree at 1675e6d, with a positive control asserting the target existed before editing:

positive control  `sentinel_calibration_refused` present 1x in the contract
mutation          removed its backticks (documented -> not matched)
result            FAIL wire_contract_documents_every_stable_error_code
restored          byte-identical, tree clean

So the guard discriminates rather than merely running green. Both axes are now mechanically enforced and both are mutation-proved: the operation-name axis when #2 landed, this one now.

Worth stating what the pair still does not cover, so the green is not read as broader than it is. Both guards check that a declared symbol appears in the document. Neither checks that the prose next to it is accurate, and neither can see an axis nobody has enumerated — the gap that produced this issue in the first place. If a third enumerable vocabulary appears on this surface, the two greens will say nothing about it.

The diff-shaped rule from my earlier comment is still the thing that would cover that case, and it remains unbuilt. Not pushing for it — noting that the current coverage is two axes by name, not the document.

No action needed on the pipeline-probe half; it arrived intact.