1use std::fmt;
4use std::time::Duration;
5
6use thiserror::Error;
7use uuid::Uuid;
8
9pub type RuntimeResult<T> = Result<T, RuntimeError>;
11
12#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
14#[serde(rename_all = "snake_case")]
15pub enum DomainDisposition {
16 Committed,
18 NotCommitted,
21 Unknown,
23}
24
25impl DomainDisposition {
26 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#[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 pub fn source(&self) -> &RuntimeError {
70 &self.source
71 }
72
73 pub fn disposition(&self) -> DomainDisposition {
75 self.disposition
76 }
77
78 pub fn into_parts(self) -> (RuntimeError, DomainDisposition) {
80 (self.source, self.disposition)
81 }
82
83 pub fn into_source(self) -> RuntimeError {
85 self.source
86 }
87}
88
89#[derive(Debug, Clone, Copy, PartialEq, Eq)]
91pub enum AuditObligationReason {
92 Terminal(crate::audit_batch::AuditTerminalReason),
94 GitDigestReceiptFailure,
96}
97
98#[derive(Debug, Error)]
100#[error("{message}")]
101pub struct AuditObligationFailure {
102 pub reason: AuditObligationReason,
104 pub verb: String,
106 pub message: String,
108 #[source]
109 source: Option<khive_storage::StorageError>,
110}
111
112impl AuditObligationFailure {
113 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 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
168pub const WRITER_POOL_CHECKOUT_TIMEOUT_STAGE: &str = "writer_pool_checkout_timeout";
171
172pub use khive_db::{SQLITE_WAL_CAPACITY_REFUSED_STAGE, SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE};
174
175pub const WRITER_QUEUE_SATURATED_STAGE: &str = "writer_queue_saturated";
178
179pub const WRITER_TASK_BEGIN_BUSY_STAGE: &str = "writer_task_begin_busy";
182
183pub const WRITER_TASK_REQUEST_FAILED_STAGE: &str = "writer_task_request_failed";
186
187pub const WRITER_TASK_TERMINATED_STAGE: &str = "writer_task_terminated";
190
191pub const STORAGE_ADMISSION_TIMEOUT_STAGE: &str = "storage_admission_timeout";
196
197pub const READ_TX_AGE_EVICTED_STAGE: &str = "read_tx_age_evicted";
208
209pub const WRITER_ADMISSION_SCOPE: &str = "writer_admission";
216
217#[derive(Debug, Clone, PartialEq, Eq)]
224pub struct AdmissionFailureContext {
225 pub stage: &'static str,
229 pub timeout: Duration,
231 pub capability: Option<khive_storage::StorageCapability>,
235 pub operation: Option<String>,
237 pub pool_identity: Option<String>,
239 pub scope: Option<&'static str>,
244 pub retry_after_ms: Option<u64>,
250}
251
252#[derive(Debug, Clone, PartialEq, Eq)]
259pub struct RetryableFailureContext {
260 pub stage: &'static str,
262 pub timeout: Duration,
264 pub capability: Option<khive_storage::StorageCapability>,
266 pub operation: Option<String>,
268 pub pool_identity: Option<String>,
270 pub scope: Option<&'static str>,
272 pub retry_after_ms: Option<u64>,
274}
275
276#[derive(Debug, Clone, Copy, PartialEq, Eq)]
283pub struct WriterTaskFailureContext {
284 pub stage: &'static str,
286 pub request_state: khive_storage::WriterTaskRequestState,
288 pub task_terminated: bool,
290 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
314pub enum ChannelIngestFailureClass {
315 Retryable { reason: &'static str },
317 Permanent { reason: &'static str },
319 Unknown { reason: &'static str },
321}
322
323impl ChannelIngestFailureClass {
324 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 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#[derive(Debug, Clone, PartialEq, Eq)]
346pub struct WriterPoolCheckoutTimeoutContext {
347 pub timeout: Duration,
350 pub capability: Option<khive_storage::StorageCapability>,
352 pub operation: Option<String>,
354}
355
356#[derive(Debug, Clone, PartialEq, Eq)]
361pub struct GuardedWriteFailure {
362 pub entry_index: Option<usize>,
365 pub missing_source: Option<Uuid>,
368 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#[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#[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#[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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
458pub enum DenialAuditOutcome {
459 Committed,
462 NotCommitted(&'static str),
465 NoStore,
467 NotAudited,
470}
471
472impl DenialAuditOutcome {
473 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#[derive(Debug, Clone, PartialEq, Eq)]
489pub struct DenialReceipt {
490 pub audit_event_id: Option<uuid::Uuid>,
492 pub audit_outcome: DenialAuditOutcome,
494}
495
496impl DenialReceipt {
497 pub fn not_audited() -> Self {
499 Self {
500 audit_event_id: None,
501 audit_outcome: DenialAuditOutcome::NotAudited,
502 }
503 }
504
505 pub fn no_store() -> Self {
507 Self {
508 audit_event_id: None,
509 audit_outcome: DenialAuditOutcome::NoStore,
510 }
511 }
512}
513
514#[derive(Debug, Clone)]
516pub struct ReceiptRefusal {
517 pub code: &'static str,
519 pub message: String,
521 pub receipt_id: String,
523 pub reason: String,
525 pub detail: serde_json::Value,
527}
528
529#[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#[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#[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#[derive(Debug)]
573pub struct BatchAdmissionReport {
574 pub refused: Vec<BatchRefusal>,
575 pub validation_complete: bool,
576 pub unchecked_indices: Vec<usize>,
577}
578
579#[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#[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#[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#[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#[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#[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#[derive(Debug, Error)]
715pub enum RuntimeError {
716 #[error(transparent)]
718 SearchRead { context: SearchReadContext },
719 #[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 #[error("canonical operation {op_index} refused")]
730 CanonicalAdmission {
731 op_index: usize,
732 #[source]
733 source: Box<RuntimeError>,
734 },
735 #[error("{source}")]
737 LintFix {
738 #[source]
739 source: Box<RuntimeError>,
740 detail: Box<crate::graph_lint::LintFixFailureDetail>,
741 },
742
743 #[error("{failure}")]
745 AuditObligation {
746 #[source]
748 failure: Box<AuditObligationFailure>,
749 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 #[error("unknown fusion strategy: {0}")]
787 UnknownFusionStrategy(String),
788
789 #[error("internal: {0}")]
790 Internal(String),
791
792 #[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 #[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 #[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 #[error("{}", .0.message)]
860 RefusedWithReceipt(Box<ReceiptRefusal>),
861
862 #[error(transparent)]
866 RefusedWithEvents { context: RefusalEventContext },
867
868 #[error(transparent)]
870 BatchWrite { context: Box<BatchWriteContext> },
871
872 #[error(transparent)]
875 WithResolution { context: ResolutionFailureContext },
876
877 #[error("permission denied for verb {verb:?}: {reason}")]
887 PermissionDenied {
888 verb: String,
889 reason: String,
890 receipt: Box<DenialReceipt>,
891 },
892
893 #[error("gate unavailable for verb {verb:?}: {reason}")]
899 GateUnavailable { verb: String, reason: String },
900
901 #[error("{0}")]
905 Khive(khive_types::KhiveError),
906
907 #[error("not found in this namespace")]
912 NamespaceMismatch { id: uuid::Uuid },
913
914 #[error("ambiguous prefix {prefix:?}: matches {}", format_uuid_list(matches))]
920 AmbiguousPrefix {
921 prefix: String,
922 matches: Vec<uuid::Uuid>,
923 },
924
925 #[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 #[error("unknown remote: {name:?}")]
945 UnknownRemote { name: String },
946
947 #[error("remote cache missing for remote={remote:?} namespace={namespace:?}")]
949 RemoteCacheMissing { remote: String, namespace: String },
950
951 #[error("ambiguous id {id:?}: matched {count} records")]
953 AmbiguousId { id: String, count: usize },
954
955 #[error("cross-namespace write denied: cannot write to remote namespace {namespace:?}")]
957 CrossNamespaceWrite { namespace: String },
958
959 #[error("remote fetch error for remote={remote:?}: {message}")]
962 RemoteFetchError { remote: String, message: String },
963
964 #[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 #[error("write blocked: {0}")]
984 SecretDetected(crate::secret_gate::SecretMatch),
985
986 #[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 #[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: u32,
1024 required_version: u32,
1026 },
1027}
1028
1029impl 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 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 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 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 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 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 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 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 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 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 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 pub fn internal_with_context(context: impl fmt::Display, source: impl fmt::Display) -> Self {
1187 Self::Internal(format!("{context}: {source}"))
1188 }
1189
1190 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 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 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 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 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 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
1436pub 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
1472impl 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}