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,
20 Unknown,
22}
23
24impl DomainDisposition {
25 pub const fn as_str(self) -> &'static str {
27 match self {
28 Self::Committed => "committed",
29 Self::NotCommitted => "not_committed",
30 Self::Unknown => "unknown",
31 }
32 }
33}
34
35#[derive(Debug, Error)]
37#[error("{source}")]
38pub struct DispatchError {
39 #[source]
40 source: RuntimeError,
41 disposition: DomainDisposition,
42}
43
44impl DispatchError {
45 pub(crate) fn new(source: RuntimeError, disposition: DomainDisposition) -> Self {
46 Self {
47 source,
48 disposition,
49 }
50 }
51
52 pub(crate) fn before_dispatch(source: RuntimeError) -> Self {
53 Self::new(source, DomainDisposition::NotCommitted)
54 }
55
56 pub(crate) fn after_handler(source: RuntimeError, domain_succeeded: bool) -> Self {
57 let disposition = if domain_succeeded {
58 DomainDisposition::Committed
59 } else {
60 source
61 .batch_write_disposition()
62 .unwrap_or(DomainDisposition::Unknown)
63 };
64 Self::new(source, disposition)
65 }
66
67 pub fn source(&self) -> &RuntimeError {
69 &self.source
70 }
71
72 pub fn disposition(&self) -> DomainDisposition {
74 self.disposition
75 }
76
77 pub fn into_parts(self) -> (RuntimeError, DomainDisposition) {
79 (self.source, self.disposition)
80 }
81
82 pub fn into_source(self) -> RuntimeError {
84 self.source
85 }
86}
87
88#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90pub enum AuditObligationReason {
91 Terminal(crate::audit_batch::AuditTerminalReason),
93 GitDigestReceiptFailure,
95}
96
97#[derive(Debug, Error)]
99#[error("{message}")]
100pub struct AuditObligationFailure {
101 pub reason: AuditObligationReason,
103 pub verb: String,
105 pub message: String,
107 #[source]
108 source: Option<khive_storage::StorageError>,
109}
110
111impl AuditObligationFailure {
112 pub fn new(verb: impl Into<String>, reason: crate::audit_batch::AuditTerminalReason) -> Self {
114 let verb = verb.into();
115 Self {
116 message: format!("audit obligation commit failed for verb {verb:?}: {reason:?}"),
117 verb,
118 reason: AuditObligationReason::Terminal(reason),
119 source: None,
120 }
121 }
122
123 pub(crate) fn from_store(verb: &str, source: khive_storage::StorageError) -> Self {
124 let mut failure = Self::new(verb, crate::audit_batch::AuditTerminalReason::StoreFailure);
125 failure.message = format!("audit obligation commit failed for verb {verb:?}: {source}");
126 failure.source = Some(source);
127 failure
128 }
129
130 pub(crate) fn git_digest_receipt(branch: &'static str) -> Self {
131 Self {
132 reason: AuditObligationReason::GitDigestReceiptFailure,
133 verb: "git.digest".into(),
134 message: format!(
135 "git_digest_receipt_persist_failed: {branch}; git.digest writes may have committed, but no durable success receipt was confirmed; inspect ingest state before retrying"
136 ),
137 source: None,
138 }
139 }
140
141 pub const fn wire_code(&self) -> &'static str {
143 use crate::audit_batch::AuditTerminalReason;
144 match self.reason {
145 AuditObligationReason::Terminal(reason) => match reason {
146 AuditTerminalReason::PreflightRejected => "preflight_rejected",
147 AuditTerminalReason::AdmissionClosed => "admission_closed",
148 AuditTerminalReason::QueueAdmissionExhausted => "queue_admission_exhausted",
149 AuditTerminalReason::AdmissionDeadlineExpired => "admission_deadline_expired",
150 AuditTerminalReason::ResolutionDeadlineExpired => "resolution_deadline_expired",
151 AuditTerminalReason::IdentityConflict => "identity_conflict",
152 AuditTerminalReason::StoreFailure => "store_failure",
153 AuditTerminalReason::RetryExhausted => "retry_exhausted",
154 AuditTerminalReason::IdempotencyUnsupported => "idempotency_unsupported",
155 AuditTerminalReason::DriverPanicked => "driver_panicked",
156 AuditTerminalReason::DriverCancelled => "driver_cancelled",
157 AuditTerminalReason::DriverJoinLost => "driver_join_lost",
158 AuditTerminalReason::DriverExitedInconsistent => "driver_exited_inconsistent",
159 AuditTerminalReason::DriverAppendAbandoned => "driver_append_abandoned",
160 AuditTerminalReason::StoreWedged => "store_wedged",
161 },
162 AuditObligationReason::GitDigestReceiptFailure => "git_digest_receipt_failure",
163 }
164 }
165}
166
167pub const WRITER_POOL_CHECKOUT_TIMEOUT_STAGE: &str = "writer_pool_checkout_timeout";
170
171pub use khive_db::{SQLITE_WAL_CAPACITY_REFUSED_STAGE, SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE};
173
174pub const WRITER_QUEUE_SATURATED_STAGE: &str = "writer_queue_saturated";
177
178pub const WRITER_TASK_BEGIN_BUSY_STAGE: &str = "writer_task_begin_busy";
181
182pub const WRITER_TASK_REQUEST_FAILED_STAGE: &str = "writer_task_request_failed";
185
186pub const WRITER_TASK_TERMINATED_STAGE: &str = "writer_task_terminated";
189
190pub const STORAGE_ADMISSION_TIMEOUT_STAGE: &str = "storage_admission_timeout";
195
196pub const READ_TX_AGE_EVICTED_STAGE: &str = "read_tx_age_evicted";
207
208pub const WRITER_ADMISSION_SCOPE: &str = "writer_admission";
215
216#[derive(Debug, Clone, PartialEq, Eq)]
223pub struct AdmissionFailureContext {
224 pub stage: &'static str,
228 pub timeout: Duration,
230 pub capability: Option<khive_storage::StorageCapability>,
234 pub operation: Option<String>,
236 pub pool_identity: Option<String>,
238 pub scope: Option<&'static str>,
243 pub retry_after_ms: Option<u64>,
249}
250
251#[derive(Debug, Clone, PartialEq, Eq)]
258pub struct RetryableFailureContext {
259 pub stage: &'static str,
261 pub timeout: Duration,
263 pub capability: Option<khive_storage::StorageCapability>,
265 pub operation: Option<String>,
267 pub pool_identity: Option<String>,
269 pub scope: Option<&'static str>,
271 pub retry_after_ms: Option<u64>,
273}
274
275#[derive(Debug, Clone, Copy, PartialEq, Eq)]
282pub struct WriterTaskFailureContext {
283 pub stage: &'static str,
285 pub request_state: khive_storage::WriterTaskRequestState,
287 pub task_terminated: bool,
289 pub retryable: bool,
291}
292
293impl From<AdmissionFailureContext> for RetryableFailureContext {
294 fn from(context: AdmissionFailureContext) -> Self {
295 Self {
296 stage: context.stage,
297 timeout: context.timeout,
298 capability: context.capability,
299 operation: context.operation,
300 pool_identity: context.pool_identity,
301 scope: context.scope,
302 retry_after_ms: context.retry_after_ms,
303 }
304 }
305}
306
307#[derive(Debug, Clone, Copy, PartialEq, Eq)]
313pub enum ChannelIngestFailureClass {
314 Retryable { reason: &'static str },
316 Permanent { reason: &'static str },
318 Unknown { reason: &'static str },
320}
321
322impl ChannelIngestFailureClass {
323 pub const fn name(self) -> &'static str {
325 match self {
326 Self::Retryable { .. } => "retryable",
327 Self::Permanent { .. } => "permanent",
328 Self::Unknown { .. } => "unknown",
329 }
330 }
331
332 pub const fn reason(self) -> &'static str {
334 match self {
335 Self::Retryable { reason } | Self::Permanent { reason } | Self::Unknown { reason } => {
336 reason
337 }
338 }
339 }
340}
341
342#[derive(Debug, Clone, PartialEq, Eq)]
345pub struct WriterPoolCheckoutTimeoutContext {
346 pub timeout: Duration,
349 pub capability: Option<khive_storage::StorageCapability>,
351 pub operation: Option<String>,
353}
354
355#[derive(Debug, Clone, PartialEq, Eq)]
360pub struct GuardedWriteFailure {
361 pub entry_index: Option<usize>,
364 pub missing_source: Option<Uuid>,
367 pub missing_target: Option<Uuid>,
370}
371
372impl fmt::Display for GuardedWriteFailure {
373 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
374 let mut missing = Vec::new();
375 if let Some(source) = self.missing_source {
376 missing.push(format!("source {source}"));
377 }
378 if let Some(target) = self.missing_target {
379 missing.push(format!("target {target}"));
380 }
381 let missing = if missing.is_empty() {
382 "endpoint(s)".to_string()
383 } else {
384 missing.join(" and ")
385 };
386 match self.entry_index {
387 Some(index) => write!(
388 f,
389 "batch entry {index}: {missing} no longer exist at write time"
390 ),
391 None => write!(f, "{missing} no longer exist at write time"),
392 }
393 }
394}
395
396impl std::error::Error for GuardedWriteFailure {}
397
398#[derive(Debug, Clone, PartialEq, Eq)]
400pub struct MissingPackDependency {
401 pub from: String,
402 pub requires: String,
403}
404
405impl fmt::Display for MissingPackDependency {
406 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
407 write!(
408 f,
409 "pack '{}' requires '{}', but '{}' is not in the loaded pack set",
410 self.from, self.requires, self.requires
411 )
412 }
413}
414
415impl std::error::Error for MissingPackDependency {}
416
417#[derive(Debug, Clone, PartialEq, Eq)]
419pub struct MissingPackDependencies {
420 pub missing: Vec<MissingPackDependency>,
421}
422
423impl fmt::Display for MissingPackDependencies {
424 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
425 let parts: Vec<String> = self.missing.iter().map(ToString::to_string).collect();
426 write!(f, "{}", parts.join("; "))
427 }
428}
429
430impl std::error::Error for MissingPackDependencies {}
431
432#[derive(Debug, Clone, PartialEq, Eq)]
434pub struct CircularPackDependency {
435 pub cycle: Vec<String>,
436}
437
438impl fmt::Display for CircularPackDependency {
439 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
440 write!(
441 f,
442 "circular dependency detected among packs: {}",
443 self.cycle.join(" -> ")
444 )
445 }
446}
447
448impl std::error::Error for CircularPackDependency {}
449
450#[derive(Debug, Clone, Copy, PartialEq, Eq)]
457pub enum DenialAuditOutcome {
458 Committed,
461 NotCommitted(&'static str),
464 NoStore,
466 NotAudited,
469}
470
471impl DenialAuditOutcome {
472 pub fn wire_code(&self) -> String {
475 match self {
476 Self::Committed => "committed".to_string(),
477 Self::NotCommitted(code) => format!("not_committed:{code}"),
478 Self::NoStore => "no_store".to_string(),
479 Self::NotAudited => "not_audited".to_string(),
480 }
481 }
482}
483
484#[derive(Debug, Clone, PartialEq, Eq)]
488pub struct DenialReceipt {
489 pub audit_event_id: Option<uuid::Uuid>,
491 pub audit_outcome: DenialAuditOutcome,
493}
494
495impl DenialReceipt {
496 pub fn not_audited() -> Self {
498 Self {
499 audit_event_id: None,
500 audit_outcome: DenialAuditOutcome::NotAudited,
501 }
502 }
503
504 pub fn no_store() -> Self {
506 Self {
507 audit_event_id: None,
508 audit_outcome: DenialAuditOutcome::NoStore,
509 }
510 }
511}
512
513#[derive(Debug, Clone)]
515pub struct ReceiptRefusal {
516 pub code: &'static str,
518 pub message: String,
520 pub receipt_id: String,
522 pub reason: String,
524 pub detail: serde_json::Value,
526}
527
528#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
530#[serde(rename_all = "snake_case")]
531pub enum RefusalRecordingErrorClass {
532 EventStoreUnavailable,
533 EventAppendFailed,
534}
535
536impl RefusalRecordingErrorClass {
537 pub const fn as_str(self) -> &'static str {
538 match self {
539 Self::EventStoreUnavailable => "event_store_unavailable",
540 Self::EventAppendFailed => "event_append_failed",
541 }
542 }
543}
544
545#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
548#[serde(untagged)]
549pub enum RefusalEventRecording {
550 Recorded {
551 item_index: usize,
552 subject: Uuid,
553 event_id: Uuid,
554 },
555 Failed {
556 item_index: usize,
557 subject: Uuid,
558 error_class: RefusalRecordingErrorClass,
559 },
560}
561
562#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
564pub struct BatchRefusal {
565 pub index: usize,
566 pub field: &'static str,
567 pub reason: &'static str,
568}
569
570#[derive(Debug)]
572pub struct BatchAdmissionReport {
573 pub refused: Vec<BatchRefusal>,
574 pub validation_complete: bool,
575 pub unchecked_indices: Vec<usize>,
576}
577
578#[derive(Debug)]
580pub struct BatchWriteContext {
581 pub source: Box<RuntimeError>,
582 pub disposition: DomainDisposition,
583 pub admission: Option<BatchAdmissionReport>,
584}
585
586impl fmt::Display for BatchWriteContext {
587 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
588 fmt::Display::fmt(self.source.as_ref(), formatter)
589 }
590}
591
592impl std::error::Error for BatchWriteContext {
593 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
594 Some(self.source.as_ref())
595 }
596}
597
598#[derive(Debug)]
604pub struct RefusalEventContext {
605 pub source: Box<RuntimeError>,
606 pub recordings: Vec<RefusalEventRecording>,
607}
608
609impl std::fmt::Display for RefusalEventContext {
610 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
611 std::fmt::Display::fmt(self.source.as_ref(), formatter)
612 }
613}
614
615impl std::error::Error for RefusalEventContext {
616 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
617 Some(self.source.as_ref())
618 }
619}
620
621#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
623pub struct ResolutionFacts {
624 pub project_id: Uuid,
625 pub duplicate_anchor_ids: Vec<Uuid>,
626 pub slug_backfilled: bool,
627 pub project_created: bool,
628 pub orphaned_project_id: Option<Uuid>,
629 pub orphaned_note_count: u64,
630}
631
632#[derive(Debug)]
634pub struct ResolutionFailureContext {
635 pub source: Box<RuntimeError>,
636 pub resolution: ResolutionFacts,
637}
638
639impl std::fmt::Display for ResolutionFailureContext {
640 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
641 std::fmt::Display::fmt(self.source.as_ref(), formatter)
642 }
643}
644
645impl std::error::Error for ResolutionFailureContext {
646 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
647 Some(self.source.as_ref())
648 }
649}
650
651#[derive(Debug, Error)]
655pub enum RuntimeError {
656 #[error(
658 "canonical operation {op_index}: {operation} is KnownUnimplemented for canonical apply"
659 )]
660 CanonicalUnsupportedOperation {
661 op_index: usize,
662 operation: &'static str,
663 },
664 #[error("canonical operation {op_index} refused")]
667 CanonicalAdmission {
668 op_index: usize,
669 #[source]
670 source: Box<RuntimeError>,
671 },
672 #[error("{source}")]
674 LintFix {
675 #[source]
676 source: Box<RuntimeError>,
677 detail: Box<crate::graph_lint::LintFixFailureDetail>,
678 },
679
680 #[error("{failure}")]
682 AuditObligation {
683 #[source]
685 failure: Box<AuditObligationFailure>,
686 domain_result: serde_json::Value,
688 },
689
690 #[error("storage: {0}")]
691 Storage(#[from] khive_storage::StorageError),
692
693 #[error("query: {0}")]
694 Query(#[from] khive_query::QueryError),
695
696 #[error("not found: {0}")]
697 NotFound(String),
698
699 #[error("invalid input: {0}")]
700 InvalidInput(String),
701
702 #[error("invalid input: {0}")]
703 UnknownVerb(String),
704
705 #[error("unconfigured: {0} is not set")]
706 Unconfigured(String),
707
708 #[error("unknown embedding model: {0}")]
709 UnknownModel(String),
710
711 #[error("embedding: {0}")]
712 Embedding(#[from] lattice_embed::EmbedError),
713
714 #[error("ambiguous: {0}")]
715 Ambiguous(String),
716
717 #[error("fusion: {0}")]
718 Fusion(#[from] khive_fusion::FuseError),
719
720 #[error("unknown fusion strategy: {0}")]
724 UnknownFusionStrategy(String),
725
726 #[error("internal: {0}")]
727 Internal(String),
728
729 #[error("audit batch incompatible event store: {0}")]
735 IncompatibleEventStore(String),
736
737 #[error("guarded edge write refused: {0}")]
738 GuardedWriteFailed(GuardedWriteFailure),
739
740 #[error("missing pack dependency: {0}")]
741 MissingPackDependency(MissingPackDependency),
742
743 #[error("missing pack dependencies: {0}")]
744 MissingPackDependencies(MissingPackDependencies),
745
746 #[error("{0}")]
747 CircularPackDependency(CircularPackDependency),
748
749 #[error("pack '{name}' registered twice (indices {first_idx} and {second_idx})")]
750 PackRedeclared {
751 name: String,
752 first_idx: usize,
753 second_idx: usize,
754 },
755
756 #[error(
760 "verb collision: verb {verb:?} declared by both pack {first_pack:?} and pack \
761 {second_pack:?}; rename one handler or use Visibility::Subhandler for internal verbs"
762 )]
763 VerbCollision {
764 verb: String,
765 first_pack: String,
766 second_pack: String,
767 },
768
769 #[error(
771 "pack {pack:?} handler {verb:?} declares request-envelope parameter {param:?}; rename the verb argument"
772 )]
773 ReservedEnvelopeParam {
774 pack: String,
775 verb: String,
776 param: String,
777 },
778
779 #[error("{}", .0.message)]
797 RefusedWithReceipt(Box<ReceiptRefusal>),
798
799 #[error(transparent)]
803 RefusedWithEvents { context: RefusalEventContext },
804
805 #[error(transparent)]
807 BatchWrite { context: Box<BatchWriteContext> },
808
809 #[error(transparent)]
812 WithResolution { context: ResolutionFailureContext },
813
814 #[error("permission denied for verb {verb:?}: {reason}")]
824 PermissionDenied {
825 verb: String,
826 reason: String,
827 receipt: Box<DenialReceipt>,
828 },
829
830 #[error("gate unavailable for verb {verb:?}: {reason}")]
836 GateUnavailable { verb: String, reason: String },
837
838 #[error("{0}")]
842 Khive(khive_types::KhiveError),
843
844 #[error("not found in this namespace")]
849 NamespaceMismatch { id: uuid::Uuid },
850
851 #[error("ambiguous prefix {prefix:?}: matches {}", format_uuid_list(matches))]
857 AmbiguousPrefix {
858 prefix: String,
859 matches: Vec<uuid::Uuid>,
860 },
861
862 #[error(
867 "cross-backend merge is not supported: \
868 into_id {into_id} is on backend '{into_backend}', \
869 from_id {from_id} is on backend '{from_backend}'. \
870 Both entities must be on the same backend to merge."
871 )]
872 CrossBackendMergeUnsupported {
873 into_id: uuid::Uuid,
874 from_id: uuid::Uuid,
875 into_backend: String,
876 from_backend: String,
877 },
878
879 #[error("unknown remote: {name:?}")]
882 UnknownRemote { name: String },
883
884 #[error("remote cache missing for remote={remote:?} namespace={namespace:?}")]
886 RemoteCacheMissing { remote: String, namespace: String },
887
888 #[error("ambiguous id {id:?}: matched {count} records")]
890 AmbiguousId { id: String, count: usize },
891
892 #[error("cross-namespace write denied: cannot write to remote namespace {namespace:?}")]
894 CrossNamespaceWrite { namespace: String },
895
896 #[error("remote fetch error for remote={remote:?}: {message}")]
899 RemoteFetchError { remote: String, message: String },
900
901 #[error(
907 "write budget exceeded: max_new_entries={max_new_entries}, \
908 attempted_new_entries={attempted_new_entries}"
909 )]
910 WriteBudgetExceeded {
911 max_new_entries: u64,
912 attempted_new_entries: u64,
913 },
914
915 #[error("write blocked: {0}")]
921 SecretDetected(crate::secret_gate::SecretMatch),
922
923 #[error("{operation} exceeded its {budget_ms}ms deadline (elapsed {elapsed_ms}ms)")]
937 DeadlineExceeded {
938 operation: String,
939 budget_ms: u64,
940 elapsed_ms: u64,
941 },
942}
943
944impl From<khive_db::SqliteError> for RuntimeError {
948 fn from(error: khive_db::SqliteError) -> Self {
949 Self::Storage(match error {
950 khive_db::SqliteError::RequestReadStopped(error) => error,
951 error => error.into_storage_error(khive_storage::StorageCapability::Sql, "runtime"),
952 })
953 }
954}
955
956impl RuntimeError {
957 pub fn before_requested_write(self) -> Self {
959 Self::BatchWrite {
960 context: Box::new(BatchWriteContext {
961 source: Box::new(self),
962 disposition: DomainDisposition::NotCommitted,
963 admission: None,
964 }),
965 }
966 }
967
968 pub fn with_batch_admission(self, admission: BatchAdmissionReport) -> Self {
970 Self::BatchWrite {
971 context: Box::new(BatchWriteContext {
972 source: Box::new(self),
973 disposition: DomainDisposition::NotCommitted,
974 admission: Some(admission),
975 }),
976 }
977 }
978
979 pub fn atomic_write_failure(error: khive_storage::StorageError) -> Self {
981 use khive_storage::{StorageError, WriterTaskRequestState};
982 let disposition = match error.without_sqlite_write_stage() {
983 StorageError::WriterTaskRequestFailed { request_state, .. }
984 | StorageError::WriterTaskTerminated { request_state, .. } => match request_state {
985 WriterTaskRequestState::NotStarted
986 | WriterTaskRequestState::TransactionRolledBack => DomainDisposition::NotCommitted,
987 WriterTaskRequestState::SideEffectsUnknown => DomainDisposition::Unknown,
988 },
989 StorageError::WriterTaskBusy { .. }
990 | StorageError::WriteQueueFull { .. }
991 | StorageError::AdmissionTimeout { .. } => DomainDisposition::NotCommitted,
992 _ => DomainDisposition::Unknown,
993 };
994 Self::BatchWrite {
995 context: Box::new(BatchWriteContext {
996 source: Box::new(Self::Storage(error)),
997 disposition,
998 admission: None,
999 }),
1000 }
1001 }
1002
1003 pub fn batch_write_disposition(&self) -> Option<DomainDisposition> {
1005 match self {
1006 Self::BatchWrite { context } => Some(context.disposition),
1007 Self::RefusedWithEvents { context } => context.source.batch_write_disposition(),
1008 _ => None,
1009 }
1010 }
1011
1012 pub fn with_resolution(self, resolution: ResolutionFacts) -> Self {
1014 Self::WithResolution {
1015 context: ResolutionFailureContext {
1016 source: Box::new(self),
1017 resolution,
1018 },
1019 }
1020 }
1021
1022 pub fn with_refusal_events(self, mut recordings: Vec<RefusalEventRecording>) -> Self {
1025 if recordings.is_empty() {
1026 return self;
1027 }
1028 match self {
1029 Self::RefusedWithEvents { mut context } => {
1030 context.recordings.append(&mut recordings);
1031 Self::RefusedWithEvents { context }
1032 }
1033 source => Self::RefusedWithEvents {
1034 context: RefusalEventContext {
1035 source: Box::new(source),
1036 recordings,
1037 },
1038 },
1039 }
1040 }
1041
1042 pub fn refusal_source(&self) -> &Self {
1045 let mut error = self;
1046 loop {
1047 error = match error {
1048 Self::RefusedWithEvents { context } => &context.source,
1049 Self::BatchWrite { context } => &context.source,
1050 Self::WithResolution { context } => context.source.as_ref(),
1051 Self::LintFix { source, .. } => source.as_ref(),
1052 Self::CanonicalAdmission { source, .. } => source.as_ref(),
1053 _ => return error,
1054 };
1055 }
1056 }
1057
1058 pub fn is_stream_policy_refusal(&self) -> bool {
1065 matches!(self.refusal_source(), Self::Khive(error)
1066 if error.kind() == khive_types::ErrorKind::Conflict
1067 && error.details().and_then(|details| details.get("reason"))
1068 == Some("stream_member"))
1069 }
1070
1071 pub fn permission_denied(verb: impl Into<String>, reason: impl Into<String>) -> Self {
1073 Self::PermissionDenied {
1074 verb: verb.into(),
1075 reason: reason.into(),
1076 receipt: Box::new(DenialReceipt::not_audited()),
1077 }
1078 }
1079
1080 pub fn internal_with_context(context: impl fmt::Display, source: impl fmt::Display) -> Self {
1085 Self::Internal(format!("{context}: {source}"))
1086 }
1087
1088 pub fn channel_ingest_failure_class(&self) -> ChannelIngestFailureClass {
1096 let source = self.refusal_source();
1097 let reason = source.variant_name();
1098 if source.retryable_failure_context().is_some() {
1099 ChannelIngestFailureClass::Retryable { reason }
1100 } else if matches!(source, Self::SecretDetected(_)) {
1101 ChannelIngestFailureClass::Permanent { reason }
1102 } else {
1103 ChannelIngestFailureClass::Unknown { reason }
1104 }
1105 }
1106
1107 fn variant_name(&self) -> &'static str {
1109 match self {
1110 Self::AuditObligation { .. } => "AuditObligation",
1111 Self::Storage(_) => "Storage",
1112 Self::Query(_) => "Query",
1113 Self::NotFound(_) => "NotFound",
1114 Self::InvalidInput(_) => "InvalidInput",
1115 Self::UnknownVerb(_) => "UnknownVerb",
1116 Self::Unconfigured(_) => "Unconfigured",
1117 Self::UnknownModel(_) => "UnknownModel",
1118 Self::Embedding(_) => "Embedding",
1119 Self::Ambiguous(_) => "Ambiguous",
1120 Self::Fusion(_) => "Fusion",
1121 Self::UnknownFusionStrategy(_) => "UnknownFusionStrategy",
1122 Self::Internal(_) => "Internal",
1123 Self::GuardedWriteFailed(_) => "GuardedWriteFailed",
1124 Self::MissingPackDependency(_) => "MissingPackDependency",
1125 Self::MissingPackDependencies(_) => "MissingPackDependencies",
1126 Self::CircularPackDependency(_) => "CircularPackDependency",
1127 Self::PackRedeclared { .. } => "PackRedeclared",
1128 Self::VerbCollision { .. } => "VerbCollision",
1129 Self::ReservedEnvelopeParam { .. } => "ReservedEnvelopeParam",
1130 Self::PermissionDenied { .. } => "PermissionDenied",
1131 Self::GateUnavailable { .. } => "GateUnavailable",
1132 Self::Khive(_) => "Khive",
1133 Self::NamespaceMismatch { .. } => "NamespaceMismatch",
1134 Self::AmbiguousPrefix { .. } => "AmbiguousPrefix",
1135 Self::CrossBackendMergeUnsupported { .. } => "CrossBackendMergeUnsupported",
1136 Self::UnknownRemote { .. } => "UnknownRemote",
1137 Self::RemoteCacheMissing { .. } => "RemoteCacheMissing",
1138 Self::AmbiguousId { .. } => "AmbiguousId",
1139 Self::CrossNamespaceWrite { .. } => "CrossNamespaceWrite",
1140 Self::RemoteFetchError { .. } => "RemoteFetchError",
1141 Self::WriteBudgetExceeded { .. } => "WriteBudgetExceeded",
1142 Self::SecretDetected(_) => "SecretDetected",
1143 Self::DeadlineExceeded { .. } => "DeadlineExceeded",
1144 Self::IncompatibleEventStore(_) => "IncompatibleEventStore",
1145 Self::RefusedWithReceipt { .. } => "RefusedWithReceipt",
1146 Self::RefusedWithEvents { context } => context.source.variant_name(),
1147 Self::BatchWrite { context } => context.source.variant_name(),
1148 Self::WithResolution { context } => context.source.variant_name(),
1149 Self::LintFix { source, .. } => source.variant_name(),
1150 Self::CanonicalAdmission { source, .. } => source.variant_name(),
1151 Self::CanonicalUnsupportedOperation { .. } => "CanonicalUnsupportedOperation",
1152 }
1153 }
1154
1155 pub fn writer_pool_checkout_timeout_context(&self) -> Option<WriterPoolCheckoutTimeoutContext> {
1162 let (sqlite_error, capability, operation) = match self.refusal_source() {
1163 Self::Storage(khive_storage::StorageError::Driver {
1164 capability,
1165 operation,
1166 source,
1167 }) => (
1168 source.downcast_ref::<khive_db::SqliteError>()?,
1169 Some(*capability),
1170 Some(operation.to_string()),
1171 ),
1172 _ => return None,
1173 };
1174
1175 let khive_db::SqliteError::WriterPoolCheckoutTimeout { timeout } = sqlite_error else {
1176 return None;
1177 };
1178 Some(WriterPoolCheckoutTimeoutContext {
1179 timeout: *timeout,
1180 capability,
1181 operation,
1182 })
1183 }
1184
1185 pub fn admission_failure_context(&self) -> Option<AdmissionFailureContext> {
1190 let source = self.refusal_source();
1191 if let Some(context) = self.writer_pool_checkout_timeout_context() {
1192 return Some(AdmissionFailureContext {
1193 stage: WRITER_POOL_CHECKOUT_TIMEOUT_STAGE,
1194 timeout: context.timeout,
1195 capability: context.capability,
1196 operation: context.operation,
1197 pool_identity: None,
1198 scope: None,
1199 retry_after_ms: None,
1200 });
1201 }
1202 if let Self::Storage(khive_storage::StorageError::WriteQueueFull { timeout_ms }) = source {
1203 return Some(AdmissionFailureContext {
1204 stage: WRITER_QUEUE_SATURATED_STAGE,
1205 timeout: Duration::from_millis(*timeout_ms),
1206 capability: None,
1207 operation: None,
1208 pool_identity: None,
1209 scope: Some(WRITER_ADMISSION_SCOPE),
1210 retry_after_ms: Some(*timeout_ms),
1211 });
1212 }
1213 if let Self::Storage(khive_storage::StorageError::AdmissionTimeout {
1214 operation,
1215 timeout_ms,
1216 pool_identity,
1217 }) = source
1218 {
1219 return Some(AdmissionFailureContext {
1220 stage: STORAGE_ADMISSION_TIMEOUT_STAGE,
1221 timeout: Duration::from_millis(*timeout_ms),
1222 capability: None,
1223 operation: Some(operation.to_string()),
1224 pool_identity: pool_identity.clone(),
1225 scope: None,
1226 retry_after_ms: None,
1227 });
1228 }
1229 None
1230 }
1231
1232 pub fn writer_task_failure_context(&self) -> Option<WriterTaskFailureContext> {
1236 let Self::Storage(error) = self.refusal_source() else {
1237 return None;
1238 };
1239 match error.without_sqlite_write_stage() {
1240 khive_storage::StorageError::WriterTaskRequestFailed {
1241 request_state,
1242 source,
1243 } => Some(WriterTaskFailureContext {
1244 stage: WRITER_TASK_REQUEST_FAILED_STAGE,
1245 request_state: *request_state,
1246 task_terminated: false,
1247 retryable: source.is_retryable(),
1248 }),
1249 khive_storage::StorageError::WriterTaskTerminated { request_state, .. } => {
1250 Some(WriterTaskFailureContext {
1251 stage: WRITER_TASK_TERMINATED_STAGE,
1252 request_state: *request_state,
1253 task_terminated: true,
1254 retryable: false,
1255 })
1256 }
1257 _ => None,
1258 }
1259 }
1260
1261 pub fn retryable_failure_context(&self) -> Option<RetryableFailureContext> {
1264 let mut enclosing = self;
1265 loop {
1266 match enclosing {
1267 Self::LintFix { .. } => return None,
1268 Self::RefusedWithEvents { context } => enclosing = &context.source,
1269 Self::BatchWrite { context } => enclosing = &context.source,
1270 Self::WithResolution { context } => enclosing = &context.source,
1271 _ => break,
1272 }
1273 }
1274
1275 let source = self.refusal_source();
1276 if let Some(context) = self.admission_failure_context() {
1277 return Some(context.into());
1278 }
1279 if let Self::Storage(error) = source {
1280 if let khive_storage::StorageError::WriterTaskBusy { timeout_ms } =
1281 error.without_sqlite_write_stage()
1282 {
1283 return Some(RetryableFailureContext {
1284 stage: WRITER_TASK_BEGIN_BUSY_STAGE,
1285 timeout: Duration::from_millis(*timeout_ms),
1286 capability: None,
1287 operation: Some("writer_task_begin".to_string()),
1288 pool_identity: None,
1289 scope: None,
1290 retry_after_ms: None,
1291 });
1292 }
1293 }
1294 if let Self::Storage(khive_storage::StorageError::ReadTransactionAgeEvicted {
1295 operation,
1296 max_age_secs,
1297 }) = source
1298 {
1299 return Some(RetryableFailureContext {
1300 stage: READ_TX_AGE_EVICTED_STAGE,
1301 timeout: Duration::from_secs(*max_age_secs),
1302 capability: Some(khive_storage::StorageCapability::Sql),
1303 operation: Some(operation.to_string()),
1304 pool_identity: None,
1305 scope: None,
1306 retry_after_ms: None,
1307 });
1308 }
1309 if let Self::Storage(
1310 khive_storage::StorageError::ReadTransactionAgeEvictionCleanupFailed {
1311 operation,
1312 max_age_secs,
1313 ..
1314 },
1315 ) = source
1316 {
1317 return Some(RetryableFailureContext {
1318 stage: READ_TX_AGE_EVICTED_STAGE,
1319 timeout: Duration::from_secs(*max_age_secs),
1320 capability: Some(khive_storage::StorageCapability::Sql),
1321 operation: Some(operation.to_string()),
1322 pool_identity: None,
1323 scope: None,
1324 retry_after_ms: None,
1325 });
1326 }
1327 None
1328 }
1329}
1330
1331pub fn fts_text_leg_or_err<T>(
1338 result: Result<Vec<T>, RuntimeError>,
1339 context: &'static str,
1340 query: &str,
1341) -> RuntimeResult<Vec<T>> {
1342 match result {
1343 Ok(hits) => Ok(hits),
1344 Err(RuntimeError::Storage(se)) if se.is_fts5_syntax_error() => {
1345 tracing::warn!(
1346 error = %se,
1347 query = %query,
1348 context,
1349 "FTS text leg failed on a parser syntax error; failing loud (#569)"
1350 );
1351 Err(RuntimeError::InvalidInput(format!(
1352 "{context}: FTS query could not be parsed: {se}"
1353 )))
1354 }
1355 Err(e) => Err(e),
1356 }
1357}
1358
1359fn format_uuid_list(uuids: &[uuid::Uuid]) -> String {
1360 uuids
1361 .iter()
1362 .map(uuid::Uuid::to_string)
1363 .collect::<Vec<_>>()
1364 .join(", ")
1365}
1366
1367impl From<khive_types::EntityTypeError> for RuntimeError {
1371 fn from(e: khive_types::EntityTypeError) -> Self {
1372 Self::InvalidInput(e.to_string())
1373 }
1374}
1375
1376impl From<khive_types::KhiveError> for RuntimeError {
1377 fn from(e: khive_types::KhiveError) -> Self {
1378 Self::Khive(e)
1379 }
1380}
1381
1382#[cfg(test)]
1383#[path = "error_refusal_event_context_tests.rs"]
1384mod refusal_event_context_tests;
1385
1386#[cfg(test)]
1387#[path = "error_stream_policy_refusal_tests.rs"]
1388mod stream_policy_refusal_tests;
1389
1390#[cfg(test)]
1391#[path = "error_channel_ingest_failure_class_tests.rs"]
1392mod channel_ingest_failure_class_tests;
1393
1394#[cfg(test)]
1395mod batch_write_proof_tests {
1396 use super::*;
1397 use crate::runtime_error_value;
1398
1399 fn proof() -> RuntimeError {
1400 RuntimeError::InvalidInput("fixture-prewrite-refusal".into()).before_requested_write()
1401 }
1402
1403 fn project_failed(source: RuntimeError) -> (DomainDisposition, serde_json::Value) {
1404 let error = DispatchError::after_handler(source, false);
1405 let borrowed = error.disposition();
1406 let (source, disposition) = error.into_parts();
1407 assert_eq!(borrowed, disposition);
1408 let value = runtime_error_value(source, disposition);
1409 assert_eq!(value["domain_disposition"], disposition.as_str());
1410 (disposition, value)
1411 }
1412
1413 #[test]
1414 fn batch_proof_reaches_dispatch_owned_parts_and_projection() {
1415 let (disposition, value) = project_failed(proof());
1416 assert_eq!(disposition, DomainDisposition::NotCommitted);
1417 assert!(value["message"]
1418 .as_str()
1419 .unwrap()
1420 .contains("fixture-prewrite-refusal"));
1421 for source in [
1422 RuntimeError::InvalidInput("ordinary".into()),
1423 RuntimeError::Storage(khive_storage::StorageError::Internal(
1424 "ordinary-storage".into(),
1425 )),
1426 ] {
1427 assert_eq!(project_failed(source).0, DomainDisposition::Unknown);
1428 }
1429 }
1430
1431 #[test]
1432 fn enclosing_success_and_unknown_contexts_protect_prior_effects() {
1433 let error = DispatchError::after_handler(proof(), true);
1434 assert_eq!(error.disposition(), DomainDisposition::Committed);
1435 let (source, disposition) = error.into_parts();
1436 assert_eq!(
1437 runtime_error_value(source, disposition)["domain_disposition"],
1438 "committed"
1439 );
1440 assert_eq!(
1441 runtime_error_value(proof(), DomainDisposition::Committed)["domain_disposition"],
1442 "committed"
1443 );
1444 let source = proof().with_resolution(ResolutionFacts {
1445 project_id: Uuid::nil(),
1446 duplicate_anchor_ids: vec![],
1447 slug_backfilled: false,
1448 project_created: true,
1449 orphaned_project_id: None,
1450 orphaned_note_count: 0,
1451 });
1452 assert_eq!(
1453 source.batch_write_disposition(),
1454 None,
1455 "enclosing earlier work blocks an inner no-write proof"
1456 );
1457 let (disposition, value) = project_failed(source);
1458 assert_eq!(disposition, DomainDisposition::Unknown);
1459 assert_eq!(value["details"]["resolution"]["project_created"], true);
1460 }
1461
1462 #[test]
1463 fn batch_evidence_preserves_original_source_and_writer_finality() {
1464 let source = RuntimeError::atomic_write_failure(
1465 khive_storage::StorageError::WriterTaskRequestFailed {
1466 request_state: khive_storage::WriterTaskRequestState::TransactionRolledBack,
1467 source: Box::new(khive_storage::StorageError::Internal(
1468 "fixture-original-cause".into(),
1469 )),
1470 },
1471 )
1472 .with_refusal_events(vec![RefusalEventRecording::Recorded {
1473 item_index: 0,
1474 subject: Uuid::nil(),
1475 event_id: Uuid::nil(),
1476 }]);
1477 assert!(matches!(source.refusal_source(), RuntimeError::Storage(_)));
1478 assert_eq!(
1479 source.writer_task_failure_context().unwrap().request_state,
1480 khive_storage::WriterTaskRequestState::TransactionRolledBack
1481 );
1482 let mut cause: &(dyn std::error::Error + 'static) = &source;
1483 let mut retained = false;
1484 while let Some(next) = cause.source() {
1485 retained |= next.to_string().contains("fixture-original-cause");
1486 cause = next;
1487 }
1488 assert!(retained, "typed cause remains below the outer error");
1489 let (disposition, value) = project_failed(source);
1490 assert_eq!(disposition, DomainDisposition::NotCommitted);
1491 assert_eq!(value["request_state"], "transaction_rolled_back");
1492 assert_eq!(value["refusal_recorded"], true);
1493 let source = RuntimeError::atomic_write_failure(
1494 khive_storage::StorageError::writer_task_terminated(
1495 khive_storage::WriterTaskRequestState::SideEffectsUnknown,
1496 ),
1497 );
1498 assert_eq!(project_failed(source).0, DomainDisposition::Unknown);
1499 }
1500}