RFC: V9 Failure State Machine & Diagnostic Artifacts

[Devaretanmay]

Summary

TokenCircuit is evolving from a simple loop counter to a deterministic execution governance engine. This RFC defines the new EquivalenceKey, the 6-class FailureTaxonomy, and the DiagnosticArtifact that will be attached to every intervention.

The Equivalence Key (Debuggable by Design)

Per production feedback, we are moving away from opaque hashing. The EquivalenceKey will be a frozen dataclass that logs the raw fields used for grouping. If an intervention fires, the developer sees exactly why it was considered equivalent.

@dataclass(frozen=True)
class EquivalenceKey:
    tool_name: str
    resource_class: str | None      # e.g., "sql_namespace", "api_endpoint"
    auth_scope: str | None          # extracted from error headers/config
    error_class: str                # normalized: "permission", "validation", "transient_5xx"
    side_effect_boundary: bool      # True if mutation occurred before failure

The Failure Taxonomy & State Transition Table

Instead of a global max_repeats, each failure class has a strict budget and a defined next-allowed action.

Failure Class	Next Allowed Action	Budget	Verifier Required
transient	Retry with backoff, same intent	+2	Same verifier passes
validation	Ask model/user for corrected args	+1	Args structurally changed
permission/auth	Stop; request auth/scope change	0	N/A
missing_resource	Discovery step or human confirmation	+1	Resource identifier resolved
ambiguous_effect	Reconcile / read-after-write verify	+1	Result confirmed
invariant_violation	Fail closed and page human	0	N/A

The Diagnostic Artifact

When the detector fires, it produces an immutable artifact attached to the TokenCircuitError. This is not just a log; it is the formal proof of the transition.

@dataclass(frozen=True)
class DiagnosticArtifact:
    equivalence_key: EquivalenceKey  # The raw fields, not just a hash
    failure_class: str               # e.g., "permission/auth"
    budget_exhausted: bool
    retry_count: int
    sample_receipts: list[str]       # Last 3 error strings
    safety_justification: str        # WHY it's safe/unsafe to continue

Concrete Test Cases

To ensure this works in production, we are implementing the following invariant tests:

1. Permission/Auth: Same principal, same restricted resource, several different model-generated queries -> budget 0 after first classified failure.
2. Validation: Malformed args where the model gets one repair attempt, then forced summary.
3. Transient: 5xx / timeout with backoff and a small retry budget.
4. Ambiguous/Empty: Distinguish "valid empty" from "query probably wrong" with an explicit verifier.
5. Side-Effect Uncertainty: Tool call may have created something, but read-after-write verification failed. Status is unknown rather than failed. (Crucial to prevent duplicate side effects).

Open Questions

• Should budget deltas be configurable per-deployment via TokenCircuitConfig, or are they fixed constants in the core engine?
• For the side_effect_boundary, what is the most reliable heuristic to detect if a tool mutated state before failing, without relying on the LLM to tell us?

Looking for feedback on the state machine shape and the test cases before we lock this in for V9.