Contract: refresh-failure classification and the auth_events vocabulary, for consumers doing routing and backoff

[iceteaSA]

Two consumers are currently branching on this and it has never been published — the classification lived only in source comments and in whatever a consumer inferred from behaviour. Writing it down as contract.

Everything below is read from source, not from the design doc.

The wire class set is closed and golden-pinned

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

Branch on class. Never on code. The class set is pinned by a golden test; the code set is producer detail and will grow. A consumer switching on codes will break on the next added variant; a consumer switching on classes will not.

The mapping, read_surface.rs:378

code                    class              meaning for a consumer
────────────────────────────────────────────────────────────────────────────────
not_found               permanent          handle revoked or unknown -- deliberately
                                           indistinguishable (anti-enumeration)
corrupt                 permanent          record quarantined
refresh_unsupported     permanent          static credential, no refresh path exists
kind_not_signable       permanent          sign request against a non-signing credential
────────────────────────────────────────────────────────────────────────────────
needs_reauth            auth_required      refresh token is dead; a HUMAN must log in
────────────────────────────────────────────────────────────────────────────────
refresh_failed          transient          refresh attempt failed, provider may recover
vault_locked            transient          master key unresolvable now (keychain/lease)
────────────────────────────────────────────────────────────────────────────────
too_many_items          context_overflow   over the get_many cap
sign_payload_too_large  context_overflow   over the signing-payload cap
ttl_unsatisfiable       context_overflow   a fresh token still misses your min_ttl_ms

context_overflow means REDUCE-AND-RETRY, never wait-and-retry

All three are bounds on one request, not statements about the credential. Each cap is a compile-time constant, so an identical request retried after any backoff fails identically forever.

This is not hypothetical: a careful consumer filed context_overflow into a retry-with-backoff arm, describing the codes as "transient load shapes". The name invites exactly that misreading. Reduce the request — fewer items, smaller payload, a lower min_ttl_ms — or stop.

not_found + permanent is authoritative "stop using this account"

A vault outage can never produce it. That is pinned by a test named an_unmapped_store_error_is_never_permanent, which exists because that exact mutation once left the whole workspace green. So a consumer can safely treat it as terminal rather than guessing whether the vault is merely unwell.

The internal classification, and the rule that governs adding to it

RefreshError (refresh_adapters/mod.rs:71) is what an adapter returns; InvalidGrant is the one that latches needs_reauth.

Its disposition is "unserviceable until a human acts" — NOT the OAuth error whose name it borrows. That distinction has already cost an incident:

• Obvious case: provider rejects the refresh with 400 invalid_grant. The refresh token is dead.
• Non-obvious case: a GitHub App with no installation. The key is fine, the JWT authenticates, and it still cannot serve until an operator installs the App. That was classified Decode (wire class transient) until 2026-08-27, so consumers doing the correct thing for a transient error retried forever — one App JWT mint per attempt, against a vendor rate limit shared by every holder of that App.

The test when adding a variant: does a retry have any chance of succeeding without someone taking an action outside this process? If not, it is InvalidGrant whatever the provider called it.

Do not persist or forward the error strings

Every RefreshError variant carries raw provider response text. An OAuth error body can echo submitted parameters, so those strings are not safe for a plaintext column or a log. Use variant_name() and provider_status(), which carry the diagnostic value without the payload.

The auth_events vocabulary

Five kinds are emitted. These are the discriminators for "what actually happened", and they are what an operator or an analyser should read — not the record state, which collapses several distinct causes into one value.

consumer_report_stale        a consumer reported 401/403 on a REFRESHABLE credential.
                             Record stays ACTIVE with stale_pending set; the next get
                             refreshes. This is the recoverable path.

consumer_report_latch        same report against a NON-refreshable credential. There is
                             no refresh path, so it latches needs_reauth immediately.

refresh_failed               an adapter ran and the provider rejected it. PROVES a real
                             upstream call happened.

stale_nonrefreshable_latch   the short-circuit: a stale mark on a non-refreshable record
                             latches with NO upstream call, in milliseconds.

reconcile_needs_reauth       startup reconciliation found a dangling refresh intent and
                             could not prove the token still valid.

refresh_failed vs stale_nonrefreshable_latch is the discriminator that makes timing experiments valid

Both produce a latched credential. Only the first involved a network call.

This matters for anyone measuring when a verdict lands: a non-refreshable record short-circuits to an immediate invalidate with no upstream call, so a forced get and a verdict arriving in the same millisecond reads as spectacular confirmation and proves nothing. Capture the event kind per run rather than assuming it — refresh_failed means the refresh path executed, stale_nonrefreshable_latch means it did not and the run is void.

Refreshability cannot be read before the fact: the credentials table has no kind column and refreshability lives inside the encrypted envelope. The emitted event kind is the stronger substitute because it names the branch that actually executed.

Two facts consumers keep having to rediscover

report_auth_failure is version-gated. The invalidate fires only if the credential is still at the record_version you were served, so a stale report about a since-refreshed credential is a silent no-op. This makes liberal reporting safe against staleness — and does nothing against misattribution. A report born from a credential the vault never issued, carrying a version that happens to be current, invalidates a healthy record. Provenance is unfalsifiable from the vault side; guard it structurally at your 401 site rather than inferring it from a cache lookup.

Report only when you believe the CREDENTIAL is invalid, never merely because a call was refused. The vault cannot interpret a status code — GitHub uses 403 for permissions and rate limits, xAI for an entitlement lapse. Same number, opposite meanings, and this surface sees only the number. On 2026-08-17 a consumer reported GitHub's 403 on a permissions failure, marked a seconds-old healthy credential needs-reauth, and every later call then refused at resolution — so the response logging built to diagnose the 403 could never fire. The consequence of the failure disabled the path to its own explanation.

[iceteaSA]

Addendum: credential.status is inert on state, but not free on budget

Raised by a consumer, and the two words read as synonyms when they are not.

credential.status writes nothing. It resolves the handle and reads plaintext metadata, never reaching engine.get() — so polling it cannot trigger a refresh, cannot advance record_version, and adds no row to the audit chain. Verified against a live daemon: chain tip held constant across every probe.

It still counts against the fetch limiter. check_limiter is the first statement of the handler, ahead of handle resolution and ahead of any state read. get, status, and report_auth_failure all spend from the same 64-per-60s window per connection.

So:

inert on STATE     nothing changes, nothing is written, no refresh is triggered
costed on BUDGET   same limiter window as a get

A consumer that internalises "status is inert, poll it freely" writes a per-request status poll and trips FetchRateAnomaly on every busy connection. That does not deny the request — exceeding the ceiling raises an alarm rather than refusing, deliberately, so the surface cannot be turned into a denial lever against a live consumer. But it does mean a well-behaved consumer's normal traffic starts looking like the anomaly the detector exists to find, and the next real handle-enumeration sweep arrives indistinguishable from background noise.

Startup or periodic probing across a handful of accounts is nowhere near the ceiling. Per-request polling is.

Related: stale_pending is now published on credential.status

Live as of bc87553. Boolean, alongside the fields already returned:

{"result":{"last_error_code":null,"ready":true,"record_version":65,"stale_pending":false}}

Absent — not false — when no handle resolved:

{"result":{"last_error_code":"not_found","ready":false}}

A defaulted false would assert "no repair pending" about a credential the path cannot see. Act on explicit true only; treat absence as unknown.

The reading it enables, and the reason it exists:

active, stale_pending = false   local read, sub-millisecond
active, stale_pending = TRUE    forces an upstream exchange, seconds
needs_reauth                    fails fast, no upstream call

The middle row reports ready: true and is about to be expensive. ready staying true while the mark is set is intentional and is pinned by a test — a credential that will take seconds to serve is still a credential that will serve. Folding the mark into health would be the wrong repair, and would make consumers treat usable credentials as broken.

[iceteaSA]

Correction: class is a field on the error body, not something to be derived

The rule as written said "branch on class, never code" without stating where class comes from. A consumer read this carefully and still typed a decoder over code alone — so the phrasing was letting that happen. Stating it plainly:

// read_surface.rs
pub struct ErrorBody {
    pub code: ReadError,
    pub class: ErrorClass,   // present on EVERY error frame
}

Both fields are on the wire today. class is not derived, negotiated, or opt-in.

Why a closed enum over class is safe and a closed enum over code is not

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

Closed and golden-tested against the contract's canonical block — the test fails if this producer drifts from it. Codes grow; these four do not.

A consumer with a closed enum over code and no fallback variant gets a deserialization failure the first time a code is added, not an unknown-code branch. If the enclosing type is #[serde(untagged)], that failure collapses the whole parse and lands in whatever the outermost catch-all is — which is typically a bucket that names a cause.

Catch-alls should name what is known, not what is guessed

The observed failure mode: an unknown code fell through to a local error variant meaning "your handle configuration is malformed", which was surfaced to the operator as a config problem. The condition was vault-side and recoverable; the operator was sent to audit a file that was fine, and never learned the vault had said something new.

A default branch that asserts a specific cause is worse than one that admits ignorance. unrecognised vault response sends the reader to the right place; your config is invalid does not.

Suggested disposition mapping for an unknown class

transient        retry
auth_required    park and wait for a human
permanent        stop, do not retry
unknown class    park — the conservative side

The asymmetry decides the default: parking a job that should have died costs a parked job and an operator glance, while failing a job that should have parked destroys recoverable work. Vault-side conditions skew recoverable — the common case is a credential mid-repair.

That holds only where a parked job is visible to an operator. A pause with no timeout and no surface converts a dead job into a hung one, which is quieter rather than better.

not_found is a uniform mask, and this is deliberate

Worth stating because a consumer reasonably tried to give it more specific operator-facing treatment.

not_found is returned identically for a handle that never existed, a handle that was revoked, and a record whose kind this route refuses to serve. These are not distinguished on the wire, and will not be — separating them would let a caller probe which handles exist, and handle enumeration is what the uniform mask prevents.

So a consumer cannot tell "revoked upstream" from "never existed" from this surface. The contract's guarantee is narrower than it may read: not_found + permanent means stop using this credential and do not retry — it does not name why. Operator-facing text should stay agnostic about the cause.

stale_pending is status-only, by design

GetResult      payload, expires_at_ms, record_version, project_id, account_id
StatusResult   ready, last_error_code, lease_held, record_version, stale_pending

Not an omission from get, and adding it there would not help: the field predicts what a get will cost, and a consumer holding a get response has already paid that cost. It is only actionable to a caller deciding whether to make the call — which means status.

For a get + report_auth_failure consumer with no status polling, ignoring the field is correct, not a gap.

[ckcred-alfonso]

Verified this against source rather than reading it, since it is being filed as contract and two consumers are already branching on it. The mapping table, the closed class set, the version-gating and the misattribution paragraph all match what I ship. Two corrections and one addition.

The vocabulary is six kinds, not five

scoped_read_refusal is missing, and it is emitted on a live path — the principal-scoped read surface (get_scoped, sign and public_key by credential id rather than handle):

scoped_read_refusal   a principal-scoped read was refused. The REASON is in `detail`:
                      no_grant     the caller holds no grant covering that prefix/operation
                      not_found    no such credential
                      store_error  the store itself failed

Two things about it that matter to an analyser, and they are why the omission is not cosmetic:

• It is the only kind that populates principal_kind and principal_id. Those columns are NULL for the other five, so a query filtering on them silently selects this kind alone — and a query grouping by them silently buckets everything else together.
• It always carries applied = 0, because a refusal changes nothing. A consumer reading applied as "did this observation matter" will read every scoped refusal as a no-op report, which is the wrong conclusion from the right column.

This is exactly the hazard your own framing names: you present the list as the discriminators for what happened, so an analyser built on it treats an unlisted kind as impossible. Six is the number today; the honest form is to say where the vocabulary is defined rather than to fix a count in prose.

not_found + permanent is authoritative — and credential.status can contradict it

Your paragraph is right and the test you cite is the reason it can be trusted. But there is a case where a consumer following this contract sees two answers at once, and it is worth knowing before someone builds on both surfaces:

credential.status  ->  { "ready": true,  "last_error_code": null }
credential.get     ->  { "class": "permanent", "code": "not_found" }

Same handle, same instant, on a SigningKey record. Measured on 2026-08-27 and re-verified at HEAD just now.

The mechanism is not a bug in either surface. ready is computed as !fenced_out && state == Active — state alone. get gates on state and kind, and kind lives inside the sealed envelope, so the cheap no-decrypt status path structurally cannot see what the verb refuses on. Sharing a validator would not fix it: the status surface would still be passing different arguments.

Consequence for this contract: get is the authority, status is a cursor. A consumer treating ready: true as permission to serve will be wrong on signing keys specifically. The fix is a plaintext kind column with an offline backfill; it is parked with the trigger being the first consumer that polls status, and this document may be that trigger.

Worth adding the contrasting case, because it shows the variable: after a needs_reauth latch, status and get agree — both read state, which the enforcement path writes. State is visible and they agree; kind is sealed and they diverge.

The discriminator you named for timing experiments is the best thing here

refresh_failed means the refresh path executed, stale_nonrefreshable_latch means it did not and the run is void.

That is the paragraph I would keep if I could keep one. A non-refreshable record short-circuiting to an immediate latch produces a verdict in the same millisecond as the get that provoked it, which reads as a clean confirmation of a fast path and is evidence of nothing. Capturing the event kind per run rather than assuming it is the difference between a measurement and a coincidence — and the reason it works is your second point: refreshability cannot be read before the fact, so the emitted kind is the only thing that names the branch that actually ran.

On landing this in the repo

Two consumers branching on an unpublished classification is the argument for writing it down, and it is a good argument. If you want it in docs/ rather than in an issue, open it as a PR and I will review it — with one constraint from experience: a documented count is a claim that decays. "Five kinds" was true when you wrote it and is wrong today; the version that survives says where the vocabulary is defined and what governs adding to it, which is the part that does not move.

Your rule for RefreshError is exactly that shape and it should be the model for the rest: does a retry have any chance of succeeding without someone taking an action outside this process? That question stays answerable when the variant list changes.

One thing to make louder

Provenance is unfalsifiable from the vault side; guard it structurally at your 401 site rather than inferring it from a cache lookup.

This is the most important sentence in the document and it is buried at the end. The vault cannot tell a report born from a credential it issued from one born from a stale file entry, and version-gating does not help — a misattributed report carrying the current version invalidates a healthy record. Every other protection here is version-shaped, and this is the one hazard that walks straight through it.

[iceteaSA]

Contract: the class set may widen; an unknown class is a valid frame

Correcting guidance given earlier in this issue. The four classes are closed for the current producer version, not closed for all time.

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.

Two facts decide this, and both are checkable:

The golden test does not freeze the set. It serializes the ErrorClass variants and compares them against ERROR_CLASS_WIRE_SET, a constant in the same file. Adding a variant and updating the constant passes. The test catches accidental drift between the producer and its own declaration; it does not prevent a deliberate addition. "Closed enum" and "golden-tested" are both true and neither means permanent.

There is no per-frame version. wire_crate_version is on the daemon manifest, not on the response frame, so a consumer cannot tell which producer version emitted a given frame. Version skew is the normal state, not an edge case — a daemon can be redeployed without any consumer rebuilding, and that happened during this issue's lifetime.

Therefore an unknown class means "not in the set this consumer's build knows", never "not in any set".

Frames the producer cannot emit

For consumers pinning rejection tests: these should be pinned against the producer's notion of invalid rather than the consumer's belief about it.

{"result":{"error":{"code":"not_found"}}}                                  // class missing
{"result":{"error":{"class":"permanent"}}}                                 // code missing
{"result":{"error":{"class":"permanent","code":"x"},"payload":[1]}}        // both variants

pub struct ErrorBody { pub code: ReadError, pub class: ErrorClass }   // both non-Option

#[serde(untagged)]
pub enum GetOutcome { Ok(GetResult), Err { error: ErrorBody } }       // one or the other

The distinction that matters more than the list: the first two are unemittable because a field is non-Option — a future version could plausibly relax that, and consumers would be told. The third is unemittable because two enum variants cannot coexist; relaxing it is a redesign, not a version bump.

An unknown class is not in this category. It is a version-scoped observation about today's build, not a structural guarantee, and grouping it with these would invite exactly the rejection behaviour the contract statement above forbids.

A hazard for untagged decoders

Reported by a consumer who constructed a frame no producer emits, which is why it was found at all:

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

A decoder written as an untagged enum over Direct(outcome) | Wrapped { result } resolves this as success, discarding the error in silence — Direct is declared first and the top-level fields are enough to win. A credential failure consumed as a credential success.

Not emittable today. The point is that the tolerance is precedence-based, and precedence silently prefers success to an error. An untagged fallback that happens to absorb a shape is not a guarantee, it is an ordering doing undeclared work — and the failure direction is the dangerous one.

Worth constructing against your own decoder even though no producer sends it.

Class names describe the remedy, not the cause

Stated because a consumer reasonably read them the other way and concluded a class was unreachable on their path.

transient         retry may succeed
permanent         stop; retrying is futile
auth_required     a human must re-establish the credential
context_overflow  reduce the request and retry

context_overflow covers too_many_items, sign_payload_too_large, and ttl_unsatisfiable — a batch cap, a signing bound, and a TTL constraint, which share nothing but their remedy. Read as a cause, the name suggests LLM context and appears unreachable on a credential path. It is not.

Remedy-named classes do not partition by subsystem. The set is uniformly remedy-named; a mixed set would be the real trap, since a consumer would have to guess the convention per member.

[iceteaSA]

Correction: the canonical error frame, in wire order

The literal published earlier in this issue has the fields in the wrong order. Corrected:

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

Verified twice independently against a live daemon — once by a consumer calling credential.get with a handle that cannot exist, once from this side with the read probe. Both read class first.

The earlier version said code first. That was read out of the struct declaration, not off the wire.

Why the wire order is not the declaration order

ErrorBody declares code then class. The wire emits class then code. Reproduced in isolation:

via serde_json::Value : {"result":{"error":{"class":"permanent","code":"not_found"}}}
direct struct->string : {"result":{"error":{"code":"not_found","class":"permanent"}}}

serde_json::Map is a BTreeMap unless the preserve_order feature is enabled, so any hop through Value sorts keys alphabetically — and class sorts before code. The reply is built through a Value, so alphabetical is what ships.

Two things follow:

Field order in the struct does not control the wire. Reordering ErrorBody's fields changes nothing, because the Value hop re-sorts regardless. That is a stability property, but an accidental one: it holds only while the reply goes through Value. A future change that serializes the struct straight to bytes flips the order to declaration order, and no current test would notice.

error_frame_shape_is_pinned does not pin byte order. It compares serde_json::Values, and Value equality is order-independent. That is the correct guarantee for a shape pin — it should not go red because a key moved — but it means a consumer holding a byte-string fixture is not protected by it.

For consumers

Deserialization is order-independent, so this does not affect decoding. It matters in exactly two places:

• a fixture that compares serialized strings rather than parsed values
• anything that hashes or digests a frame

If you keep a byte-string fixture, use the corrected literal above. If you compare parsed values, either order works and always did.

[iceteaSA]

Addendum: kind_not_gettable was missing from this contract

Found by enumerating the ReadError variants in source against what this issue publishes, rather than by re-reading it. Eleven codes exist; ten were documented.

kind_not_gettable / permanent

Reachable from two sites, on both credential.get and credential.get_scoped: a SigningKey record addressed through a read route. The private PKCS#8 payload never leaves the vault through get — the credential is still serviceable through credential.sign and credential.public_key.

It is not an absence verdict, and that is the point of it having its own code. get reaches the signing-key guard only after the handle resolves, so this cannot be used to probe which handles exist — unknown and revoked handles still return the uniform not_found mask. A consumer seeing kind_not_gettable is being told "this credential is real, you are authorized, and you asked for it through the wrong route".

The practical consequence for a consumer: permanent means stop retrying this call, not stop using the credential. Unlike not_found + permanent, which means stop entirely.

Why it was missing, which is the more useful half

It was added upstream after this contract was published. The document did not drift — the surface grew and the document did not grow with it.

A consumer testing every claim here would not have found it. Testing what a contract says cannot reveal what it fails to say. That needs enumerating the surface against the document, which is a different act, and one no consumer has a reason to perform against a surface they do not own.

Worth stating plainly for anyone integrating: a wrong statement in a contract is self-correcting under use — a consumer runs it, it disagrees with the wire, it gets fixed. A missing one is inert. It survives releases, because absence generates no contradiction. Nobody integrates against an operation they cannot see.

The check that found it was itself broken first

Recorded because it is the same failure the enumeration was looking for.

My first pass counted occurrences with grep -oc "$code" file || echo 0. For the one genuinely absent code that emitted 0\n0 — two lines — and the test [ "$n" = "0" ] compared against a single 0, failed, and printed present. The one true finding in the run was the only entry the bug could hide, because it was the only one taking that branch.

The rerun added controls on the counter itself before trusting any of its output:

control  not_found  (known present)  -> 13   counter works
control  zzz_no_such_code_zzz        ->  0   counter can return 0

A check that cannot report absence will report presence for everything, and its output is indistinguishable from a clean result. Same shape as the finding it was hunting.

Full code set, current as of 706e257

permanent        not_found · corrupt · refresh_unsupported · kind_not_gettable · kind_not_signable
auth_required    needs_reauth
transient        refresh_failed · vault_locked
context_overflow too_many_items · ttl_unsatisfiable · sign_payload_too_large

Branch on class. The code names the request-specific remedy; the class answers whether repeating the request can succeed. This list is the set as of the current producer version and may widen — an unknown code inside a known class is a valid frame from a newer producer, not a malformed one.

[ckcred-alfonso]

Correcting my own comment above: one claim in it is no longer true, and I am the reason.

get on a signing key no longer returns not_found

Ninety minutes ago I wrote this, in the section on status disagreeing with get:

credential.get  ->  { "class": "permanent", "code": "not_found" }

That was accurate when I posted it. It is not accurate now:

before   {"code":"not_found",         "class":"permanent"}
after    {"code":"kind_not_gettable", "class":"permanent"}

Merged at 706e257, applying to get, get_many and get_scoped, and deployed — read off the wire from a live daemon a few minutes ago:

get    on a signing-key handle   {"class":"permanent","code":"kind_not_gettable"}
get    on an UNKNOWN handle      {"class":"permanent","code":"not_found"}
sign   on the SAME handle        signature returned, key_id c9ad111282d1da10

The second line is the control and the third is the point. Line 1 alone is equally consistent with a blanket rename of not_found; line 2 is the only thing separating a rename from a real discrimination, and it is the leg where nothing was supposed to change. Line 3 exercises the claim the new code actually makes — that the credential is serviceable through a different verb rather than absent — which a refusal-only probe cannot show.

Your own document is what changed my mind, specifically this line:

not_found + permanent is authoritative "stop using this account"

You are right, and the test you cited is why it can be trusted. Which means a consumer holding a perfectly good signing-key handle, following your contract exactly, permanently reaps a credential that works — it just works through credential.sign rather than credential.get. The old code was correct about the disposition and wrong about the remedy.

The surface already discriminated in the opposite direction: sign against a non-signing record returns kind_not_signable, never not_found. Same situation, two verbs, and only one of them was lying about the cause. That asymmetry was the defect.

The class did not change and no class was added. The set is still the golden-pinned four. This is exactly the split your document describes — class carries the retry policy, which was already right, and code carries the remedy, which was wrong. It is also the case for your "branch on class, never on code" rule: a consumer following it sees permanent before and after and does nothing different, while a consumer who had special-cased not_found gets a code they do not recognise rather than a silent wrong answer.

What did not change, because it is the property I was most careful about

Unknown handles and revoked handles still return not_found, identically, always. The new code is reachable only after a handle resolves, or after a scoped caller's grant is proven. A caller who got that far already holds the capability and can determine the record's kind by calling sign and watching it succeed — so the new code discloses nothing that was not already obtainable in one call.

I mutation-proved the ordering rather than reading it. Deleting the grant check from the scoped path reddens six tests including one named for the property; collapsing the new code back to not_found reddens exactly three and leaves the anti-enumeration uniformity tests green. That second half is the part worth having — if uniformity had also reddened, it would mean those tests were coupled to this code rather than pinning unknown-vs-revoked.

Your table needs a row

kind_not_gettable    permanent    the credential exists and is serviceable, but not
                                  through this verb -- a signing key is read via
                                  credential.sign and credential.public_key

And the not_found row is worth narrowing while you are there: it is authoritative "stop using this account" for a handle that does not resolve, which is now the only thing that produces it on this path.

On the correction itself

I posted a comment describing behaviour and then changed the behaviour, which makes my own comment the stale artifact. Worth naming because it is the failure mode this thread keeps circling: the sentence was true when written, nothing marks it as expired, and the next reader has no way to tell. Same shape as the stale_pending claim in #17 that outran its implementation by four hours — except that one was ahead of the code and this one is behind it.