Module error 

Runtime error types.

Structs

AdmissionFailureContext

Structured context for a pre-execution admission failure: a finite-wait pooled writer checkout timeout, a bounded write-queue enqueue timeout, or a bounded storage-admission wait (reader/writer handle slot or pooled reader checkout). All happen before SQLite executes the request, so all are safe to classify as retryable — the request was never accepted, let alone started.

AuditObligationFailure

An obligation failure preserves its typed cause and any storage source.

CircularPackDependency

Circular pack dependency detected during topological sort.

DenialReceipt

What a refused dispatch can cite: the GateDenied audit row’s id when one committed, and where the row ended up otherwise. Boxed on the error so a refusal does not widen every Result<_, RuntimeError> in the tree.

DispatchError

An unchanged runtime error with provenance from one dispatch boundary.

GuardedWriteFailure

A guarded edge write (link/link_many) was refused because one or both endpoints no longer existed at write time. Names the exact endpoint(s) missing instead of a generic “source or target” message, and, for a batch write, which entry in the batch failed first.

MissingPackDependencies

Multiple missing pack dependencies collected into one error.

MissingPackDependency

A single missing pack dependency.

ReceiptRefusal

Payload of RuntimeError::RefusedWithReceipt.

RefusalEventContext

Original refusal and the independent evidence of recording it.

ResolutionFacts

Repo-anchor facts established before a git.digest ingest failed.

ResolutionFailureContext

Preserve a resolved anchor’s facts while exposing the original typed error.

RetryableFailureContext

Structured context for a failure that is proven safe to retry.

WriterPoolCheckoutTimeoutContext

Structured context recovered from either a direct SQLite runtime error or a typed SQLite source preserved inside a storage-driver wrapper.

WriterTaskFailureContext

Structured writer-request finality recovered from a storage error.

Enums

AuditObligationReason

Typed cause of a post-dispatch audit or durable-receipt failure.

ChannelIngestFailureClass

Typed disposition for a channel message whose comm.ingest write failed.

DenialAuditOutcome

All errors produced by the khive-runtime layer.

DomainDisposition

What this dispatch boundary can establish about its own domain operation.

RefusalEventRecording

Event evidence for one eligible existing target in a refused request. Failed means no confirmed event, not proof that an ambiguous append wrote nothing.

RefusalRecordingErrorClass

Bounded failure evidence; never carries rejected input or a storage error string.

RuntimeError

Variants cover storage, query, validation, namespace isolation, and permission failures. Callers should match on InvalidInput for bad arguments, NotFound for missing records, and NamespaceMismatch (reported as not-found) for cross-namespace access attempts.

Constants

READ_TX_AGE_EVICTED_STAGE

Stable wire code/stage for a cached read-only transaction proactively rolled back after pinning a WAL snapshot past the configured read_tx_max_age bound (#1846). Always safe to retry: the eviction only ever fires on a read-only handle, so no side effect can exist for a retry to duplicate. Shared by both khive_storage::StorageError::ReadTransactionAgeEvicted (clean rollback) and khive_storage::StorageError::ReadTransactionAgeEvictionCleanupFailed (rollback denied or failed outright) — the rendered message field distinguishes the two; retry behavior is identical for both.

SQLITE_WAL_CAPACITY_REFUSED_STAGE

Stable ADR-194 WAL capacity stages, shared with the SQLite error source. Stable ADR-194 capacity stages. The refusal stage is reserved for the WAL I/O limiter; this configuration-only slice emits only unavailable.

SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE

Stable ADR-194 WAL capacity stages, shared with the SQLite error source.

STORAGE_ADMISSION_TIMEOUT_STAGE

Stable wire code/stage for a bounded storage-admission wait (a reader/writer handle slot or a pooled reader checkout) that elapsed before anything was acquired. The operation never started, so the failure is safe to retry.

WRITER_ADMISSION_SCOPE

Stable ADR-131:251 scope discriminator carried on a WRITER_QUEUE_SATURATED_STAGE failure — distinguishes write-queue admission saturation from other unavailable failure kinds that share the same retryable: true shape but are not bounded by the admission deadline (e.g. WRITER_POOL_CHECKOUT_TIMEOUT_STAGE, which has no ADR-131-defined scope and carries None).

WRITER_POOL_CHECKOUT_TIMEOUT_STAGE

Stable ADR-135 F6 stage and wire code for a finite-wait pooled writer checkout that expires before SQLite executes.

WRITER_QUEUE_SATURATED_STAGE

Stable wire code/stage for a bounded write-queue enqueue that never accepted the request within its configured deadline (#1382, #1643).

WRITER_TASK_BEGIN_BUSY_STAGE

Stable wire code/stage for SQLite write-lock contention after the writer queue accepted a request but before its operation closure ran.

WRITER_TASK_REQUEST_FAILED_STAGE

Stable wire code/stage for an ordinary writer request whose operation or COMMIT failed after the task proved its transaction was rolled back.

WRITER_TASK_TERMINATED_STAGE

Stable wire code/stage for a request reported by a permanently retired writer seam.

Functions

fts_text_leg_or_err

Resolve an FTS text-leg search result, failing loud on parser syntax errors instead of silently degrading to vector-only fusion.

Type Aliases

RuntimeResult

Convenience alias for Result<T, RuntimeError>.