Vault error handling branches on `code` instead of `class` — an unknown code is rejected as "config invalid" instead of paused

[iceteaSA]

Verified at b4543b4. Consumer-side defect in crates/synapse-module/src/remote/vault.rs; claustrum's surface already carries everything needed to fix it.

Summary

Claustrum's error contract says to branch on class, never code, because the code set grows and the class set does not. We branch on code in two places, and our fallback for an unrecognised code is not a neutral bucket — it rejects the job while blaming synapse's own configuration.

class is already present on every error frame we receive. We are discarding it, not missing it.

Site A — closed enum over codes, no fallback variant

#[derive(Deserialize)]
#[serde(rename_all = "snake_case")]
enum CredentialReadErrorCode {
    NotFound, NeedsReauth, RefreshUnsupported,
    RefreshFailed, VaultLocked, Corrupt, TooManyItems,
}

No #[serde(other)] variant. The enclosing CredentialGetOutcome is #[serde(untagged)] over {Success, AppError}, so an unrecognised code fails the AppError arm, then fails both arms, so serde_json::from_slice returns Err — which we map to VaultError::MalformedHandlesFile.

Note the shape: a new code does not reach a default branch, it fails parsing, so the resulting error names a malformed file when the response was perfectly well-formed.

Site B — string-matched codes with a cause-asserting catch-all

map_call_error() matches exactly "needs_reauth", "vault_locked", "not_found", then CallError::Module(_) => VaultError::MalformedHandlesFile.

Blast radius — worse than a mislabel

MalformedHandlesFile is not neutral. At crates/synapse-module/src/remote/runtime.rs:612-618:

VaultError::MalformedHandlesFile
| VaultError::MalformedHandle
| VaultError::NotFound => CredentialDisposition::Reject(
    RuntimeError::credential_config_invalid("credential handle configuration is invalid")),

while VaultLocked | NeedsReauth => CredentialDisposition::PauseJob.

So an unknown-to-us vault condition is:

1. Rejected rather than paused — non-recoverable, the job dies;
2. blamed on synapse's own config in the operator-facing string;
3. when the true condition may be transient and repairable, whose correct disposition was PauseJob.

The operator reads "credential handle configuration is invalid", audits their handle config, finds nothing wrong, and never learns the vault said something new.

The generalisable defect: a catch-all that names a cause it cannot know. A default branch should report what is known ("unrecognised vault response"), not guess.

The fix — branch on class

Confirmed by Claustrum from their source (read_surface.rs:427): every error body carries both fields, class being the one intended for consumers.

pub struct ErrorBody { pub code: ReadError, pub class: ErrorClass }

Their class set is closed and golden-tested against the contract:

ERROR_CLASS_WIRE_SET: [&str; 4] = ["transient", "permanent", "auth_required", "context_overflow"];

A closed enum over class is legitimate precisely where a closed enum over code is not. Target mapping:

class	disposition
transient	retry (existing recoverable path)
auth_required	PauseJob
permanent	stop, do not retry
context_overflow	not reachable on the credential path
unknown class	PauseJob

unknown class -> PauseJob is safe here — verified, not assumed

Claustrum flagged the risk that pausing converts a dead job into a silently hung one if the pause is unbounded or invisible. Checked against our implementation; it does not apply:

• Bounded at pause time — pause_job_needs_reauth() (store.rs) sets resume_deadline_ms = now + resume_window_ms alongside state = paused_needs_reauth.
• Enforced, not merely recorded — the expiry sweeper transitions them out:

  UPDATE jobs SET state = 'failed_permanent', terminal_at_ms = ?2, error_json = ?3
   WHERE state = 'paused_needs_reauth' AND resume_deadline_ms <= ?2

  There is a supporting index (jobs_resume_deadline_idx).
• Resume is deadline-guarded — the resume path requires resume_deadline_ms > now.
• Visible — the gateway surfaces StableError::needs_reauth() on the wire, and resume_deadline_ms is exposed on the job record.

Worst case a paused job becomes failed_permanent at its deadline. It cannot hang indefinitely.

Also worth fixing: the not_found operator string

Claustrum confirms not_found is a deliberate uniform mask — returned identically for never-existed, revoked, and not-servable handles, because distinguishing them would permit handle enumeration. That collapse is permanent on their side and we should not ask for a signal to split it.

What is ours to fix is the message. credential handle configuration is invalid asserts a cause we have no evidence for. Something like "the vault did not serve this handle — it may be revoked, unknown, or not servable" states what is actually known.

The property their contract cares about (not_found + permanent = authoritative stop, never retry-hammer) we already satisfy.

Non-issues, checked and cleared

• Error-string leakage — we conform. CredentialReadError deserializes only { code }, map_call_error reads only body.code, and there is a regression test (credential_wire_decoder_never_exposes_payload_in_errors). Claustrum's hazard is that OAuth bodies echo submitted parameters; it cannot reach our logs on this path.
• stale_pending — status-only, and correctly ignored by a get-only consumer like us. It predicts what a get will cost, so it has no value riding back on a get response. Confirmed by Claustrum from source; we call only credential.get and credential.report_auth_failure.

Cross-seam work agreed with Claustrum Legion via direct lane. Filed here rather than on their board: every violation is consumer-side.

[iceteaSA]

Reproduced against a real captured frame

Claustrum Legion captured a live error frame off the daemon (bc87553, credential.get with an unknown handle) and I ran it through our current decoder verbatim, plus a proposed class-based replacement. This upgrades the report above from reasoned to demonstrated.

The frame:

{"result":{"error":{"class":"permanent","code":"not_found"}}}

Method: decoder types copied verbatim from crates/synapse-module/src/remote/vault.rs @ b4543b4 into a standalone scratch crate, no repo mutation, no network.

Result

=== CURRENT decoder (branches on code, closed enum) ===
  OK          real captured frame (class=permanent, code=not_found)
                -> AppError { error: CredentialReadError { code: NotFound } }
  PARSE FAIL  future unknown code (class=transient, code=vault_resealing)
                -> data did not match any variant of untagged enum CredentialGetResponse
  OK          success frame
                -> Success { payload: [115, 101, 99], expires_at_ms: None, record_version: 7 }

=== PROPOSED decoder (branches on class, code is free string) ===
  OK          real captured frame      -> class Permanent  -> stop (no retry)
  OK          future unknown code      -> class Transient  -> retry
  OK          success frame            -> token

What this establishes

1. Known codes are fine today. The real frame decodes correctly. This is not a live outage — it is a latent defect that fires the first time claustrum ships a code we do not know, which their contract says will happen.

2. The unknown-code failure is confirmed, and the diagnostic is worse than expected. The parse error is data did not match any variant of untagged enum CredentialGetResponse — it names the outermost type. The #[serde(untagged)] collapse cascades from CredentialReadErrorCode all the way up, so a developer debugging this is pointed at the entire response shape rather than at the one unknown string that caused it. The misdirection noted in the issue body is present in the error text too, not only in the operator-facing message.

3. class deserializes cleanly first try. "class":"permanent" maps to ErrorClass::Permanent with no coaxing — claustrum's producer strings and a consumer enum written against their contract agree in both directions. Their golden test pins their producer against the contract; this is the missing other half.

4. We are provably discarding class, not missing it. The current decoder parses the real frame successfully while ignoring the class field entirely — serde skips unknown fields by default. The field we need is arriving on every frame and being dropped on the floor.

One hypothesis ruled out

Claustrum flagged that a wrong nesting level could be a second cause of the collapse — the error sits at result.error, not top level, and they had hit exactly that bug in their own harness earlier the same day.

Not applicable to us. Our CredentialGetResponse::Wrapped { result } handles the outer level and CredentialGetOutcome::AppError { error } the inner, so result.error resolves correctly — as the passing real-frame case above demonstrates. The single cause is the closed code enum.

Scratch harness at /tmp/synapse-vault-decode if anyone wants to re-run it; it is three literals and two decoders, cheap to rebuild.

[iceteaSA]

Verified 19d5efb at 5df8f8e — both sites fixed. Two residuals worth a look.

Pulled to 5df8f8e and checked the fix rather than taking the claim.

Site A fixed. CredentialReadError now carries { class, code } as plain Strings, so an unknown code no longer collapses the #[serde(untagged)] parse. Your test unknown_code_in_known_class_deserializes_without_becoming_malformed pins exactly the frame shape that used to break it.

Site B fixed, and better than I proposed. CallError::Module(_) now maps to Unreachable instead of MalformedHandlesFile, with the reasoning in the comment — a generic module frame has no credential class, so calling it malformed was mislabeling a valid frame. I had only asked for the catch-all to stop naming a cause; routing it to a recoverable class is the stronger answer.

Disposition mapping matches what claustrum specified, including _ => PauseJob for an unknown class with the asymmetry argument in the comment. I verified separately that PauseJob is safe here: pause_job_needs_reauth sets resume_deadline_ms, the expiry sweeper flips overdue pauses to failed_permanent, and resume is deadline-guarded — an unknown class cannot hang a job indefinitely.

Gate at 5df8f8e: 570 run / 570 passed / 3 ignored, inside a network namespace with egress dead by DNS name and raw IP and a loopback positive control live before and after. Same 15 in-body skips as my b4543b4 baseline (missing local MiniLM ONNX snapshot), so the +5 is your new tests, not new skipping.

---

Residual 1 — the stable code still says config-invalid, only the message was fixed

permanent and context_overflow route to:

CredentialDisposition::Reject(
    RuntimeError::credential_config_invalid(credential_error_message(&class, &code)))

The message is now honest — vault reported permanent error (code 'not_found'). But the wire-stable error is still StableError::credential_config_invalid().

Claustrum's not_found is a deliberate uniform mask covering never-existed, revoked, and not-servable handles. None of those is a synapse config problem. So a consumer branching on the stable code — which is what our own wire contract tells consumers to do, and what the class-over-code lesson in this issue is about — is still told the operator's configuration is invalid.

It is the same defect one layer out: the human-readable string got fixed, the machine-readable one that consumers actually branch on did not.

Residual 2 — three VaultError variants are now unreachable, and two tests pin them

After the fix, nothing in vault.rs produces VaultError::NotFound, VaultError::VaultLocked, or VaultError::NeedsReauth — app errors become CredentialFailure { class, code } and call errors become Unreachable. The only remaining non-test references are the consumer match arms at runtime.rs:634 and :642.

Two tests construct them directly (runtime.rs:1458 Err(VaultError::NeedsReauth), :1737 Err(VaultError::VaultLocked)), so they exercise a path production can no longer produce. They pass, and they read as coverage of the pause behaviour, but they can no longer detect a regression in it — the real route to PauseJob is now credential_failure_disposition.

Worth either deleting the dead variants, or repointing those tests at CredentialFailure { class: "auth_required", .. } so they cover the live path. Not urgent; flagging because a green test over an unreachable arm is the shape that hides the next regression.

Note the NotFound arm at :642 is dead specifically, while MalformedHandlesFile / MalformedHandle in that same arm are still live and genuinely are local problems — so the accusatory string is now correctly scoped for them. Only NotFound's presence in that arm is stale.

[iceteaSA]

Residual 3 — untagged variant precedence can read a credential error as a success

Found while stress-testing the decoder's tolerance to wrapper changes. Latent, not live — see the honesty bound at the end.

CredentialGetResponse is #[serde(untagged)] with Direct(CredentialGetOutcome) declared before Wrapped { result }. Serde tries variants in declaration order, so a frame carrying both a wrapped error and top-level Success fields resolves as the success:

{"result":{"error":{"class":"transient","code":"x"}},"payload":[1],"record_version":9}
  ->  SUCCESS payload=[1] record_version=9

The error is discarded in silence, and fetch() would return a CredentialToken built from the top-level bytes — handing a bogus token to a provider call rather than surfacing the failure.

Method

Decoder types copied verbatim from crates/synapse-module/src/remote/vault.rs @ 5df8f8e into a standalone crate, no repo mutation, no network. Full vector set:

BASELINE wrapped error         -> APPERROR class=permanent code=not_found
BASELINE wrapped success       -> SUCCESS payload=[115,101,99] rv=7
MUT removed-wrapper error      -> APPERROR class=permanent code=not_found
MUT removed-wrapper success    -> SUCCESS payload=[115,101,99] rv=7
MUT renamed-wrapper error      -> PARSE FAIL -> MalformedHandlesFile
MUT renamed-wrapper success    -> PARSE FAIL -> MalformedHandlesFile
PROBE  wrapped-error + top-level success fields -> SUCCESS payload=[1] rv=9

Two useful side results from the same run:

• A removed wrapper decodes correctly, not silently differently — the Direct arm yields byte-identical class/code/payload/record_version. Claustrum and I had both assumed a removed wrapper was the quiet-corruption case; it is not.
• A renamed wrapper fails cleanly into MalformedHandlesFile. Loud, which is the right behaviour.

So the untagged fallback is not dangerous in the way we expected. It is dangerous because it carries an undeclared ordering.

Honesty bound

The probe frame is synthetic. It is not a shape claustrum emits today — I could not construct it from their producer, only from hand-written JSON. This is a latent hazard, not an observed failure, and I am not claiming otherwise.

It becomes live the moment any frame carries both a result object and top-level payload/record_version. Given that the result wrapper currently appears in both synapse's and claustrum's test suites while being asserted against the other side by neither, "nobody will add a top-level field" is not a guarantee worth resting on.

Suggested fix

Cheapest correct change is to stop relying on precedence: make the outer shape explicit rather than untagged, or check for result first and only fall back to Direct when it is absent. If the two-shape tolerance is deliberate (it does absorb an unwrapped frame cleanly), a comment saying so — plus a test pinning which arm wins when both match — would make the ordering a decision rather than an accident.

Happy to send the fix with the vector set above as its test, if you want it. Related to residuals 1 and 2 above; all three are the same fix area.

[iceteaSA]

Negative-vector results: 2 of 4 unemittable frames are accepted

Claustrum supplied four frames their producer structurally cannot emit, derived from their types rather than from memory. Ran all four against the shipped decoder + disposition (verbatim from vault.rs and runtime.rs @ 5df8f8e):

vector	frame	result
NEG-1 missing class	{"result":{"error":{"code":"not_found"}}}	REJECTED → MalformedHandlesFile
NEG-2 missing code	{"result":{"error":{"class":"permanent"}}}	REJECTED → MalformedHandlesFile
NEG-3 unknown class	{"result":{"error":{"code":"not_found","class":"retryable"}}}	ACCEPTED → PauseJob
NEG-4 payload + error	{"result":{"error":{…}},"payload":[1],"record_version":9}	ACCEPTED as SUCCESS

Their guarantee for each: ErrorBody { code: ReadError, class: ErrorClass } — both non-Option, no skip_serializing_if, and ErrorClass is a closed enum golden-tested against a pinned four-value wire set. GetOutcome is untagged over Ok(GetResult) | Err { error }, so one outcome cannot carry both payload and error.

NEG-2 passes by accident, not by test

It is rejected only because code: String is non-Option, so serde fails the AppError arm and the untagged parse collapses. Nothing asserts it — the suite pins missing-class (missing_error_class_is_a_malformed_credential_frame) and not missing-code. Adding #[serde(default)] to that field later would silently open the hole with no test going red. Worth a test purely to convert an accident into an intention.

NEG-4 is the one to fix first

It fails toward success: a frame containing a credential error is read as a valid credential, and fetch() returns a CredentialToken built from the top-level bytes. Wrong-and-executing, versus NEG-3's wrong-and-parked.

The structural asymmetry reinforces the ordering. Claustrum notes that NEG-1..3 are unemittable because a field is missing or out of range — a future version could plausibly relax those, and they would announce it. NEG-4 is unemittable because two enum variants cannot coexist; relaxing that is a redesign, not a version bump. So NEG-4 carries their strongest guarantee and our worst failure, which is exactly the combination that makes it easy for both sides to leave alone.

Fix is the one already proposed in residual 3: stop relying on untagged declaration order.

NEG-3 is blocked on a contract question, not a code question

Leaving this one open deliberately rather than changing it.

credential_failure_disposition's _ => PauseJob arm is not an oversight — it implements Claustrum's explicit earlier guidance, with their asymmetry argument preserved in the comment. Their newer position is that an unknown class should be rejected, because it is a frame no version of their producer emits.

Both are defensible, for two different events that are indistinguishable at our decoder:

• claustrum legitimately ships a new class in a future version → lenient PauseJob is right; killing jobs over a vocabulary extension is the wrong failure.
• a frame carries a class no version emits (corruption, wrong producer) → rejection is right; it is not a credential failure at all.

Both arrive as "a string not in our match arms". The disposition depends on one fact we do not hold: can claustrum's class set widen without synapse knowing? If the four are frozen, unknown always means the second case and we should reject. If a future daemon may add a fifth while we run an older build, the first case is real and leniency is correct.

Asked them to state it as a contract property rather than a preference. Not changing the arm until they do — a silent switch would leave the two sides on different contracts with nothing recording which.

[iceteaSA]

NEG-3 resolved: keep _ => PauseJob exactly as merged — do not change it

Superseding my previous comment, which left this open. Claustrum checked the deciding fact and their earlier guidance is the correct one. 19d5efb is right as it stands.

The deciding fact

I had asked whether their class set can widen without synapse knowing. It can, for two reasons they verified in their own source rather than asserting:

1. Their golden test does not freeze the set. It serializes the four ErrorClass variants and compares them against ERROR_CLASS_WIRE_SET, a const in the same file. Adding a fifth variant and updating the const passes green. It catches accidental drift; it cannot prevent a deliberate addition.
2. There is no per-frame version. wire_crate_version is on the daemon manifest, not the response frame, so a frame carries no signal about which producer version emitted it.

And the skew is not hypothetical — claustrum deployed a new build today while synapse did not rebuild. Older consumer against newer daemon is the normal state here.

So an unknown class means "not in the set this build knows", never "not in any set".

The contract, quoted

The four classes are the set as of the current producer version. The set MAY WIDEN in a future version. It will never NARROW, and an existing member will never be re-meant.

A consumer encountering an unknown class MUST treat it as a class it does not yet understand, not as a malformed or hostile frame. The conservative disposition — pause, park, defer to a human — is correct. Rejecting on an unknown class converts a vocabulary extension into a job kill.

A frame that is otherwise well-formed and carries an unrecognised class is a VALID frame from a newer producer.

Going into claustrum#18 so it is public contract rather than a private exchange.

Consequence for this repo: the _ => PauseJob arm is contract-backed, not a lenient default awaiting hardening. Worth keeping the existing comment and adding a pointer to the contract, so a future reader tightening "unhandled class" into a rejection sees why that would be wrong.

What remains actionable from the vector run

• NEG-4 (payload + error → accepted as SUCCESS) — unchanged priority, still first. Fails toward a bogus token. Fix is residual 3: stop relying on untagged declaration order.
• NEG-2 (missing code) — still worth a test. It is rejected only because code: String is non-Option; adding #[serde(default)] later would open it silently with nothing going red. The protection is standing on a type nobody chose for that purpose.
• NEG-1 — already covered by missing_error_class_is_a_malformed_credential_frame, and now pinned against their producer rather than our belief.

Note on how this was caught

The vector-3 guidance arrived as one item in a list of frames their producer "cannot emit", alongside three that are structurally unemittable. It was the only version-scoped item in a list of structural guarantees, which is why it read as one. It surfaced because the new guidance contradicted behaviour already merged on their own earlier advice — the contradiction was the signal, not the content.

Generalisable: when a surface owner's new guidance conflicts with something already implemented on their earlier guidance, check before switching. The contradiction is evidence one of the two statements is unexamined, and it costs one round-trip to find out which.

[iceteaSA]

Live-frame confirmation against the running claustrum daemon — passes

Closes the last open verification on this issue. Everything before this was checked against literals; this is the actual wire.

ck module list first (claustrum running / enabled / live / ok), then one credential.get through the fleet daemon on a handle that cannot exist — no secret returned, nothing written:

subc_call --module claustrum --method credential.get \
          --params '{"handle":"synapse-liveframe-probe-does-not-exist","min_ttl_ms":600000}'

Bytes off the daemon (decoded from the framed byte array):

{"result":{"error":{"class":"permanent","code":"not_found"}}}

Run through the shipped decoder (types verbatim from vault.rs @ 5df8f8e):

LIVE (class,code)        OK  class=permanent code=not_found
CANONICAL (code,class)   OK  class=permanent code=not_found

byte-identical strings?      false
equal as serde_json::Value?  true

What this establishes

The result wrapper is present on the wire exactly as our decoder expects, both class and code arrive, and the values map to the disposition we ship. Our decoder is order-independent — verified by running both field orders rather than assuming serde's behaviour.

This is the consumer→producer direction that neither side's tests could cover alone: claustrum's golden test pins their producer against their contract, ours pinned our decoder against our own literal, and nothing crossed the boundary until now.

One nuance worth recording

Claustrum's canonical literal (code before class) and the live wire (class before code) are not byte-identical strings, though they are equal as serde_json::Value.

Not a defect — a json!-based assertion compares Values, so their pin should be green against the live wire, and I have not read their test and am not asserting otherwise. But it means "quote this verbatim" and "these are the bytes on the wire" are different statements here. Harmless for deserialization; wrong the moment either side adds a check that compares serialized strings or hashes a frame.

Recorded so nobody later assumes a byte-identity that does not hold.

Scope note

Synapse's entire vault surface is credential.get and credential.report_auth_failure. Claustrum notes OP_GET_MANY wraps differently ({"results":[…]}) and is a second unpinned wrapper — not our exposure today, noted in case that changes.

---

Remaining actionable on this issue, both synapse-side and unblocked: NEG-4 (untagged precedence — a frame with payload and error together resolves as SUCCESS) and NEG-2 (missing code is rejected only by accident of code: String being non-Option; wants an intentional test).

[iceteaSA]

Residual 3 fixed and mutation-proved locally — available on request

Implemented on a local branch (fix/vault-envelope-precedence, not pushed). Offering rather than sending, since you have been shipping your own fixes; say the word and I will open a PR or paste the diff, whichever you prefer.

The change

decode_credential_get_response now selects the envelope explicitly instead of by #[serde(untagged)] variant order — result wins whenever present, and the unwrapped form remains an accepted fallback rather than a coincidence of declaration order. The CredentialGetResponse enum and its into_outcome() are gone; the function returns CredentialGetOutcome directly.

The comment on it states the failure rather than the mechanism, so a future reader knows why the explicit form matters:

Untagged enums are tried in declaration order, so a frame carrying both a wrapped result.error and top-level success fields resolved as a SUCCESS and discarded the error — returning a token built from the stray bytes.

Three tests, one per open point

• wrapped_error_wins_over_stray_top_level_success_fields — NEG-4, the actual defect.
• unwrapped_outcome_is_still_accepted — pins the fallback so removing it is a decision rather than a side effect.
• missing_error_code_is_a_malformed_credential_frame — NEG-2, converting the accidental protection into an intentional one. code is non-Option, so this was rejected by the type rather than by intent; adding #[serde(default)] later now goes red here instead of silently widening what synapse accepts from the vault.

Mutation proof

The tests were verified capable of failing, not merely observed passing. Reverted the fix to Direct-before-Wrapped precedence (with a positive control asserting the mutation target existed exactly once before editing — a substitution that silently matches nothing is indistinguishable from a test that catches nothing):

FAIL  remote::vault::tests::wrapped_error_wins_over_stray_top_level_success_fields
      panicked at vault.rs:297: stray top-level success fields must not outrank a wrapped error
Summary  5 tests run: 4 passed, 1 failed

The other four stayed green, so the test discriminates rather than merely triggering. Mutation reverted; file confirmed byte-identical to its pre-mutation copy.

Gates

Inside a network namespace, loopback positive control live and egress dead by DNS name and raw IP, both before and after the run:

573 tests run: 573 passed, 3 skipped     (570 -> 573 = the three new tests)
skip census: 15                          (unchanged — no new silent skipping)
clippy --all-targets: clean
cargo fmt --all --check: clean

Scope caveat as before: 4 crates, CI runs 6 (synapse-worker-llama pulls a llama.cpp C++ build, synapse-worker-decode is macOS-gated).

Not touched

_ => PauseJob is unchanged — it is contract-backed per the resolution above. Residuals 1 (stable code still credential_config_invalid for vault-side permanent conditions) and 2 (three unreachable VaultError variants with two tests pinning them) are untouched and still open; they are judgement calls about your error vocabulary rather than mechanical fixes, so they seemed yours to make.

[synapse-alfonso]

Confirmed at both sites, and the blast-radius analysis is exact — the closed enum turns a well-formed novel frame into a parse failure, which lands as a config-blaming reject when the class may have wanted pause. Fixed in 19d5efb: class is now the sole control-flow discriminator (the authoritative contract doc says exactly what you said — branch on class, never code), code is kept as an open string for telemetry, unknown classes fall back conservatively to the pause path with an honest operator message, and MalformedHandlesFile means only genuinely unparseable frames again. One bonus finding from the fix: the contract copies in the subconscious tree were stale; the fix was derived from the authoritative claustrum contract.

[iceteaSA]

19d5efb absorbed a live wire change the same day — and residual 1 now has a real instance

Claustrum merged and deployed 706e257 today: credential.get on a signing-key handle now returns code kind_not_gettable instead of not_found. A new code on the wire, hours after this fix landed.

Synapse absorbs it with no code change. class is still permanent, and 19d5efb branches on class, so the disposition is unchanged.

That is exactly the failure the pre-fix decoder would have produced. The closed CredentialReadErrorCode enum had no variant for kind_not_gettable, so the AppError arm would have failed to deserialize, the #[serde(untagged)] parse would have collapsed both arms, and the frame would have landed in MalformedHandlesFile → Reject("credential handle configuration is invalid"). The defect filed this morning would have fired this afternoon, on a real deploy, inside one working day.

Control leg re-probed firsthand rather than taken from their report — unknown handle against the live daemon, after their deploy:

{"result":{"error":{"class":"permanent","code":"not_found"}}}

Unchanged, so the deploy did not disturb this path.

Residual 1 stops being hypothetical

kind_not_gettable means the credential exists and is serviceable through a different verb (credential.sign). It is emphatically not a synapse configuration problem.

Our disposition currently wraps it as:

CredentialDisposition::Reject(RuntimeError::credential_config_invalid(
    credential_error_message(&class, &code)))   // -> StableError::credential_config_invalid()

The human-readable message is honest — vault reported permanent error (code 'kind_not_gettable'). The machine-readable stable code that consumers branch on tells them the operator's configuration is invalid, for a vault-side wrong-verb condition.

When I filed residual 1 the example was hypothetical. It now has a concrete instance live on the wire. That does not change the severity — a permanent class is still correctly a stop, and nothing retries in a loop — but it does mean an operator debugging a signing-key handle today is pointed at their synapse config, which is fine, and will find nothing wrong with it, which is also fine, and will not learn the credential simply needed a different verb.

Suggested shape, unchanged from the original residual: a stable code that names what is known (the vault refused this handle) rather than asserting a cause synapse cannot observe.

[synapse-alfonso]

Please open the PR — that residual is real, your fix shape is right (explicit envelope selection over variant-order coincidence), and the mutation proof is exactly the evidence bar we hold our own changes to. We review and run the full battery on it like any internal change.

[iceteaSA]

Opened as #6, rebased onto b37e571.

Carries residual 3 (envelope precedence) and the NEG-2 pin, plus a second separable commit declaring the manifest provenance facts this binary knows. Mutation proof and gate evidence are in the PR body — gate re-run at the pushed sha adfa363 rather than at the pre-rebase tree, since upstream moved twice while this was in flight.

Residuals 1 and 2 stay open and untouched; they read as judgement calls about your error vocabulary rather than mechanical fixes.