Enum RuntimeError 

pub enum RuntimeError {
    AuditObligation {
        failure: Box<AuditObligationFailure>,
        domain_result: Value,
    },
    Storage(StorageError),
    Sqlite(SqliteError),
    Query(QueryError),
    NotFound(String),
    InvalidInput(String),
    UnknownVerb(String),
    Unconfigured(String),
    UnknownModel(String),
    Embedding(EmbedError),
    Ambiguous(String),
    Fusion(FuseError),
    UnknownFusionStrategy(String),
    Internal(String),
    IncompatibleEventStore(String),
    GuardedWriteFailed(GuardedWriteFailure),
    MissingPackDependency(MissingPackDependency),
    MissingPackDependencies(MissingPackDependencies),
    CircularPackDependency(CircularPackDependency),
    PackRedeclared {
        name: String,
        first_idx: usize,
        second_idx: usize,
    },
    VerbCollision {
        verb: String,
        first_pack: String,
        second_pack: String,
    },
    ReservedEnvelopeParam {
        pack: String,
        verb: String,
        param: String,
    },
    RefusedWithReceipt(Box<ReceiptRefusal>),
    RefusedWithEvents {
        context: RefusalEventContext,
    },
    PermissionDenied {
        verb: String,
        reason: String,
        receipt: Box<DenialReceipt>,
    },
    GateUnavailable {
        verb: String,
        reason: String,
    },
    Khive(KhiveError),
    NamespaceMismatch {
        id: Uuid,
    },
    AmbiguousPrefix {
        prefix: String,
        matches: Vec<Uuid>,
    },
    CrossBackendMergeUnsupported {
        into_id: Uuid,
        from_id: Uuid,
        into_backend: String,
        from_backend: String,
    },
    UnknownRemote {
        name: String,
    },
    RemoteCacheMissing {
        remote: String,
        namespace: String,
    },
    AmbiguousId {
        id: String,
        count: usize,
    },
    CrossNamespaceWrite {
        namespace: String,
    },
    RemoteFetchError {
        remote: String,
        message: String,
    },
    WriteBudgetExceeded {
        max_new_entries: u64,
        attempted_new_entries: u64,
    },
    SecretDetected(SecretMatch),
    DeadlineExceeded {
        operation: String,
        budget_ms: u64,
        elapsed_ms: u64,
    },
}

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.

Variants

AuditObligation

The domain handler succeeded, but its post-dispatch obligation did not.

Fields

failure: Box<AuditObligationFailure>

Typed reason and source of the obligation failure.

domain_result: Value

Exact canonical value held after the domain handler succeeded.

Storage(StorageError)

Sqlite(SqliteError)

Query(QueryError)

NotFound(String)

InvalidInput(String)

UnknownVerb(String)

Unconfigured(String)

UnknownModel(String)

Embedding(EmbedError)

Ambiguous(String)

Fusion(FuseError)

UnknownFusionStrategy(String)

FusionStrategy::Custom { name, .. } named a strategy no pack has registered via KhiveRuntime::register_fusion_strategy (ADR-012). Fails closed — never falls back to RRF or any other default.

Internal(String)

IncompatibleEventStore(String)

An EventStore was configured via with_event_store but does not implement ADR-133’s preflight_event/append_events_idempotent pair (EventStore::supports_idempotent_audit_batch reports false). Raised at build() time rather than left to fail every audited dispatch silently.

GuardedWriteFailed(GuardedWriteFailure)

MissingPackDependency(MissingPackDependency)

MissingPackDependencies(MissingPackDependencies)

CircularPackDependency(CircularPackDependency)

PackRedeclared

Fields

name: String

first_idx: usize

second_idx: usize

VerbCollision

Two packs declared the same Visibility::Verb handler name. Visibility::Subhandler entries are pack-prefixed and do not participate in cross-pack collision checks.

Fields

verb: String

first_pack: String

second_pack: String

ReservedEnvelopeParam

A handler advertised a parameter that request parsing owns at the envelope level.

Fields

pack: String

verb: String

param: String

RefusedWithReceipt(Box<ReceiptRefusal>)

A handler refused the call and wrote a durable receipt naming the refusal.

The durable id rides as its own field. Without it a consumer has to find the id inside the refusal sentence with a regular expression, which makes the wording of a message part of the contract and breaks silently the first time someone rewords it. message keeps whatever text the refusal already produced, so a reader that does parse it today keeps working.

reason is the refusal’s own explanation, the same value the receipt stores, so a consumer keeping its own command record does not parse the sentence for it either. detail carries the surface’s other structured evidence (for exec, the resolved output cap); it must be a JSON object or null, and its members are projected beside the fields above without overriding them.

Boxed so the refusal’s evidence does not widen every Result in the runtime: the error enum is copied on each ?, the refusal is rare.

RefusedWithEvents

Original typed refusal, with recording evidence independent of the refused write. Construct through Self::with_refusal_events so no eligible targets means an unchanged, unadorned refusal.

Fields

context: RefusalEventContext

PermissionDenied

Gate denied this verb invocation.

Returned by VerbRegistry::dispatch when the configured Gate returns GateDecision::Deny. The pack is never invoked. The reason field carries the deny message produced by the gate implementation.

receipt carries the id of the GateDenied audit row when one committed, so the caller can cite the refusal, and says whether such a row exists.

Fields

verb: String

reason: String

receipt: Box<DenialReceipt>

GateUnavailable

The configured gate could not produce an authorization decision.

This is distinct from Self::PermissionDenied: the pack or intercepted operation is never invoked, but the gate did not answer with an explicit denial.

Fields

verb: String

reason: String

Khive(KhiveError)

A structured khive_types::KhiveError converted into the runtime layer. The full structured error is preserved so callers can inspect kind, code, details, and retry_hint without information loss.

NamespaceMismatch

Record exists but belongs to a different namespace than the provided token.

Externally reported as “not found in this namespace” to avoid leaking cross-namespace existence information (timing-oracle mitigation).

Fields

id: Uuid

AmbiguousPrefix

A short-prefix lookup matched more than one record.

prefix is the 8+ hex-char prefix supplied by the caller. matches holds the full UUIDs of all matching records (at most 2 are reported to bound the scan — callers must supply the full UUID to disambiguate).

Fields

prefix: String

matches: Vec<Uuid>

CrossBackendMergeUnsupported

Cross-backend merge_entity is unsupported in v1.

Both entities must reside on the same backend. To merge entities on different backends, manually export from_id, delete it, and re-import on into_id’s backend.

Fields

into_id: Uuid

from_id: Uuid

into_backend: String

from_backend: String

UnknownRemote

A kg:// ref names a remote not declared in schema.yaml.

Fields

name: String

RemoteCacheMissing

A remote cache entry is absent and --fetch was not requested.

Fields

remote: String

namespace: String

AmbiguousId

A short ID matches multiple entities in the same namespace or remote cache.

Fields

id: String

count: usize

CrossNamespaceWrite

A write operation targeted a remote namespace, which is read-only.

Fields

namespace: String

RemoteFetchError

Remote cache setup or repair failed. Producers redact the source and sanitize diagnostics before constructing this wire-visible error.

Fields

remote: String

message: String

WriteBudgetExceeded

A caller-supplied write budget was exceeded during a Compound apply.

max_new_entries is the limit passed by the caller. attempted_new_entries is consumed + 1, i.e. the create that would have exceeded the cap. None budget never produces this error (unlimited path).

Fields

max_new_entries: u64

attempted_new_entries: u64

SecretDetected(SecretMatch)

Write blocked: content matches a secret pattern.

The SecretMatch carries the detector name and a masked excerpt (first6...Nchars). The full candidate is never stored in the error. Store a pointer (env-var name, keychain item) rather than the raw value.

DeadlineExceeded

A bounded per-operation deadline elapsed before the operation completed (#889). The operation may still be running in the background (this is a client-observable timeout, not a cancellation signal to the underlying work) — callers should treat this as “no answer within budget”, not “the operation failed or was rolled back”.

Distinct from #836’s narrower ann_ready_timeout_ms, which bounds only a single cold-miss ANN-build wait inside the recall vector leg and degrades to an in-band FTS-only result. This variant bounds the entire operation end-to-end and is surfaced as a typed error so a caller under sustained contention gets a fast, clear answer instead of hanging until an upstream client-side ceiling (observed at 300s in production, #889) fires instead.

Fields

operation: String

budget_ms: u64

elapsed_ms: u64

Implementations

impl RuntimeError

pub fn with_refusal_events(self, recordings: Vec<RefusalEventRecording>) -> Self

Attach only evidence for established, eligible targets. Missing/new targets contribute no entry, and an empty batch leaves the error variant unchanged.

pub fn refusal_source(&self) -> &Self

Inspect the original typed error without treating event-recording failure as the failed domain operation or losing its policy/retry classification.

pub fn is_stream_policy_refusal(&self) -> bool

Whether the immutable stream record policy refused this write.

Only the structured runtime marker establishes this class. Ordinary conflicts, caller sequence preconditions, and raw storage failures do not acquire a refusal classification from their rendered messages. These membership guards refuse before applying the requested domain write.

pub fn permission_denied( verb: impl Into<String>, reason: impl Into<String>, ) -> Self

A gate refusal from a path that writes no audit row.

pub fn channel_ingest_failure_class(&self) -> ChannelIngestFailureClass

Classify a failed inbound channel write without inspecting rendered error text.

Existing typed safe-retry failures remain retryable. Secret detection is the first deterministic policy refusal and is permanent. None from Self::retryable_failure_context is deliberately not interpreted as permanent: every other variant starts in the bounded Unknown bucket.

pub fn writer_pool_checkout_timeout_context( &self, ) -> Option<WriterPoolCheckoutTimeoutContext>

Recover a finite-wait pool-checkout timeout without inspecting rendered error text.

Store implementations retain khive_db::SqliteError as the typed source of StorageError::Driver; this method carries that structure through the runtime wrapper for the MCP wire serializer. A direct RuntimeError::Sqlite follows the same classification path.

pub fn admission_failure_context(&self) -> Option<AdmissionFailureContext>

Recover either pre-execution write-admission failure this process can produce, by typed variant rather than rendered message text (#1643). Both are safe to classify as retryable: the request was never accepted, so no partial side effect can exist to roll back.

pub fn writer_task_failure_context(&self) -> Option<WriterTaskFailureContext>

Recover writer-request finality without parsing the rendered storage error. Ordinary proven rollbacks and terminal writer failures are deliberately distinct even when they carry the same request state.

pub fn retryable_failure_context(&self) -> Option<RetryableFailureContext>

Recover every typed failure for which this process can prove that retrying the one failed operation cannot duplicate a side effect.

Trait Implementations

impl Debug for RuntimeError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for RuntimeError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for RuntimeError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<EmbedError> for RuntimeError

fn from(source: EmbedError) -> Self

Converts to this type from the input type.

impl From<EntityTypeError> for RuntimeError

Maps the dependency-light khive-types entity-type resolution error onto RuntimeError::InvalidInput at the pack boundary: khive-types cannot depend on khive-runtime, so it cannot produce RuntimeError directly.

fn from(e: EntityTypeError) -> Self

Converts to this type from the input type.

impl From<FuseError> for RuntimeError

fn from(source: FuseError) -> Self

Converts to this type from the input type.

impl From<KhiveError> for RuntimeError

fn from(e: KhiveError) -> Self

Converts to this type from the input type.

impl From<QueryError> for RuntimeError

fn from(source: QueryError) -> Self

Converts to this type from the input type.

impl From<SqliteError> for RuntimeError

fn from(error: SqliteError) -> Self

Converts to this type from the input type.

impl From<StorageError> for RuntimeError

fn from(source: StorageError) -> Self

Converts to this type from the input type.