Skip to main content

khive_runtime/
error.rs

1//! Runtime error types.
2
3use std::fmt;
4use std::time::Duration;
5
6use thiserror::Error;
7use uuid::Uuid;
8
9/// Convenience alias for `Result<T, RuntimeError>`.
10pub type RuntimeResult<T> = Result<T, RuntimeError>;
11
12/// What this dispatch boundary can establish about its own domain operation.
13#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
14#[serde(rename_all = "snake_case")]
15pub enum DomainDisposition {
16    /// The handler returned its canonical success value before a later failure.
17    Committed,
18    /// The operation was refused before its handler was invoked.
19    NotCommitted,
20    /// The handler failed, so its domain effects are not established here.
21    Unknown,
22}
23
24impl DomainDisposition {
25    /// Stable wire spelling, shared by request and daemon envelopes.
26    pub const fn as_str(self) -> &'static str {
27        match self {
28            Self::Committed => "committed",
29            Self::NotCommitted => "not_committed",
30            Self::Unknown => "unknown",
31        }
32    }
33}
34
35/// An unchanged runtime error with provenance from one dispatch boundary.
36#[derive(Debug, Error)]
37#[error("{source}")]
38pub struct DispatchError {
39    #[source]
40    source: RuntimeError,
41    disposition: DomainDisposition,
42}
43
44impl DispatchError {
45    pub(crate) fn new(source: RuntimeError, disposition: DomainDisposition) -> Self {
46        Self {
47            source,
48            disposition,
49        }
50    }
51
52    pub(crate) fn before_dispatch(source: RuntimeError) -> Self {
53        Self::new(source, DomainDisposition::NotCommitted)
54    }
55
56    pub(crate) fn after_handler(source: RuntimeError, domain_succeeded: bool) -> Self {
57        let disposition = if domain_succeeded {
58            DomainDisposition::Committed
59        } else {
60            source
61                .batch_write_disposition()
62                .unwrap_or(DomainDisposition::Unknown)
63        };
64        Self::new(source, disposition)
65    }
66
67    /// Borrow the original error without changing its classification.
68    pub fn source(&self) -> &RuntimeError {
69        &self.source
70    }
71
72    /// Read provenance belonging to this dispatch, not to a nested operation.
73    pub fn disposition(&self) -> DomainDisposition {
74        self.disposition
75    }
76
77    /// Separate the original error from its dispatch provenance.
78    pub fn into_parts(self) -> (RuntimeError, DomainDisposition) {
79        (self.source, self.disposition)
80    }
81
82    /// Compatibility path for callers that consume runtime errors directly.
83    pub fn into_source(self) -> RuntimeError {
84        self.source
85    }
86}
87
88/// Typed cause of a post-dispatch audit or durable-receipt failure.
89#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90pub enum AuditObligationReason {
91    /// The audit batch reported one of its closed terminal outcomes.
92    Terminal(crate::audit_batch::AuditTerminalReason),
93    /// Receipt setup failed before submission produced a terminal outcome.
94    GitDigestReceiptFailure,
95}
96
97/// An obligation failure preserves its typed cause and any storage source.
98#[derive(Debug, Error)]
99#[error("{message}")]
100pub struct AuditObligationFailure {
101    /// Machine-readable terminal or receipt-setup cause.
102    pub reason: AuditObligationReason,
103    /// Domain verb whose post-dispatch obligation failed.
104    pub verb: String,
105    /// Stable caller-visible explanation; excludes the canonical domain value.
106    pub message: String,
107    #[source]
108    source: Option<khive_storage::StorageError>,
109}
110
111impl AuditObligationFailure {
112    /// Preserve a terminal audit outcome without parsing its display text.
113    pub fn new(verb: impl Into<String>, reason: crate::audit_batch::AuditTerminalReason) -> Self {
114        let verb = verb.into();
115        Self {
116            message: format!("audit obligation commit failed for verb {verb:?}: {reason:?}"),
117            verb,
118            reason: AuditObligationReason::Terminal(reason),
119            source: None,
120        }
121    }
122
123    pub(crate) fn from_store(verb: &str, source: khive_storage::StorageError) -> Self {
124        let mut failure = Self::new(verb, crate::audit_batch::AuditTerminalReason::StoreFailure);
125        failure.message = format!("audit obligation commit failed for verb {verb:?}: {source}");
126        failure.source = Some(source);
127        failure
128    }
129
130    pub(crate) fn git_digest_receipt(branch: &'static str) -> Self {
131        Self {
132            reason: AuditObligationReason::GitDigestReceiptFailure,
133            verb: "git.digest".into(),
134            message: format!(
135                "git_digest_receipt_persist_failed: {branch}; git.digest writes may have committed, but no durable success receipt was confirmed; inspect ingest state before retrying"
136            ),
137            source: None,
138        }
139    }
140
141    /// Closed wire-code mapping: a new batch terminal reason requires an arm.
142    pub const fn wire_code(&self) -> &'static str {
143        use crate::audit_batch::AuditTerminalReason;
144        match self.reason {
145            AuditObligationReason::Terminal(reason) => match reason {
146                AuditTerminalReason::PreflightRejected => "preflight_rejected",
147                AuditTerminalReason::AdmissionClosed => "admission_closed",
148                AuditTerminalReason::QueueAdmissionExhausted => "queue_admission_exhausted",
149                AuditTerminalReason::AdmissionDeadlineExpired => "admission_deadline_expired",
150                AuditTerminalReason::ResolutionDeadlineExpired => "resolution_deadline_expired",
151                AuditTerminalReason::IdentityConflict => "identity_conflict",
152                AuditTerminalReason::StoreFailure => "store_failure",
153                AuditTerminalReason::RetryExhausted => "retry_exhausted",
154                AuditTerminalReason::IdempotencyUnsupported => "idempotency_unsupported",
155                AuditTerminalReason::DriverPanicked => "driver_panicked",
156                AuditTerminalReason::DriverCancelled => "driver_cancelled",
157                AuditTerminalReason::DriverJoinLost => "driver_join_lost",
158                AuditTerminalReason::DriverExitedInconsistent => "driver_exited_inconsistent",
159                AuditTerminalReason::DriverAppendAbandoned => "driver_append_abandoned",
160                AuditTerminalReason::StoreWedged => "store_wedged",
161            },
162            AuditObligationReason::GitDigestReceiptFailure => "git_digest_receipt_failure",
163        }
164    }
165}
166
167/// Stable ADR-135 F6 stage and wire code for a finite-wait pooled writer
168/// checkout that expires before SQLite executes.
169pub const WRITER_POOL_CHECKOUT_TIMEOUT_STAGE: &str = "writer_pool_checkout_timeout";
170
171/// Stable ADR-194 WAL capacity stages, shared with the SQLite error source.
172pub use khive_db::{SQLITE_WAL_CAPACITY_REFUSED_STAGE, SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE};
173
174/// Stable wire code/stage for a bounded write-queue enqueue that never
175/// accepted the request within its configured deadline (#1382, #1643).
176pub const WRITER_QUEUE_SATURATED_STAGE: &str = "writer_queue_saturated";
177
178/// Stable wire code/stage for SQLite write-lock contention after the writer
179/// queue accepted a request but before its operation closure ran.
180pub const WRITER_TASK_BEGIN_BUSY_STAGE: &str = "writer_task_begin_busy";
181
182/// Stable wire code/stage for an ordinary writer request whose operation or
183/// COMMIT failed after the task proved its transaction was rolled back.
184pub const WRITER_TASK_REQUEST_FAILED_STAGE: &str = "writer_task_request_failed";
185
186/// Stable wire code/stage for a request reported by a permanently retired
187/// writer seam.
188pub const WRITER_TASK_TERMINATED_STAGE: &str = "writer_task_terminated";
189
190/// Stable wire code/stage for a bounded storage-admission wait (a
191/// reader/writer handle slot or a pooled reader checkout) that elapsed
192/// before anything was acquired. The operation never started, so the
193/// failure is safe to retry.
194pub const STORAGE_ADMISSION_TIMEOUT_STAGE: &str = "storage_admission_timeout";
195
196/// Stable wire code/stage for a cached read-only transaction proactively
197/// rolled back after pinning a WAL snapshot past the configured
198/// `read_tx_max_age` bound (#1846). Always safe to retry: the eviction only
199/// ever fires on a read-only handle, so no side effect can exist for a
200/// retry to duplicate. Shared by both
201/// [`khive_storage::StorageError::ReadTransactionAgeEvicted`] (clean
202/// rollback) and
203/// [`khive_storage::StorageError::ReadTransactionAgeEvictionCleanupFailed`]
204/// (rollback denied or failed outright) — the rendered `message` field
205/// distinguishes the two; retry behavior is identical for both.
206pub const READ_TX_AGE_EVICTED_STAGE: &str = "read_tx_age_evicted";
207
208/// Stable ADR-131:251 `scope` discriminator carried on a
209/// [`WRITER_QUEUE_SATURATED_STAGE`] failure — distinguishes write-queue
210/// admission saturation from other `unavailable` failure kinds that share
211/// the same `retryable: true` shape but are not bounded by the admission
212/// deadline (e.g. [`WRITER_POOL_CHECKOUT_TIMEOUT_STAGE`], which has no
213/// ADR-131-defined scope and carries `None`).
214pub const WRITER_ADMISSION_SCOPE: &str = "writer_admission";
215
216/// Structured context for a pre-execution admission failure: a finite-wait
217/// pooled writer checkout timeout, a bounded write-queue enqueue timeout, or
218/// a bounded storage-admission wait (reader/writer handle slot or pooled
219/// reader checkout). All happen before SQLite executes the request, so all
220/// are safe to classify as retryable — the request was never accepted, let
221/// alone started.
222#[derive(Debug, Clone, PartialEq, Eq)]
223pub struct AdmissionFailureContext {
224    /// Stable wire stage/code: one of [`WRITER_POOL_CHECKOUT_TIMEOUT_STAGE`],
225    /// [`WRITER_QUEUE_SATURATED_STAGE`], or
226    /// [`STORAGE_ADMISSION_TIMEOUT_STAGE`].
227    pub stage: &'static str,
228    /// The configured deadline that elapsed.
229    pub timeout: Duration,
230    /// Storage capability the request was scoped to, when known. The write
231    /// queue is process-local and unscoped by capability, so this is `None`
232    /// for [`WRITER_QUEUE_SATURATED_STAGE`].
233    pub capability: Option<khive_storage::StorageCapability>,
234    /// Storage operation name, when known.
235    pub operation: Option<String>,
236    /// Database identity supplied by the pool that refused admission, when known.
237    pub pool_identity: Option<String>,
238    /// ADR-131:251 `scope` discriminator. `Some(`[`WRITER_ADMISSION_SCOPE`]`)`
239    /// for [`WRITER_QUEUE_SATURATED_STAGE`]; `None` for
240    /// [`WRITER_POOL_CHECKOUT_TIMEOUT_STAGE`], which ADR-131 does not define a
241    /// scope for.
242    pub scope: Option<&'static str>,
243    /// ADR-131:251 `retry_after_ms` hint — set equal to the admission
244    /// deadline actually applied to the rejected operation, so a retrying
245    /// caller waits at least one full admission window before retrying.
246    /// `Some(timeout_ms)` for [`WRITER_QUEUE_SATURATED_STAGE`]; `None`
247    /// otherwise.
248    pub retry_after_ms: Option<u64>,
249}
250
251/// Structured context for a failure that is proven safe to retry.
252///
253/// This includes the two pre-admission failures above and writer-task BEGIN
254/// contention after queue acceptance but before operation execution. Callers
255/// must inspect `scope`: only `writer_admission` means the queue never
256/// accepted the operation.
257#[derive(Debug, Clone, PartialEq, Eq)]
258pub struct RetryableFailureContext {
259    /// Stable wire stage/code.
260    pub stage: &'static str,
261    /// Configured wait that ended before execution.
262    pub timeout: Duration,
263    /// Storage capability when the failure is capability-scoped.
264    pub capability: Option<khive_storage::StorageCapability>,
265    /// Storage operation when known.
266    pub operation: Option<String>,
267    /// Database identity supplied by the pool that refused admission, when known.
268    pub pool_identity: Option<String>,
269    /// Admission scope only when the queue never accepted the operation.
270    pub scope: Option<&'static str>,
271    /// Server backoff hint when a governing contract defines one.
272    pub retry_after_ms: Option<u64>,
273}
274
275/// Structured writer-request finality recovered from a storage error.
276///
277/// `request_state` answers whether effects are known absent or ambiguous;
278/// `task_terminated` separately answers whether the writer seam remains
279/// usable. `retryable` retains the source error's transient policy and must
280/// not be inferred from rollback finality alone.
281#[derive(Debug, Clone, Copy, PartialEq, Eq)]
282pub struct WriterTaskFailureContext {
283    /// Stable MCP code/stage for the error family.
284    pub stage: &'static str,
285    /// What the writer can prove about this request's effects.
286    pub request_state: khive_storage::WriterTaskRequestState,
287    /// Whether the writer seam was permanently retired.
288    pub task_terminated: bool,
289    /// Whether the source failure is transient independently of finality.
290    pub retryable: bool,
291}
292
293impl From<AdmissionFailureContext> for RetryableFailureContext {
294    fn from(context: AdmissionFailureContext) -> Self {
295        Self {
296            stage: context.stage,
297            timeout: context.timeout,
298            capability: context.capability,
299            operation: context.operation,
300            pool_identity: context.pool_identity,
301            scope: context.scope,
302            retry_after_ms: context.retry_after_ms,
303        }
304    }
305}
306
307/// Typed disposition for a channel message whose `comm.ingest` write failed.
308///
309/// Every bucket carries the stable [`RuntimeError`] variant name that selected
310/// it. Consumers can therefore make retry/quarantine decisions and report a
311/// reason without inspecting the error's rendered text.
312#[derive(Debug, Clone, Copy, PartialEq, Eq)]
313pub enum ChannelIngestFailureClass {
314    /// A pre-execution admission failure that is safe to retry indefinitely.
315    Retryable { reason: &'static str },
316    /// A deterministic policy refusal that should quarantine immediately.
317    Permanent { reason: &'static str },
318    /// An error with no explicit retry or permanent policy classification.
319    Unknown { reason: &'static str },
320}
321
322impl ChannelIngestFailureClass {
323    /// Stable lowercase bucket name persisted on quarantine notifications.
324    pub const fn name(self) -> &'static str {
325        match self {
326            Self::Retryable { .. } => "retryable",
327            Self::Permanent { .. } => "permanent",
328            Self::Unknown { .. } => "unknown",
329        }
330    }
331
332    /// Stable typed error-variant name; never derived from `Display` output.
333    pub const fn reason(self) -> &'static str {
334        match self {
335            Self::Retryable { reason } | Self::Permanent { reason } | Self::Unknown { reason } => {
336                reason
337            }
338        }
339    }
340}
341
342/// Structured context recovered from either a direct SQLite runtime error or
343/// a typed SQLite source preserved inside a storage-driver wrapper.
344#[derive(Debug, Clone, PartialEq, Eq)]
345pub struct WriterPoolCheckoutTimeoutContext {
346    /// Finite checkout deadline that elapsed before the pooled mutex was
347    /// acquired.
348    pub timeout: Duration,
349    /// Storage capability that wrapped the SQLite source, if one did.
350    pub capability: Option<khive_storage::StorageCapability>,
351    /// Storage operation that wrapped the SQLite source, if one did.
352    pub operation: Option<String>,
353}
354
355/// A guarded edge write (`link`/`link_many`) was refused because one or both
356/// endpoints no longer existed at write time. Names the exact endpoint(s)
357/// missing instead of a generic "source or target" message, and, for a batch
358/// write, which entry in the batch failed first.
359#[derive(Debug, Clone, PartialEq, Eq)]
360pub struct GuardedWriteFailure {
361    /// Index of the failing entry within a `link_many` batch. `None` for the
362    /// singleton `link` path, which has no batch to index into.
363    pub entry_index: Option<usize>,
364    /// The source endpoint id, present only when it is the (or one of the)
365    /// missing endpoint(s).
366    pub missing_source: Option<Uuid>,
367    /// The target endpoint id, present only when it is the (or one of the)
368    /// missing endpoint(s).
369    pub missing_target: Option<Uuid>,
370}
371
372impl fmt::Display for GuardedWriteFailure {
373    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
374        let mut missing = Vec::new();
375        if let Some(source) = self.missing_source {
376            missing.push(format!("source {source}"));
377        }
378        if let Some(target) = self.missing_target {
379            missing.push(format!("target {target}"));
380        }
381        let missing = if missing.is_empty() {
382            "endpoint(s)".to_string()
383        } else {
384            missing.join(" and ")
385        };
386        match self.entry_index {
387            Some(index) => write!(
388                f,
389                "batch entry {index}: {missing} no longer exist at write time"
390            ),
391            None => write!(f, "{missing} no longer exist at write time"),
392        }
393    }
394}
395
396impl std::error::Error for GuardedWriteFailure {}
397
398/// A single missing pack dependency.
399#[derive(Debug, Clone, PartialEq, Eq)]
400pub struct MissingPackDependency {
401    pub from: String,
402    pub requires: String,
403}
404
405impl fmt::Display for MissingPackDependency {
406    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
407        write!(
408            f,
409            "pack '{}' requires '{}', but '{}' is not in the loaded pack set",
410            self.from, self.requires, self.requires
411        )
412    }
413}
414
415impl std::error::Error for MissingPackDependency {}
416
417/// Multiple missing pack dependencies collected into one error.
418#[derive(Debug, Clone, PartialEq, Eq)]
419pub struct MissingPackDependencies {
420    pub missing: Vec<MissingPackDependency>,
421}
422
423impl fmt::Display for MissingPackDependencies {
424    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
425        let parts: Vec<String> = self.missing.iter().map(ToString::to_string).collect();
426        write!(f, "{}", parts.join("; "))
427    }
428}
429
430impl std::error::Error for MissingPackDependencies {}
431
432/// Circular pack dependency detected during topological sort.
433#[derive(Debug, Clone, PartialEq, Eq)]
434pub struct CircularPackDependency {
435    pub cycle: Vec<String>,
436}
437
438impl fmt::Display for CircularPackDependency {
439    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
440        write!(
441            f,
442            "circular dependency detected among packs: {}",
443            self.cycle.join(" -> ")
444        )
445    }
446}
447
448impl std::error::Error for CircularPackDependency {}
449
450/// All errors produced by the khive-runtime layer.
451///
452/// Where the `GateDenied` audit row of a refused dispatch ended up.
453///
454/// A refusal reaches the caller whatever happens to its audit row; this value
455/// says whether the row the caller could cite exists.
456#[derive(Debug, Clone, Copy, PartialEq, Eq)]
457pub enum DenialAuditOutcome {
458    /// The row committed, or an identical row was already present, and
459    /// `audit_event_id` on the refusal names it.
460    Committed,
461    /// The row was built and submitted but did not commit; the audit
462    /// obligation wire code says why.
463    NotCommitted(&'static str),
464    /// No event store is configured, so no row was written.
465    NoStore,
466    /// The refusal comes from a path that writes no audit row (namespace
467    /// authorization, channel policy).
468    NotAudited,
469}
470
471impl DenialAuditOutcome {
472    /// Closed wire spelling: `committed`, `not_committed:<code>`, `no_store`,
473    /// `not_audited`.
474    pub fn wire_code(&self) -> String {
475        match self {
476            Self::Committed => "committed".to_string(),
477            Self::NotCommitted(code) => format!("not_committed:{code}"),
478            Self::NoStore => "no_store".to_string(),
479            Self::NotAudited => "not_audited".to_string(),
480        }
481    }
482}
483
484/// What a refused dispatch can cite: the `GateDenied` audit row's id when
485/// one committed, and where the row ended up otherwise. Boxed on the error
486/// so a refusal does not widen every `Result<_, RuntimeError>` in the tree.
487#[derive(Debug, Clone, PartialEq, Eq)]
488pub struct DenialReceipt {
489    /// The audit row's event id when `audit_outcome` is `Committed`.
490    pub audit_event_id: Option<uuid::Uuid>,
491    /// Whether the row the caller could cite exists.
492    pub audit_outcome: DenialAuditOutcome,
493}
494
495impl DenialReceipt {
496    /// The refusal's path writes no audit row.
497    pub fn not_audited() -> Self {
498        Self {
499            audit_event_id: None,
500            audit_outcome: DenialAuditOutcome::NotAudited,
501        }
502    }
503
504    /// No event store is configured, so no row was written.
505    pub fn no_store() -> Self {
506        Self {
507            audit_event_id: None,
508            audit_outcome: DenialAuditOutcome::NoStore,
509        }
510    }
511}
512
513/// Payload of [`RuntimeError::RefusedWithReceipt`].
514#[derive(Debug, Clone)]
515pub struct ReceiptRefusal {
516    /// Wire `code`, naming which refusal surface produced this.
517    pub code: &'static str,
518    /// The refusal's own sentence, unchanged.
519    pub message: String,
520    /// Id of the durable row the refusal wrote.
521    pub receipt_id: String,
522    /// Why the call was refused, as the receipt records it.
523    pub reason: String,
524    /// Surface-specific structured evidence, an object or `Value::Null`.
525    pub detail: serde_json::Value,
526}
527
528/// Bounded failure evidence; never carries rejected input or a storage error string.
529#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
530#[serde(rename_all = "snake_case")]
531pub enum RefusalRecordingErrorClass {
532    EventStoreUnavailable,
533    EventAppendFailed,
534}
535
536impl RefusalRecordingErrorClass {
537    pub const fn as_str(self) -> &'static str {
538        match self {
539            Self::EventStoreUnavailable => "event_store_unavailable",
540            Self::EventAppendFailed => "event_append_failed",
541        }
542    }
543}
544
545/// Event evidence for one eligible existing target in a refused request.
546/// `Failed` means no confirmed event, not proof that an ambiguous append wrote nothing.
547#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
548#[serde(untagged)]
549pub enum RefusalEventRecording {
550    Recorded {
551        item_index: usize,
552        subject: Uuid,
553        event_id: Uuid,
554    },
555    Failed {
556        item_index: usize,
557        subject: Uuid,
558        error_class: RefusalRecordingErrorClass,
559    },
560}
561
562/// Value-free admission evidence for one original input position.
563#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
564pub struct BatchRefusal {
565    pub index: usize,
566    pub field: &'static str,
567    pub reason: &'static str,
568}
569
570/// Complete or explicitly interrupted record-list admission.
571#[derive(Debug)]
572pub struct BatchAdmissionReport {
573    pub refused: Vec<BatchRefusal>,
574    pub validation_complete: bool,
575    pub unchecked_indices: Vec<usize>,
576}
577
578/// Operation-local proof, independent of any separately recorded refusal events.
579#[derive(Debug)]
580pub struct BatchWriteContext {
581    pub source: Box<RuntimeError>,
582    pub disposition: DomainDisposition,
583    pub admission: Option<BatchAdmissionReport>,
584}
585
586impl fmt::Display for BatchWriteContext {
587    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
588        fmt::Display::fmt(self.source.as_ref(), formatter)
589    }
590}
591
592impl std::error::Error for BatchWriteContext {
593    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
594        Some(self.source.as_ref())
595    }
596}
597
598/// Original refusal and the independent evidence of recording it.
599///
600/// The runtime variant transparently forwards this context's error source, which
601/// deliberately exposes the contained `RuntimeError`, not its `Box` or its own
602/// underlying source. This keeps typed consumers at the original refusal first.
603#[derive(Debug)]
604pub struct RefusalEventContext {
605    pub source: Box<RuntimeError>,
606    pub recordings: Vec<RefusalEventRecording>,
607}
608
609impl std::fmt::Display for RefusalEventContext {
610    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
611        std::fmt::Display::fmt(self.source.as_ref(), formatter)
612    }
613}
614
615impl std::error::Error for RefusalEventContext {
616    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
617        Some(self.source.as_ref())
618    }
619}
620
621/// Repo-anchor facts established before a `git.digest` ingest failed.
622#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
623pub struct ResolutionFacts {
624    pub project_id: Uuid,
625    pub duplicate_anchor_ids: Vec<Uuid>,
626    pub slug_backfilled: bool,
627    pub project_created: bool,
628    pub orphaned_project_id: Option<Uuid>,
629    pub orphaned_note_count: u64,
630}
631
632/// Preserve a resolved anchor's facts while exposing the original typed error.
633#[derive(Debug)]
634pub struct ResolutionFailureContext {
635    pub source: Box<RuntimeError>,
636    pub resolution: ResolutionFacts,
637}
638
639impl std::fmt::Display for ResolutionFailureContext {
640    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
641        std::fmt::Display::fmt(self.source.as_ref(), formatter)
642    }
643}
644
645impl std::error::Error for ResolutionFailureContext {
646    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
647        Some(self.source.as_ref())
648    }
649}
650
651/// Variants cover storage, query, validation, namespace isolation, and permission failures.
652/// Callers should match on `InvalidInput` for bad arguments, `NotFound` for missing records,
653/// and `NamespaceMismatch` (reported as not-found) for cross-namespace access attempts.
654#[derive(Debug, Error)]
655pub enum RuntimeError {
656    /// A decoded canonical operation has no live apply implementation.
657    #[error(
658        "canonical operation {op_index}: {operation} is KnownUnimplemented for canonical apply"
659    )]
660    CanonicalUnsupportedOperation {
661        op_index: usize,
662        operation: &'static str,
663    },
664    /// A constituent was refused before canonical writer admission. Retain
665    /// its typed source without rendering submitted or captured contents.
666    #[error("canonical operation {op_index} refused")]
667    CanonicalAdmission {
668        op_index: usize,
669        #[source]
670        source: Box<RuntimeError>,
671    },
672    /// A lint fix stopped, retaining its exact typed cause and confirmed receipts.
673    #[error("{source}")]
674    LintFix {
675        #[source]
676        source: Box<RuntimeError>,
677        detail: Box<crate::graph_lint::LintFixFailureDetail>,
678    },
679
680    /// The domain handler succeeded, but its post-dispatch obligation did not.
681    #[error("{failure}")]
682    AuditObligation {
683        /// Typed reason and source of the obligation failure.
684        #[source]
685        failure: Box<AuditObligationFailure>,
686        /// Exact canonical value held after the domain handler succeeded.
687        domain_result: serde_json::Value,
688    },
689
690    #[error("storage: {0}")]
691    Storage(#[from] khive_storage::StorageError),
692
693    #[error("query: {0}")]
694    Query(#[from] khive_query::QueryError),
695
696    #[error("not found: {0}")]
697    NotFound(String),
698
699    #[error("invalid input: {0}")]
700    InvalidInput(String),
701
702    #[error("invalid input: {0}")]
703    UnknownVerb(String),
704
705    #[error("unconfigured: {0} is not set")]
706    Unconfigured(String),
707
708    #[error("unknown embedding model: {0}")]
709    UnknownModel(String),
710
711    #[error("embedding: {0}")]
712    Embedding(#[from] lattice_embed::EmbedError),
713
714    #[error("ambiguous: {0}")]
715    Ambiguous(String),
716
717    #[error("fusion: {0}")]
718    Fusion(#[from] khive_fusion::FuseError),
719
720    /// `FusionStrategy::Custom { name, .. }` named a strategy no pack has
721    /// registered via `KhiveRuntime::register_fusion_strategy` (ADR-012).
722    /// Fails closed — never falls back to RRF or any other default.
723    #[error("unknown fusion strategy: {0}")]
724    UnknownFusionStrategy(String),
725
726    #[error("internal: {0}")]
727    Internal(String),
728
729    /// An `EventStore` was configured via `with_event_store` but does not
730    /// implement ADR-133's `preflight_event`/`append_events_idempotent`
731    /// pair (`EventStore::supports_idempotent_audit_batch` reports
732    /// `false`). Raised at `build()` time rather than left to fail every
733    /// audited dispatch silently.
734    #[error("audit batch incompatible event store: {0}")]
735    IncompatibleEventStore(String),
736
737    #[error("guarded edge write refused: {0}")]
738    GuardedWriteFailed(GuardedWriteFailure),
739
740    #[error("missing pack dependency: {0}")]
741    MissingPackDependency(MissingPackDependency),
742
743    #[error("missing pack dependencies: {0}")]
744    MissingPackDependencies(MissingPackDependencies),
745
746    #[error("{0}")]
747    CircularPackDependency(CircularPackDependency),
748
749    #[error("pack '{name}' registered twice (indices {first_idx} and {second_idx})")]
750    PackRedeclared {
751        name: String,
752        first_idx: usize,
753        second_idx: usize,
754    },
755
756    /// Two packs declared the same `Visibility::Verb` handler name.
757    /// `Visibility::Subhandler` entries are pack-prefixed and do not
758    /// participate in cross-pack collision checks.
759    #[error(
760        "verb collision: verb {verb:?} declared by both pack {first_pack:?} and pack \
761         {second_pack:?}; rename one handler or use Visibility::Subhandler for internal verbs"
762    )]
763    VerbCollision {
764        verb: String,
765        first_pack: String,
766        second_pack: String,
767    },
768
769    /// A handler advertised a parameter that request parsing owns at the envelope level.
770    #[error(
771        "pack {pack:?} handler {verb:?} declares request-envelope parameter {param:?}; rename the verb argument"
772    )]
773    ReservedEnvelopeParam {
774        pack: String,
775        verb: String,
776        param: String,
777    },
778
779    /// A handler refused the call and wrote a durable receipt naming the refusal.
780    ///
781    /// The durable id rides as its own field. Without it a consumer has to find
782    /// the id inside the refusal sentence with a regular expression, which makes
783    /// the wording of a message part of the contract and breaks silently the
784    /// first time someone rewords it. `message` keeps whatever text the refusal
785    /// already produced, so a reader that does parse it today keeps working.
786    ///
787    /// `reason` is the refusal's own explanation, the same value the receipt
788    /// stores, so a consumer keeping its own command record does not parse the
789    /// sentence for it either. `detail` carries the surface's other structured
790    /// evidence (for exec, the resolved output cap); it must be a JSON object or
791    /// null, and its members are projected beside the fields above without
792    /// overriding them.
793    ///
794    /// Boxed so the refusal's evidence does not widen every `Result` in the
795    /// runtime: the error enum is copied on each `?`, the refusal is rare.
796    #[error("{}", .0.message)]
797    RefusedWithReceipt(Box<ReceiptRefusal>),
798
799    /// Original typed refusal, with recording evidence independent of the refused write.
800    /// Construct through [`Self::with_refusal_events`] so no eligible targets means
801    /// an unchanged, unadorned refusal.
802    #[error(transparent)]
803    RefusedWithEvents { context: RefusalEventContext },
804
805    /// A batch boundary's typed admission or atomic-write settlement evidence.
806    #[error(transparent)]
807    BatchWrite { context: Box<BatchWriteContext> },
808
809    /// Preserve the original typed failure while carrying facts established
810    /// before a `git.digest` ingest failed.
811    #[error(transparent)]
812    WithResolution { context: ResolutionFailureContext },
813
814    /// Gate denied this verb invocation.
815    ///
816    /// Returned by `VerbRegistry::dispatch` when the configured `Gate` returns
817    /// `GateDecision::Deny`. The pack is never invoked. The `reason` field
818    /// carries the deny message produced by the gate implementation.
819    ///
820    /// `receipt` carries the id of the `GateDenied` audit row when one
821    /// committed, so the caller can cite the refusal, and says whether such
822    /// a row exists.
823    #[error("permission denied for verb {verb:?}: {reason}")]
824    PermissionDenied {
825        verb: String,
826        reason: String,
827        receipt: Box<DenialReceipt>,
828    },
829
830    /// The configured gate could not produce an authorization decision.
831    ///
832    /// This is distinct from [`Self::PermissionDenied`]: the pack or
833    /// intercepted operation is never invoked, but the gate did not answer
834    /// with an explicit denial.
835    #[error("gate unavailable for verb {verb:?}: {reason}")]
836    GateUnavailable { verb: String, reason: String },
837
838    /// A structured [`khive_types::KhiveError`] converted into the runtime
839    /// layer. The full structured error is preserved so callers can inspect
840    /// `kind`, `code`, `details`, and `retry_hint` without information loss.
841    #[error("{0}")]
842    Khive(khive_types::KhiveError),
843
844    /// Record exists but belongs to a different namespace than the provided token.
845    ///
846    /// Externally reported as "not found in this namespace" to avoid leaking
847    /// cross-namespace existence information (timing-oracle mitigation).
848    #[error("not found in this namespace")]
849    NamespaceMismatch { id: uuid::Uuid },
850
851    /// A short-prefix lookup matched more than one record.
852    ///
853    /// `prefix` is the 8+ hex-char prefix supplied by the caller.
854    /// `matches` holds the full UUIDs of all matching records (at most 2 are
855    /// reported to bound the scan — callers must supply the full UUID to disambiguate).
856    #[error("ambiguous prefix {prefix:?}: matches {}", format_uuid_list(matches))]
857    AmbiguousPrefix {
858        prefix: String,
859        matches: Vec<uuid::Uuid>,
860    },
861
862    /// Cross-backend `merge_entity` is unsupported in v1.
863    ///
864    /// Both entities must reside on the same backend. To merge entities on different
865    /// backends, manually export `from_id`, delete it, and re-import on `into_id`'s backend.
866    #[error(
867        "cross-backend merge is not supported: \
868         into_id {into_id} is on backend '{into_backend}', \
869         from_id {from_id} is on backend '{from_backend}'. \
870         Both entities must be on the same backend to merge."
871    )]
872    CrossBackendMergeUnsupported {
873        into_id: uuid::Uuid,
874        from_id: uuid::Uuid,
875        into_backend: String,
876        from_backend: String,
877    },
878
879    // ── Remote Resolution and Content-Hash Verification ──────────────────────
880    /// A `kg://` ref names a remote not declared in `schema.yaml`.
881    #[error("unknown remote: {name:?}")]
882    UnknownRemote { name: String },
883
884    /// A remote cache entry is absent and `--fetch` was not requested.
885    #[error("remote cache missing for remote={remote:?} namespace={namespace:?}")]
886    RemoteCacheMissing { remote: String, namespace: String },
887
888    /// A short ID matches multiple entities in the same namespace or remote cache.
889    #[error("ambiguous id {id:?}: matched {count} records")]
890    AmbiguousId { id: String, count: usize },
891
892    /// A write operation targeted a remote namespace, which is read-only.
893    #[error("cross-namespace write denied: cannot write to remote namespace {namespace:?}")]
894    CrossNamespaceWrite { namespace: String },
895
896    /// Remote cache setup or repair failed. Producers redact the source and
897    /// sanitize diagnostics before constructing this wire-visible error.
898    #[error("remote fetch error for remote={remote:?}: {message}")]
899    RemoteFetchError { remote: String, message: String },
900
901    /// A caller-supplied write budget was exceeded during a Compound apply.
902    ///
903    /// `max_new_entries` is the limit passed by the caller. `attempted_new_entries`
904    /// is `consumed + 1`, i.e. the create that would have exceeded the cap.
905    /// `None` budget never produces this error (unlimited path).
906    #[error(
907        "write budget exceeded: max_new_entries={max_new_entries}, \
908         attempted_new_entries={attempted_new_entries}"
909    )]
910    WriteBudgetExceeded {
911        max_new_entries: u64,
912        attempted_new_entries: u64,
913    },
914
915    /// Write blocked: content matches a secret pattern.
916    ///
917    /// The `SecretMatch` carries the detector name and a masked excerpt
918    /// (`first6...Nchars`). The full candidate is never stored in the error.
919    /// Store a pointer (env-var name, keychain item) rather than the raw value.
920    #[error("write blocked: {0}")]
921    SecretDetected(crate::secret_gate::SecretMatch),
922
923    /// A bounded per-operation deadline elapsed before the operation
924    /// completed (#889). The operation may still be running in the
925    /// background (this is a client-observable timeout, not a cancellation
926    /// signal to the underlying work) — callers should treat this as "no
927    /// answer within budget", not "the operation failed or was rolled back".
928    ///
929    /// Distinct from `#836`'s narrower `ann_ready_timeout_ms`, which bounds
930    /// only a single cold-miss ANN-build wait inside the recall vector leg
931    /// and degrades to an in-band FTS-only result. This variant bounds the
932    /// *entire* operation end-to-end and is surfaced as a typed error so a
933    /// caller under sustained contention gets a fast, clear answer instead
934    /// of hanging until an upstream client-side ceiling (observed at 300s in
935    /// production, #889) fires instead.
936    #[error("{operation} exceeded its {budget_ms}ms deadline (elapsed {elapsed_ms}ms)")]
937    DeadlineExceeded {
938        operation: String,
939        budget_ms: u64,
940        elapsed_ms: u64,
941    },
942}
943
944// Compatibility bridge for concrete backend callers while ADR-071's raw-SQL
945// and backend-handle migrations remain in progress. Classification belongs to
946// the database boundary; the runtime exposes only the storage error envelope.
947impl From<khive_db::SqliteError> for RuntimeError {
948    fn from(error: khive_db::SqliteError) -> Self {
949        Self::Storage(match error {
950            khive_db::SqliteError::RequestReadStopped(error) => error,
951            error => error.into_storage_error(khive_storage::StorageCapability::Sql, "runtime"),
952        })
953    }
954}
955
956impl RuntimeError {
957    /// Certify that this operation refused before attempting requested data writes.
958    pub fn before_requested_write(self) -> Self {
959        Self::BatchWrite {
960            context: Box::new(BatchWriteContext {
961                source: Box::new(self),
962                disposition: DomainDisposition::NotCommitted,
963                admission: None,
964            }),
965        }
966    }
967
968    /// Attach admission evidence established before any requested data write.
969    pub fn with_batch_admission(self, admission: BatchAdmissionReport) -> Self {
970        Self::BatchWrite {
971            context: Box::new(BatchWriteContext {
972                source: Box::new(self),
973                disposition: DomainDisposition::NotCommitted,
974                admission: Some(admission),
975            }),
976        }
977    }
978
979    /// Preserve a single atomic write's actual typed settlement, never its rendered text.
980    pub fn atomic_write_failure(error: khive_storage::StorageError) -> Self {
981        use khive_storage::{StorageError, WriterTaskRequestState};
982        let disposition = match error.without_sqlite_write_stage() {
983            StorageError::WriterTaskRequestFailed { request_state, .. }
984            | StorageError::WriterTaskTerminated { request_state, .. } => match request_state {
985                WriterTaskRequestState::NotStarted
986                | WriterTaskRequestState::TransactionRolledBack => DomainDisposition::NotCommitted,
987                WriterTaskRequestState::SideEffectsUnknown => DomainDisposition::Unknown,
988            },
989            StorageError::WriterTaskBusy { .. }
990            | StorageError::WriteQueueFull { .. }
991            | StorageError::AdmissionTimeout { .. } => DomainDisposition::NotCommitted,
992            _ => DomainDisposition::Unknown,
993        };
994        Self::BatchWrite {
995            context: Box::new(BatchWriteContext {
996                source: Box::new(Self::Storage(error)),
997                disposition,
998                admission: None,
999            }),
1000        }
1001    }
1002
1003    /// Read only this operation's proof, never a nested earlier action's finality.
1004    pub fn batch_write_disposition(&self) -> Option<DomainDisposition> {
1005        match self {
1006            Self::BatchWrite { context } => Some(context.disposition),
1007            Self::RefusedWithEvents { context } => context.source.batch_write_disposition(),
1008            _ => None,
1009        }
1010    }
1011
1012    /// Attach established repo-anchor facts without changing the source error.
1013    pub fn with_resolution(self, resolution: ResolutionFacts) -> Self {
1014        Self::WithResolution {
1015            context: ResolutionFailureContext {
1016                source: Box::new(self),
1017                resolution,
1018            },
1019        }
1020    }
1021
1022    /// Attach only evidence for established, eligible targets. Missing/new targets
1023    /// contribute no entry, and an empty batch leaves the error variant unchanged.
1024    pub fn with_refusal_events(self, mut recordings: Vec<RefusalEventRecording>) -> Self {
1025        if recordings.is_empty() {
1026            return self;
1027        }
1028        match self {
1029            Self::RefusedWithEvents { mut context } => {
1030                context.recordings.append(&mut recordings);
1031                Self::RefusedWithEvents { context }
1032            }
1033            source => Self::RefusedWithEvents {
1034                context: RefusalEventContext {
1035                    source: Box::new(source),
1036                    recordings,
1037                },
1038            },
1039        }
1040    }
1041
1042    /// Inspect the original typed error without losing its policy/retry
1043    /// classification through evidence wrappers.
1044    pub fn refusal_source(&self) -> &Self {
1045        let mut error = self;
1046        loop {
1047            error = match error {
1048                Self::RefusedWithEvents { context } => &context.source,
1049                Self::BatchWrite { context } => &context.source,
1050                Self::WithResolution { context } => context.source.as_ref(),
1051                Self::LintFix { source, .. } => source.as_ref(),
1052                Self::CanonicalAdmission { source, .. } => source.as_ref(),
1053                _ => return error,
1054            };
1055        }
1056    }
1057
1058    /// Whether the immutable stream record policy refused this write.
1059    ///
1060    /// Only the structured runtime marker establishes this class. Ordinary
1061    /// conflicts, caller sequence preconditions, and raw storage failures do
1062    /// not acquire a refusal classification from their rendered messages.
1063    /// These membership guards refuse before applying the requested domain write.
1064    pub fn is_stream_policy_refusal(&self) -> bool {
1065        matches!(self.refusal_source(), Self::Khive(error)
1066            if error.kind() == khive_types::ErrorKind::Conflict
1067                && error.details().and_then(|details| details.get("reason"))
1068                    == Some("stream_member"))
1069    }
1070
1071    /// A gate refusal from a path that writes no audit row.
1072    pub fn permission_denied(verb: impl Into<String>, reason: impl Into<String>) -> Self {
1073        Self::PermissionDenied {
1074            verb: verb.into(),
1075            reason: reason.into(),
1076            receipt: Box::new(DenialReceipt::not_audited()),
1077        }
1078    }
1079
1080    /// An [`Internal`](Self::Internal) error whose message is `context: source`.
1081    ///
1082    /// Storage and SQL failures that have no typed variant of their own use
1083    /// this shape, so the rendered text is defined here once.
1084    pub fn internal_with_context(context: impl fmt::Display, source: impl fmt::Display) -> Self {
1085        Self::Internal(format!("{context}: {source}"))
1086    }
1087
1088    /// Classify a failed inbound channel write without inspecting rendered
1089    /// error text.
1090    ///
1091    /// Existing typed safe-retry failures remain retryable. Secret detection is
1092    /// the first deterministic policy refusal and is permanent. `None` from
1093    /// [`Self::retryable_failure_context`] is deliberately not interpreted as
1094    /// permanent: every other variant starts in the bounded `Unknown` bucket.
1095    pub fn channel_ingest_failure_class(&self) -> ChannelIngestFailureClass {
1096        let source = self.refusal_source();
1097        let reason = source.variant_name();
1098        if source.retryable_failure_context().is_some() {
1099            ChannelIngestFailureClass::Retryable { reason }
1100        } else if matches!(source, Self::SecretDetected(_)) {
1101            ChannelIngestFailureClass::Permanent { reason }
1102        } else {
1103            ChannelIngestFailureClass::Unknown { reason }
1104        }
1105    }
1106
1107    /// Stable top-level variant name used by typed policy classifiers.
1108    fn variant_name(&self) -> &'static str {
1109        match self {
1110            Self::AuditObligation { .. } => "AuditObligation",
1111            Self::Storage(_) => "Storage",
1112            Self::Query(_) => "Query",
1113            Self::NotFound(_) => "NotFound",
1114            Self::InvalidInput(_) => "InvalidInput",
1115            Self::UnknownVerb(_) => "UnknownVerb",
1116            Self::Unconfigured(_) => "Unconfigured",
1117            Self::UnknownModel(_) => "UnknownModel",
1118            Self::Embedding(_) => "Embedding",
1119            Self::Ambiguous(_) => "Ambiguous",
1120            Self::Fusion(_) => "Fusion",
1121            Self::UnknownFusionStrategy(_) => "UnknownFusionStrategy",
1122            Self::Internal(_) => "Internal",
1123            Self::GuardedWriteFailed(_) => "GuardedWriteFailed",
1124            Self::MissingPackDependency(_) => "MissingPackDependency",
1125            Self::MissingPackDependencies(_) => "MissingPackDependencies",
1126            Self::CircularPackDependency(_) => "CircularPackDependency",
1127            Self::PackRedeclared { .. } => "PackRedeclared",
1128            Self::VerbCollision { .. } => "VerbCollision",
1129            Self::ReservedEnvelopeParam { .. } => "ReservedEnvelopeParam",
1130            Self::PermissionDenied { .. } => "PermissionDenied",
1131            Self::GateUnavailable { .. } => "GateUnavailable",
1132            Self::Khive(_) => "Khive",
1133            Self::NamespaceMismatch { .. } => "NamespaceMismatch",
1134            Self::AmbiguousPrefix { .. } => "AmbiguousPrefix",
1135            Self::CrossBackendMergeUnsupported { .. } => "CrossBackendMergeUnsupported",
1136            Self::UnknownRemote { .. } => "UnknownRemote",
1137            Self::RemoteCacheMissing { .. } => "RemoteCacheMissing",
1138            Self::AmbiguousId { .. } => "AmbiguousId",
1139            Self::CrossNamespaceWrite { .. } => "CrossNamespaceWrite",
1140            Self::RemoteFetchError { .. } => "RemoteFetchError",
1141            Self::WriteBudgetExceeded { .. } => "WriteBudgetExceeded",
1142            Self::SecretDetected(_) => "SecretDetected",
1143            Self::DeadlineExceeded { .. } => "DeadlineExceeded",
1144            Self::IncompatibleEventStore(_) => "IncompatibleEventStore",
1145            Self::RefusedWithReceipt { .. } => "RefusedWithReceipt",
1146            Self::RefusedWithEvents { context } => context.source.variant_name(),
1147            Self::BatchWrite { context } => context.source.variant_name(),
1148            Self::WithResolution { context } => context.source.variant_name(),
1149            Self::LintFix { source, .. } => source.variant_name(),
1150            Self::CanonicalAdmission { source, .. } => source.variant_name(),
1151            Self::CanonicalUnsupportedOperation { .. } => "CanonicalUnsupportedOperation",
1152        }
1153    }
1154
1155    /// Recover a finite-wait pool-checkout timeout without inspecting rendered
1156    /// error text.
1157    ///
1158    /// Store implementations retain [`khive_db::SqliteError`] as the typed
1159    /// source of `StorageError::Driver`; this method carries that structure
1160    /// through the runtime wrapper for the MCP wire serializer.
1161    pub fn writer_pool_checkout_timeout_context(&self) -> Option<WriterPoolCheckoutTimeoutContext> {
1162        let (sqlite_error, capability, operation) = match self.refusal_source() {
1163            Self::Storage(khive_storage::StorageError::Driver {
1164                capability,
1165                operation,
1166                source,
1167            }) => (
1168                source.downcast_ref::<khive_db::SqliteError>()?,
1169                Some(*capability),
1170                Some(operation.to_string()),
1171            ),
1172            _ => return None,
1173        };
1174
1175        let khive_db::SqliteError::WriterPoolCheckoutTimeout { timeout } = sqlite_error else {
1176            return None;
1177        };
1178        Some(WriterPoolCheckoutTimeoutContext {
1179            timeout: *timeout,
1180            capability,
1181            operation,
1182        })
1183    }
1184
1185    /// Recover either pre-execution write-admission failure this process can
1186    /// produce, by typed variant rather than rendered message text (#1643).
1187    /// Both are safe to classify as retryable: the request was never
1188    /// accepted, so no partial side effect can exist to roll back.
1189    pub fn admission_failure_context(&self) -> Option<AdmissionFailureContext> {
1190        let source = self.refusal_source();
1191        if let Some(context) = self.writer_pool_checkout_timeout_context() {
1192            return Some(AdmissionFailureContext {
1193                stage: WRITER_POOL_CHECKOUT_TIMEOUT_STAGE,
1194                timeout: context.timeout,
1195                capability: context.capability,
1196                operation: context.operation,
1197                pool_identity: None,
1198                scope: None,
1199                retry_after_ms: None,
1200            });
1201        }
1202        if let Self::Storage(khive_storage::StorageError::WriteQueueFull { timeout_ms }) = source {
1203            return Some(AdmissionFailureContext {
1204                stage: WRITER_QUEUE_SATURATED_STAGE,
1205                timeout: Duration::from_millis(*timeout_ms),
1206                capability: None,
1207                operation: None,
1208                pool_identity: None,
1209                scope: Some(WRITER_ADMISSION_SCOPE),
1210                retry_after_ms: Some(*timeout_ms),
1211            });
1212        }
1213        if let Self::Storage(khive_storage::StorageError::AdmissionTimeout {
1214            operation,
1215            timeout_ms,
1216            pool_identity,
1217        }) = source
1218        {
1219            return Some(AdmissionFailureContext {
1220                stage: STORAGE_ADMISSION_TIMEOUT_STAGE,
1221                timeout: Duration::from_millis(*timeout_ms),
1222                capability: None,
1223                operation: Some(operation.to_string()),
1224                pool_identity: pool_identity.clone(),
1225                scope: None,
1226                retry_after_ms: None,
1227            });
1228        }
1229        None
1230    }
1231
1232    /// Recover writer-request finality without parsing the rendered storage
1233    /// error. Ordinary proven rollbacks and terminal writer failures are
1234    /// deliberately distinct even when they carry the same request state.
1235    pub fn writer_task_failure_context(&self) -> Option<WriterTaskFailureContext> {
1236        let Self::Storage(error) = self.refusal_source() else {
1237            return None;
1238        };
1239        match error.without_sqlite_write_stage() {
1240            khive_storage::StorageError::WriterTaskRequestFailed {
1241                request_state,
1242                source,
1243            } => Some(WriterTaskFailureContext {
1244                stage: WRITER_TASK_REQUEST_FAILED_STAGE,
1245                request_state: *request_state,
1246                task_terminated: false,
1247                retryable: source.is_retryable(),
1248            }),
1249            khive_storage::StorageError::WriterTaskTerminated { request_state, .. } => {
1250                Some(WriterTaskFailureContext {
1251                    stage: WRITER_TASK_TERMINATED_STAGE,
1252                    request_state: *request_state,
1253                    task_terminated: true,
1254                    retryable: false,
1255                })
1256            }
1257            _ => None,
1258        }
1259    }
1260
1261    /// Recover every typed failure for which this process can prove that
1262    /// retrying the one failed operation cannot duplicate a side effect.
1263    pub fn retryable_failure_context(&self) -> Option<RetryableFailureContext> {
1264        let mut enclosing = self;
1265        loop {
1266            match enclosing {
1267                Self::LintFix { .. } => return None,
1268                Self::RefusedWithEvents { context } => enclosing = &context.source,
1269                Self::BatchWrite { context } => enclosing = &context.source,
1270                Self::WithResolution { context } => enclosing = &context.source,
1271                _ => break,
1272            }
1273        }
1274
1275        let source = self.refusal_source();
1276        if let Some(context) = self.admission_failure_context() {
1277            return Some(context.into());
1278        }
1279        if let Self::Storage(error) = source {
1280            if let khive_storage::StorageError::WriterTaskBusy { timeout_ms } =
1281                error.without_sqlite_write_stage()
1282            {
1283                return Some(RetryableFailureContext {
1284                    stage: WRITER_TASK_BEGIN_BUSY_STAGE,
1285                    timeout: Duration::from_millis(*timeout_ms),
1286                    capability: None,
1287                    operation: Some("writer_task_begin".to_string()),
1288                    pool_identity: None,
1289                    scope: None,
1290                    retry_after_ms: None,
1291                });
1292            }
1293        }
1294        if let Self::Storage(khive_storage::StorageError::ReadTransactionAgeEvicted {
1295            operation,
1296            max_age_secs,
1297        }) = source
1298        {
1299            return Some(RetryableFailureContext {
1300                stage: READ_TX_AGE_EVICTED_STAGE,
1301                timeout: Duration::from_secs(*max_age_secs),
1302                capability: Some(khive_storage::StorageCapability::Sql),
1303                operation: Some(operation.to_string()),
1304                pool_identity: None,
1305                scope: None,
1306                retry_after_ms: None,
1307            });
1308        }
1309        if let Self::Storage(
1310            khive_storage::StorageError::ReadTransactionAgeEvictionCleanupFailed {
1311                operation,
1312                max_age_secs,
1313                ..
1314            },
1315        ) = source
1316        {
1317            return Some(RetryableFailureContext {
1318                stage: READ_TX_AGE_EVICTED_STAGE,
1319                timeout: Duration::from_secs(*max_age_secs),
1320                capability: Some(khive_storage::StorageCapability::Sql),
1321                operation: Some(operation.to_string()),
1322                pool_identity: None,
1323                scope: None,
1324                retry_after_ms: None,
1325            });
1326        }
1327        None
1328    }
1329}
1330
1331/// Resolve an FTS text-leg search result, failing loud on parser syntax
1332/// errors instead of silently degrading to vector-only fusion.
1333///
1334/// A genuine backend outage (pool exhaustion, connection failure, etc.) is
1335/// NOT a bad query and is returned as-is via the fallthrough `Err(e)` arm;
1336/// `is_fts5_syntax_error` is the narrow gate that tells the two apart.
1337pub fn fts_text_leg_or_err<T>(
1338    result: Result<Vec<T>, RuntimeError>,
1339    context: &'static str,
1340    query: &str,
1341) -> RuntimeResult<Vec<T>> {
1342    match result {
1343        Ok(hits) => Ok(hits),
1344        Err(RuntimeError::Storage(se)) if se.is_fts5_syntax_error() => {
1345            tracing::warn!(
1346                error = %se,
1347                query = %query,
1348                context,
1349                "FTS text leg failed on a parser syntax error; failing loud (#569)"
1350            );
1351            Err(RuntimeError::InvalidInput(format!(
1352                "{context}: FTS query could not be parsed: {se}"
1353            )))
1354        }
1355        Err(e) => Err(e),
1356    }
1357}
1358
1359fn format_uuid_list(uuids: &[uuid::Uuid]) -> String {
1360    uuids
1361        .iter()
1362        .map(uuid::Uuid::to_string)
1363        .collect::<Vec<_>>()
1364        .join(", ")
1365}
1366
1367/// Maps the dependency-light `khive-types` entity-type resolution error onto
1368/// `RuntimeError::InvalidInput` at the pack boundary: `khive-types` cannot
1369/// depend on `khive-runtime`, so it cannot produce `RuntimeError` directly.
1370impl From<khive_types::EntityTypeError> for RuntimeError {
1371    fn from(e: khive_types::EntityTypeError) -> Self {
1372        Self::InvalidInput(e.to_string())
1373    }
1374}
1375
1376impl From<khive_types::KhiveError> for RuntimeError {
1377    fn from(e: khive_types::KhiveError) -> Self {
1378        Self::Khive(e)
1379    }
1380}
1381
1382#[cfg(test)]
1383#[path = "error_refusal_event_context_tests.rs"]
1384mod refusal_event_context_tests;
1385
1386#[cfg(test)]
1387#[path = "error_stream_policy_refusal_tests.rs"]
1388mod stream_policy_refusal_tests;
1389
1390#[cfg(test)]
1391#[path = "error_channel_ingest_failure_class_tests.rs"]
1392mod channel_ingest_failure_class_tests;
1393
1394#[cfg(test)]
1395mod batch_write_proof_tests {
1396    use super::*;
1397    use crate::runtime_error_value;
1398
1399    fn proof() -> RuntimeError {
1400        RuntimeError::InvalidInput("fixture-prewrite-refusal".into()).before_requested_write()
1401    }
1402
1403    fn project_failed(source: RuntimeError) -> (DomainDisposition, serde_json::Value) {
1404        let error = DispatchError::after_handler(source, false);
1405        let borrowed = error.disposition();
1406        let (source, disposition) = error.into_parts();
1407        assert_eq!(borrowed, disposition);
1408        let value = runtime_error_value(source, disposition);
1409        assert_eq!(value["domain_disposition"], disposition.as_str());
1410        (disposition, value)
1411    }
1412
1413    #[test]
1414    fn batch_proof_reaches_dispatch_owned_parts_and_projection() {
1415        let (disposition, value) = project_failed(proof());
1416        assert_eq!(disposition, DomainDisposition::NotCommitted);
1417        assert!(value["message"]
1418            .as_str()
1419            .unwrap()
1420            .contains("fixture-prewrite-refusal"));
1421        for source in [
1422            RuntimeError::InvalidInput("ordinary".into()),
1423            RuntimeError::Storage(khive_storage::StorageError::Internal(
1424                "ordinary-storage".into(),
1425            )),
1426        ] {
1427            assert_eq!(project_failed(source).0, DomainDisposition::Unknown);
1428        }
1429    }
1430
1431    #[test]
1432    fn enclosing_success_and_unknown_contexts_protect_prior_effects() {
1433        let error = DispatchError::after_handler(proof(), true);
1434        assert_eq!(error.disposition(), DomainDisposition::Committed);
1435        let (source, disposition) = error.into_parts();
1436        assert_eq!(
1437            runtime_error_value(source, disposition)["domain_disposition"],
1438            "committed"
1439        );
1440        assert_eq!(
1441            runtime_error_value(proof(), DomainDisposition::Committed)["domain_disposition"],
1442            "committed"
1443        );
1444        let source = proof().with_resolution(ResolutionFacts {
1445            project_id: Uuid::nil(),
1446            duplicate_anchor_ids: vec![],
1447            slug_backfilled: false,
1448            project_created: true,
1449            orphaned_project_id: None,
1450            orphaned_note_count: 0,
1451        });
1452        assert_eq!(
1453            source.batch_write_disposition(),
1454            None,
1455            "enclosing earlier work blocks an inner no-write proof"
1456        );
1457        let (disposition, value) = project_failed(source);
1458        assert_eq!(disposition, DomainDisposition::Unknown);
1459        assert_eq!(value["details"]["resolution"]["project_created"], true);
1460    }
1461
1462    #[test]
1463    fn batch_evidence_preserves_original_source_and_writer_finality() {
1464        let source = RuntimeError::atomic_write_failure(
1465            khive_storage::StorageError::WriterTaskRequestFailed {
1466                request_state: khive_storage::WriterTaskRequestState::TransactionRolledBack,
1467                source: Box::new(khive_storage::StorageError::Internal(
1468                    "fixture-original-cause".into(),
1469                )),
1470            },
1471        )
1472        .with_refusal_events(vec![RefusalEventRecording::Recorded {
1473            item_index: 0,
1474            subject: Uuid::nil(),
1475            event_id: Uuid::nil(),
1476        }]);
1477        assert!(matches!(source.refusal_source(), RuntimeError::Storage(_)));
1478        assert_eq!(
1479            source.writer_task_failure_context().unwrap().request_state,
1480            khive_storage::WriterTaskRequestState::TransactionRolledBack
1481        );
1482        let mut cause: &(dyn std::error::Error + 'static) = &source;
1483        let mut retained = false;
1484        while let Some(next) = cause.source() {
1485            retained |= next.to_string().contains("fixture-original-cause");
1486            cause = next;
1487        }
1488        assert!(retained, "typed cause remains below the outer error");
1489        let (disposition, value) = project_failed(source);
1490        assert_eq!(disposition, DomainDisposition::NotCommitted);
1491        assert_eq!(value["request_state"], "transaction_rolled_back");
1492        assert_eq!(value["refusal_recorded"], true);
1493        let source = RuntimeError::atomic_write_failure(
1494            khive_storage::StorageError::writer_task_terminated(
1495                khive_storage::WriterTaskRequestState::SideEffectsUnknown,
1496            ),
1497        );
1498        assert_eq!(project_failed(source).0, DomainDisposition::Unknown);
1499    }
1500}