Error Model

Index treats refusal as a first-class outcome. A request can be well formed and still be refused because its determinism, capability, authorization, or budget contract cannot be satisfied. That is different from no matching vectors and different again from a corrupt artifact or backend defect.

Taxonomy

Error	Meaning	Retry posture
ValidationError	Input shape or value is invalid	Repair the request
InvariantError	A domain rule such as vector dimension or execution-mode compatibility was broken	Repair construction or implementation
ConfigurationError	Backend, embedding, cache, or resource configuration is incomplete or invalid	Repair configuration
DeterminismViolationError	The requested replay or determinism claim cannot be honored	Change inputs or explicitly choose bounded non-determinism
BackendCapabilityError	The selected backend lacks a required operation	Select a capable backend or change the request
BackendUnavailableError	A configured backend cannot be reached or opened	Retry only after checking connectivity and credentials
BudgetExceededError	Latency, memory, error, vector, distance, probe, or request limit was exceeded	Reduce work or explicitly revise the budget
AuthzDeniedError	Authorization policy rejected the operation	Do not retry without new authority
CorruptArtifactError	Stored data failed integrity or compatibility checks	Quarantine and rebuild from trusted inputs
ConflictError or AtomicityViolationError	State versioning or transaction guarantees failed	Resolve state ownership before retrying
BackendDivergenceError	Backend behavior violated the recorded execution contract	Preserve evidence and investigate backend identity
ReplayNotSupportedError	Replay was requested for an execution that did not establish replayability	Treat as non-replayable; do not synthesize parity
ANN and plugin errors	Approximate-index build/query or plugin load/call failed	Follow the recorded capability and retry hint

All package errors carry a message, invariant identifier, and retryability flag. Budget errors additionally retain the exhausted dimension and any explicit partial results. Partial results are evidence of interrupted work, not a successful top-k response.

Refusal path

flowchart TD
    A[Execution request] --> B[Validate invariants]
    B --> C[Check authorization and capability]
    C --> D[Check determinism and budgets]
    D --> E[Execute backend]
    B -- invalid --> F[validation or invariant error]
    C -- cannot satisfy --> G[structured refusal]
    D -- cannot satisfy --> G
    E -- backend defect --> H[operational error]
    E -- success --> I[result and provenance]

The interface refusal envelope names a reason, message, and remediation for configuration, determinism, backend capability, backend availability, and budget failures. Preserve that envelope across HTTP or CLI boundaries. Mapping it to an empty candidate list makes a contract failure indistinguishable from a valid search with no matches.

Outcome and State Are Independent

The error type explains why work stopped; the run state explains what was durably published. Keeping both dimensions avoids treating a stored diagnostic as a completed search.

Outcome	Run state	Consumer rule
admission refusal	no executable run, or retained refusal envelope	change the request, capability, authority, or budget named by the refusal
backend failure after admission	failed when failure finalization succeeds	inspect provenance and retryability; never read it as a result
process interruption	incomplete	retain for diagnosis or explicit recovery; never load as complete
budget failure with partial candidates	failed with diagnostic partials	use partials only to explain exhausted work
valid search with no matches	complete with an empty ordered result set	accept as a successful negative retrieval result

sequenceDiagram
    participant Client
    participant Orchestrator
    participant RunStore
    participant Backend
    Client->>Orchestrator: governed execution request
    Orchestrator->>Orchestrator: validate and admit contract
    alt refused before execution
        Orchestrator-->>Client: refusal envelope
    else admitted
        Orchestrator->>RunStore: begin incomplete run
        Orchestrator->>Backend: execute fingerprinted plan
        alt backend completes
            Backend-->>Orchestrator: ordered results
            Orchestrator->>RunStore: write result, then mark complete
            Orchestrator-->>Client: result and provenance
        else governed failure
            Orchestrator->>RunStore: mark failed with reason
            Orchestrator-->>Client: typed failure
        end
    end

If the process disappears before terminal status is written, incomplete remains the truthful state. Recovery may inspect or supersede that run, but it must not edit history to claim the interrupted execution completed.

Exact and approximate failures

Deterministic requests require strict mode and reject ANN settings. Non-deterministic requests require bounded or exploratory mode, an execution budget, and declared randomness. ANN settings validate recall, candidate pool, diversity, witness, latency, index-memory, and search parameters before work begins.

An approximate low-signal refusal is not backend unavailability. A witness quality failure is not exact-result corruption. Keep the declared loss posture, ANN parameters, witness evidence, and failure reason together.

Replay failures

Replay can fail because the original run was non-replayable, an artifact is missing or corrupt, index or parameter identity changed, the backend diverged, or the comparison exceeded policy. Each cause changes the conclusion. Never report “replay mismatch” without the identity and contract dimension that differed.

Retryability is advisory and local to the failure. A retry creates new execution evidence unless the documented recovery path explicitly resumes the same incomplete run. It must repeat admission checks because backend identity, artifact state, authority, and remaining budget may have changed.