§17.1: add a retryable error code for Guardian resource exhaustion

[jrcrittenden]

§17.1 has no code for "the Guardian can't accept this request right now, but a retry later can succeed." The AGT reference Guardian hits this when its replay-protection cache (§10.3) is full. It can't record a new request_id, so accepting the request would leave its replays undetectable, and it has to refuse.

Neither existing option fits:

• -32005 REPLAY_DETECTED is wrong because the request isn't a replay, and its recovery (regenerate request_id) can't succeed.
• -32000 SESSION_REFUSED fails closed correctly, but its recovery says not to retry without a policy or configuration change. This condition clears on its own as cache entries age out of the skew window.

AGT returns -32000 with data.reason: "replay_protection_capacity" for now (#229, a4efc16).

Proposal: add a registry code, for example -32008 GUARDIAN_OVERLOADED, that clients MUST treat as a refusal for the current request and MAY retry after a backoff. The error can carry an optional data.retry_after_ms.

Reported by @shivang-sec on #229.

[jrcrittenden]

A related registry gap came up on #229, raised by @astrogilda's wire probes (probityai/agent-evidence-vectors#119).

The AGT Guardian answers with three codes from the reserved band that §17.1 doesn't list:

• -32010: the envelope failed schema validation, and no deny could be addressed to it (no usable id), or the body was over the size limit.
• -32011: the Guardian has no handler for a method the session negotiated.
• -32020: evaluation itself failed (a policy runtime error, or a Guardian fault caught by the outer net around dispatch).

AGT reads all three as refusal. If a client written only against §17.1 falls back to its availability posture for an unknown error, it fails open under proceed. #229 closed one path to -32020 (51d2de7 now answers an uncanonicalisable signed body with -32004), but a real Guardian fault still answers -32020.

The Fix:

1. A rule for unknown codes: an error response in -32000..-32099 whose code the client doesn't recognise MUST be treated as a refusal for that request, never as an availability failure. That closes the gap for codes added later too. The retryable code proposed above would be the explicit exception, since it says when a retry is allowed.
2. Register the three codes, for example as ENVELOPE_INVALID, METHOD_NOT_DISPATCHED and EVALUATION_FAILED, so SDKs can branch on them rather than treating them as opaque refusals.

[shivang-sec]

One AGT integration detail that may be useful when implementing this: in the PR #229 revision, REFUSAL_RPC_CODES is used both when deciding whether an unsigned refusal can be accepted and when classifying a response as a refusal rather than a generic delivery failure. The proposed -32008 is not currently in that set.

Could the implementation tests cover -32008 through both paths, including a regression test proving that an overload response cannot fall through to on_decision_failure: proceed?

One related point to settle in the spec: the inspected replay store returns "capacity" before recording the new request ID or dispatching the method. Should that ordering be normative for all conforming Guardians, so retrying with the same ID is safe, or should clients use a fresh ID as the proposal suggests?

[jrcrittenden]

@shivang-sec good catch. The host listed the refusal codes it knew, so -32008 would have been classified as a delivery failure and run under proceed. As of 1d6b224 on #229, the host treats -32700 and the whole -32000..-32099 range as a refusal, both when it accepts an unsigned refusal and when it classifies one. That covers -32008 before it's registered. The new test sends an unsigned -32008 to a keyed host under proceed and asserts a guardian_refused deny. -32050 and -32099 are covered as well, and -32601 and -32603 still keep the posture.

On ordering: yes, it should be normative. A Guardian MUST NOT record the request_id of a request it refuses with -32008, so a client MAY retry with the same request_id after the backoff. AGT already does this.