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