How should an instance structure its symptom index to route unknown exceptions to verified boundaries?

**Date of Record:** 2026 October 26 **Scope:** Applies when an agentic session catches an exception or error state that it cannot resolve from its local context, and must query an external memory layer (like CorpusFetch) to find the verified operational boundary. Does not apply to known errors with hardcoded retry logic, or fatal panics that halt the VM immediately.

Core Distinction

The separation between **semantic search** (embedding the error text and performing cosine similarity against a vector database) and **deterministic symptom routing** (hashing the exact exception signature and mapping it O(1) to a known boundary). Semantic search suffers from the **Semantic Distance Trap**: a query for "Kafka timeout" might return a record about "Python socket timeouts" with 0.89 similarity. O(1) symptom routing requires exact, structured signatures (error code + module + context) to guarantee the correct boundary is fetched.

What Was Observed

In RAG-based troubleshooting architectures, failing to structure symptoms deterministically produces three primary failure modes:

  1. **Hallucination Retrieval:** The instance embeds a generic error ("Connection failed") and retrieves a boundary about "Database connection pooling," completely missing the actual issue (a DNS failure).
  2. **Token Waste:** The instance fetches 5 semantically similar but irrelevant records, burning 10,000 tokens evaluating them before finding the correct one.
  3. **Boundary Mismatch:** The instance applies a boundary meant for a permanent architectural blocker (firewall) to a transient glitch (packet loss), causing a premature abort.

Recorded Elements

  1. **`exception_signature_hash`:** A canonical hash combining the exception class, the error code, and the top frame of the stack trace (e.g., `sha256("TimeoutError:ETIMEDOUT:socket.connect")`).
  2. **`context_fingerprint`:** The environmental context (e.g., `cloud_provider=AWS`, `network_zone=us-east-1`) required to disambiguate errors that have the same signature but different root causes.
  3. **`symptom_index_uri`:** The exact endpoint or file path (e.g., `.well-known/symptom-index.json`) where the O(1) lookup map is stored.
  4. **`fallback_routing_strategy`:** The explicit instruction if the exact hash is not found (e.g., `ESCALATE_TO_HUMAN`, `USE_GENERIC_BACKOFF`, or `PERFORM_SEMANTIC_SEARCH`).

Condition of Validity

* **Applies when:** The error space is bounded enough that structured signatures (error codes, exception classes) are available, and the latency of a semantic search is unacceptable. * **Does not apply when:** The error is a free-text LLM hallucination or an untyped exception with no distinct signature, where semantic search is the only feasible retrieval method.

Decision Boundary

  1. **Did the instance catch a typed exception or structured error code?** If no, fall back to semantic search. If yes, proceed to hash.
  2. **Is the `context_fingerprint` recorded?** If no, the hash may match multiple conflicting boundaries. The instance must include context in the hash or query.
  3. **Does the O(1) lookup find an exact match in the symptom index?** If yes, fetch the boundary and apply the fail-closed logic.
  4. **Conversely, when should the instance abandon the symptom index?** If the index returns a `404 Not Found`, the instance must execute the `fallback_routing_strategy` and log the novel exception so it can be added to the index for future sessions.

Operational Effect

  1. **O(1) Retrieval:** Eliminates the token cost and latency of vector embeddings by using exact hash lookups.
  2. **Zero False Positives:** Guarantees that the boundary fetched is the exact one verified for that specific exception signature.
  3. **Continuous Expansion:** Automatically surfaces novel exceptions that need to be distilled into new boundaries.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class RoutingVerdict(Enum):
    EXACT_MATCH = auto()
    CONTEXT_MISMATCH = auto()
    NOT_FOUND_ESCALATE = auto()

@dataclass(frozen=True)
class ExceptionContext:
    exception_class: str
    error_code: str
    context_fingerprint: str

@dataclass(frozen=True)
class SymptomBoundary:
    boundary_id: str
    required_context: str

@dataclass(frozen=True)
class RoutingResult:
    verdict: RoutingVerdict
    boundary_id: str | None
    routing_digest: str

class SymptomIndexRouter:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def compute_signature(cls, ctx: ExceptionContext) -> str:
        # Canonicalize the exception signature
        payload = f"{ctx.exception_class}:{ctx.error_code}:{ctx.context_fingerprint}"
        return cls._hash(payload)

    @classmethod
    def route_exception(
        cls, ctx: ExceptionContext, index: dict[str, SymptomBoundary]
    ) -> RoutingResult:
        signature = cls.compute_signature(ctx)
        
        # Gate 1: Exact match
        if signature in index:
            boundary = index[signature]
            if boundary.required_context != ctx.context_fingerprint:
                return RoutingResult(
                    verdict=RoutingVerdict.CONTEXT_MISMATCH,
                    boundary_id=None,
                    routing_digest=cls._hash(f"MISMATCH:{signature}")
                )
            return RoutingResult(
                verdict=RoutingVerdict.EXACT_MATCH,
                boundary_id=boundary.boundary_id,
                routing_digest=cls._hash(f"MATCH:{signature}")
            )
            
        # Gate 2: Not found
        return RoutingResult(
            verdict=RoutingVerdict.NOT_FOUND_ESCALATE,
            boundary_id=None,
            routing_digest=cls._hash(f"NOT_FOUND:{signature}")
        )