1use thiserror::Error;
5
6#[derive(Clone, Debug, Eq, Error, PartialEq)]
8#[non_exhaustive]
9pub enum ConfigurationError {
10 #[error("required PostgreSQL environment variable {name} is missing")]
12 MissingEnvironmentVariable {
13 name: &'static str,
15 },
16 #[error("PostgreSQL environment variable {name} is invalid")]
18 InvalidEnvironmentVariable {
19 name: &'static str,
21 },
22 #[error("PostgreSQL connection URL must not be empty")]
24 EmptyDatabaseUrl,
25 #[error("production auto-migration requires STATEKNOT_MIGRATION_DATABASE_URL")]
27 MigrationDatabaseUrlRequired,
28 #[error("production migration and runtime PostgreSQL URLs must be distinct")]
30 SharedProductionMigrationCredential,
31 #[error("PostgreSQL connection URL is invalid")]
33 InvalidDatabaseUrl,
34 #[error("PostgreSQL maximum connections must be positive")]
36 ZeroMaximumConnections,
37 #[error("PostgreSQL minimum connections must not exceed maximum connections")]
39 PoolMinimumExceedsMaximum,
40 #[error("{name} must be positive")]
42 ZeroDuration {
43 name: &'static str,
45 },
46 #[error("{name} exceeds the signed microsecond storage range")]
48 DurationTooLarge {
49 name: &'static str,
51 },
52 #[error("lock timeout must be strictly less than statement timeout")]
54 LockTimeoutNotBelowStatementTimeout,
55 #[error("{name} exceeds PostgreSQL's signed millisecond timeout range")]
57 PostgresTimeoutTooLarge {
58 name: &'static str,
60 },
61 #[error("{name} must be a positive whole number of microseconds")]
63 LeaseTimingNotMicrosecondAligned {
64 name: &'static str,
66 },
67 #[error("lease duration must not exceed the maximum lease horizon")]
69 LeaseDurationExceedsMaximumHorizon,
70 #[error("outbox attempt lease must not exceed five minutes")]
72 OutboxAttemptLeaseTooLong,
73}
74
75#[derive(Debug, Error)]
77#[non_exhaustive]
78pub enum StoreError {
79 #[error("invalid failure close boundary or evidence")]
81 InvalidRunFailureClose,
82 #[error("run is sealed for failure closure")]
84 RunFailureClosing,
85 #[error("compatible failure close runtime is required")]
87 UnsupportedFailureCloseRuntime,
88 #[error("Agent deadline request or scan scope is invalid")]
90 InvalidAgentDeadline,
91 #[error("child Join evidence is unavailable or conflicts with this result")]
93 ChildJoinRejected,
94 #[error("child cancellation request was not found")]
96 ChildCancellationNotFound,
97 #[error("compatible child runtime is required")]
99 UnsupportedChildRuntime,
100 #[error("terminal child accounting is incomplete")]
102 IncompleteChildAccounting,
103 #[error("child run commit conflicts with durable ownership")]
105 ChildRunConflict,
106 #[error("child run ownership was not found")]
108 ChildRunNotFound,
109 #[error("child run admission was rejected")]
111 ChildRunRejected,
112 #[error("child run topology limit reached")]
114 ChildRunTopologyExceeded,
115 #[error("unsettled children block this run mutation")]
117 UnsettledChildRuns,
118 #[error("child-adjusted invocation budget observation is required")]
120 ChildBudgetObservationRequired,
121 #[error("child run terminal settlement evidence is unavailable")]
123 ChildRunSettlementUnavailable,
124 #[error(transparent)]
126 Configuration(#[from] ConfigurationError),
127 #[error("PostgreSQL {operation} failed")]
129 Database {
130 operation: &'static str,
132 #[source]
134 source: sqlx_core::Error,
135 },
136 #[error("PostgreSQL schema migration failed")]
138 Migration {
139 #[source]
141 source: sqlx_core::migrate::MigrateError,
142 },
143 #[error("PostgreSQL server major version is unsupported")]
145 UnsupportedServerVersion,
146 #[error("StateKnot PostgreSQL schema has not been migrated")]
148 SchemaNotMigrated,
149 #[error("StateKnot PostgreSQL schema is incompatible with this binary")]
151 IncompatibleSchema,
152 #[error("StateKnot PostgreSQL schema objects are incomplete")]
154 IncompleteSchema,
155 #[error("artifact storage locator is invalid")]
157 InvalidArtifactStorageLocator,
158 #[error("artifact was not found in the tenant registry")]
160 ArtifactNotFound,
161 #[error("artifact registration conflicts with durable registry evidence")]
163 ArtifactRegistrationConflict,
164 #[error("artifact parent was not found in the tenant registry")]
166 ArtifactParentNotFound,
167 #[error("artifact provenance event was not found in the tenant journal")]
169 ArtifactProvenanceNotFound,
170 #[error("compiled graph definition was not found in the tenant registry")]
172 GraphDefinitionNotFound,
173 #[error("compiled graph identity already exists with a different definition")]
175 GraphDefinitionConflict,
176 #[error("scheduler fairness policy registration is invalid")]
178 InvalidSchedulerFairnessPolicy,
179 #[error("scheduler fairness reservation retention policy is invalid")]
181 InvalidSchedulerFairnessRetention,
182 #[error("scheduler fairness shard already exists with a different policy")]
184 SchedulerFairnessPolicyConflict,
185 #[error("scheduler fairness policy was not found")]
187 SchedulerFairnessPolicyNotFound,
188 #[error("scheduler fairness reservation identity conflicts with durable evidence")]
190 SchedulerFairnessReservationConflict,
191 #[error("scheduler fairness reservation sequence is exhausted")]
193 SchedulerFairnessSequenceExhausted,
194 #[error("run was not found in the tenant boundary")]
196 RunNotFound,
197 #[error("run identity already exists with different admission provenance")]
199 RunConflict,
200 #[error("agent admission was not found in the tenant-scoped run")]
202 AgentAdmissionNotFound,
203 #[error("agent admission commit input is invalid")]
205 InvalidAgentAdmissionCommit,
206 #[error("agent admission was rejected at its durable commit observation")]
208 AgentAdmissionRejected,
209 #[error("agent admission state-schema dependency is unavailable")]
211 AgentAdmissionSchemaUnavailable,
212 #[error("agent admission initial state was rejected by its pinned schema")]
214 AgentAdmissionStateRejected,
215 #[error("agent admission identity conflicts with durable evidence")]
217 AgentAdmissionConflict,
218 #[error("agent submission key was not found in the tenant boundary")]
220 AgentSubmissionNotFound,
221 #[error("agent submission key conflicts with durable submission evidence")]
223 AgentSubmissionConflict,
224 #[error("run is quarantined")]
226 RunQuarantined,
227 #[error("run quarantine component code is invalid")]
229 InvalidRunQuarantineComponent,
230 #[error("run quarantine request is invalid")]
232 InvalidRunQuarantineRequest,
233 #[error("run quarantine evidence was not found in the tenant-scoped run")]
235 RunQuarantineNotFound,
236 #[error("run quarantine identity conflicts with durable evidence")]
238 RunQuarantineIdConflict,
239 #[error("run already has different durable quarantine evidence")]
241 RunQuarantineConflict,
242 #[error("run quarantine journal observation is stale")]
244 StaleRunQuarantineObservation,
245 #[error("claimed run recovery context is invalid")]
247 InvalidClaimedRunRecoveryContext,
248 #[error("claimed run recovery journal observation is stale")]
250 StaleClaimedRunRecoveryObservation,
251 #[error("ready-node recovery requires a current graph checkpoint")]
253 ReadyNodeRecoveryCheckpointMissing,
254 #[error("noninitial graph replay dependency is unavailable on this worker")]
256 GraphReplayDependencyUnavailable,
257 #[error("noninitial graph replay exceeds its configured barrier byte limit")]
259 GraphReplayResourceLimit,
260 #[error("ready-node dispatch plan is invalid for the requested durable start")]
262 InvalidReadyNodeDispatchPlan,
263 #[error("ready-node recovery decision is not dispatchable")]
265 ReadyNodeNotDispatchable,
266 #[error("ready-node recovery plan cannot schedule a delayed retry wakeup")]
269 InvalidDelayedRetryPlan,
270 #[error("run quarantine evidence conflicts with its durable projection")]
272 RunQuarantineCommitConflict,
273 #[error("run lifecycle is not runnable")]
275 RunNotRunnable,
276 #[error("run is not yet available for a scheduler claim")]
278 RunNotYetAvailable,
279 #[error("journal append source is not authorized by this entry point")]
281 WrongAppendAuthority,
282 #[error("journal event identity conflicts with a committed intent")]
284 EventIdConflict,
285 #[error("journal event projection conflicts with the committed projection intent")]
287 ProjectionIntentConflict,
288 #[error("journal expectation does not match the current durable head")]
290 StaleJournalHead,
291 #[error("checkpoint was not found in the tenant-scoped run")]
293 CheckpointNotFound,
294 #[error("checkpoint identity conflicts with a committed write intent")]
296 CheckpointIdConflict,
297 #[error("journal event and checkpoint identities conflict with an atomic commit")]
299 CheckpointCommitConflict,
300 #[error("durable wait registration batch is invalid")]
302 InvalidWaitRegistrationBatch,
303 #[error("durable wait registration conflicts with the atomic commit")]
305 WaitRegistrationCommitConflict,
306 #[error("durable wait registration was not found in the tenant-scoped run")]
308 WaitRegistrationNotFound,
309 #[error("durable wait registration kind does not match the requested API")]
311 WaitRegistrationKindMismatch,
312 #[error("interrupt resolution is invalid for the locked durable request")]
314 InvalidInterruptResolution,
315 #[error("interrupt resolution conflicts with the atomic commit")]
317 InterruptResolutionCommitConflict,
318 #[error("timer firing is invalid for the locked durable timer")]
320 InvalidTimerFiring,
321 #[error("timer firing conflicts with the atomic commit")]
323 TimerFiringCommitConflict,
324 #[error("wait discovery page size is invalid")]
326 InvalidWaitDiscoveryPageSize,
327 #[error("due timer page cursor is invalid")]
329 InvalidDueTimerCursor,
330 #[error("expired interrupt page cursor is invalid")]
332 InvalidExpiredInterruptCursor,
333 #[error("wait abandonment transition is invalid")]
335 InvalidWaitAbandonment,
336 #[error("wait abandonment conflicts with the atomic commit")]
338 WaitAbandonmentCommitConflict,
339 #[error("wait abandonment was not found in the tenant-scoped run")]
341 WaitAbandonmentNotFound,
342 #[error("durable wait was abandoned without resolution or firing")]
344 WaitWasAbandoned,
345 #[error("successor checkpoint commit requires a complete checkpoint barrier")]
347 CheckpointBarrierRequired,
348 #[error("checkpoint barrier does not match its durable base checkpoint")]
350 InvalidCheckpointBarrier,
351 #[error("checkpoint barrier is incomplete")]
353 CheckpointBarrierIncomplete,
354 #[error("checkpoint barrier result set conflicts with durable pending results")]
356 CheckpointBarrierResultConflict,
357 #[error("checkpoint barrier identities conflict with an atomic commit")]
359 CheckpointBarrierCommitConflict,
360 #[error("checkpoint parent does not match the current durable checkpoint")]
362 StaleCheckpointHead,
363 #[error("checkpoint advancement is blocked by an unsettled tool invocation")]
365 CheckpointBlockedByToolInvocation,
366 #[error("tool invocation was not found in the tenant-scoped run")]
368 ToolInvocationNotFound,
369 #[error("Tool authorization receipt is invalid for the durable invocation boundary")]
371 InvalidToolAuthorizationReceipt,
372 #[error("Tool authorization receipt was not found in the tenant boundary")]
374 ToolAuthorizationReceiptNotFound,
375 #[error("Tool authorization receipt identity conflicts with durable evidence")]
377 ToolAuthorizationReceiptConflict,
378 #[error("Tool authorization receipt page size is invalid")]
380 InvalidToolAuthorizationReceiptPageSize,
381 #[error("Tool authorization receipt cursor is invalid")]
383 InvalidToolAuthorizationReceiptCursor,
384 #[error("Skill activation evidence is invalid for the durable run boundary")]
386 InvalidSkillActivation,
387 #[error("Skill acting window was not found in the tenant boundary")]
389 SkillActingWindowNotFound,
390 #[error("Skill activation identity conflicts with durable evidence")]
392 SkillActivationConflict,
393 #[error("Skill acting window is inactive")]
395 SkillActingWindowInactive,
396 #[error("tool invocation identity conflicts with a committed intent")]
398 ToolInvocationIdConflict,
399 #[error("journal event and tool invocation identities conflict with an atomic commit")]
401 ToolInvocationCommitConflict,
402 #[error("tool invocation head is stale")]
404 StaleToolInvocationHead,
405 #[error("tool invocation transition is invalid for the locked record")]
407 InvalidToolInvocationTransition,
408 #[error("tool invocation activation is not ready in the base checkpoint")]
410 InvalidToolInvocationActivation,
411 #[error("checkpoint advancement is blocked by an unsettled model invocation")]
413 CheckpointBlockedByModelInvocation,
414 #[error("model invocation was not found in the tenant-scoped run")]
416 ModelInvocationNotFound,
417 #[error("model invocation identity conflicts with a committed intent")]
419 ModelInvocationIdConflict,
420 #[error("journal event and model invocation identities conflict with an atomic commit")]
422 ModelInvocationCommitConflict,
423 #[error("model invocation head is stale")]
425 StaleModelInvocationHead,
426 #[error("model invocation transition is invalid for the locked record")]
428 InvalidModelInvocationTransition,
429 #[error("model invocation activation is not ready in the base checkpoint")]
431 InvalidModelInvocationActivation,
432 #[error("pending node result was not found in the tenant-scoped run")]
434 PendingNodeResultNotFound,
435 #[error("pending node result conflicts with the committed semantic intent")]
437 PendingNodeResultConflict,
438 #[error("journal event and pending node result conflict with an atomic commit")]
440 PendingNodeResultCommitConflict,
441 #[error("pending node result activation is not ready in the base checkpoint")]
443 InvalidPendingNodeResultActivation,
444 #[error("pending node result commit requires a durable node attempt")]
446 NodeAttemptRequired,
447 #[error("pending node result is invalid at its durable commit position")]
449 InvalidPendingNodeResult,
450 #[error("pending node result contains an invalid external invocation binding")]
452 InvalidPendingNodeResultBinding,
453 #[error("pending node result page size is invalid")]
455 InvalidPendingNodeResultPageSize,
456 #[error("pending node result cursor is invalid")]
458 InvalidPendingNodeResultCursor,
459 #[error("node attempt was not found in the tenant-scoped run")]
461 NodeAttemptNotFound,
462 #[error("node attempt identity conflicts with a committed owner")]
464 NodeAttemptIdConflict,
465 #[error("journal event and node attempt conflict with an atomic commit")]
467 NodeAttemptCommitConflict,
468 #[error("node attempt activation is not ready in the base checkpoint")]
470 InvalidNodeAttemptActivation,
471 #[error("node attempt transition is invalid for the locked history")]
473 InvalidNodeAttemptTransition,
474 #[error("node attempt history reached its hard physical-attempt limit")]
476 NodeAttemptLimitExceeded,
477 #[error("node attempt start is stale")]
479 StaleNodeAttemptStart,
480 #[error("node attempt history cursor does not match a durable attempt")]
482 InvalidNodeAttemptCursor,
483 #[error("node attempt history page size is invalid")]
485 InvalidNodeAttemptPageSize,
486 #[error("runnable run page size is invalid")]
488 InvalidRunnableRunPageSize,
489 #[error("runnable run cursor is invalid")]
491 InvalidRunnableRunCursor,
492 #[error("outbox enqueue batch is invalid")]
494 InvalidOutboxBatch,
495 #[error("outbox destination snapshot does not match its canonical configuration")]
497 OutboxDestinationSnapshotMismatch,
498 #[error("outbox destination snapshot was not found in the tenant boundary")]
500 OutboxDestinationNotFound,
501 #[error("outbox destination snapshot conflicts with durable configuration")]
503 OutboxDestinationConflict,
504 #[error("outbox delivery was not found in the tenant-scoped run")]
506 OutboxDeliveryNotFound,
507 #[error("outbox delivery identity conflicts with a committed intent")]
509 OutboxDeliveryIdConflict,
510 #[error("journal event and outbox deliveries conflict with an atomic commit")]
512 OutboxEnqueueConflict,
513 #[error("outbox attempt identity conflicts with a committed owner")]
515 OutboxAttemptIdConflict,
516 #[error("outbox delivery fencing token is stale")]
518 StaleOutboxFence,
519 #[error("outbox attempt lease has expired")]
521 OutboxAttemptExpired,
522 #[error("outbox attempt was not found in the tenant-scoped run")]
524 OutboxAttemptNotFound,
525 #[error("outbox attempt completion conflicts with durable evidence")]
527 OutboxCompletionConflict,
528 #[error("outbox attempt transition is invalid for the locked history")]
530 InvalidOutboxTransition,
531 #[error("outbox attempt history cursor does not match a durable attempt")]
533 InvalidOutboxAttemptCursor,
534 #[error("outbox attempt history page size is invalid")]
536 InvalidOutboxAttemptPageSize,
537 #[error("pending node result page snapshot is stale and must be restarted")]
539 StalePendingNodeResultSnapshot,
540 #[error("journal cursor does not match a durable event")]
542 InvalidJournalCursor,
543 #[error("checkpoint lineage cursor does not match a durable checkpoint")]
545 InvalidCheckpointCursor,
546 #[error("tool invocation history cursor does not match a durable revision")]
548 InvalidToolInvocationCursor,
549 #[error("model invocation history cursor does not match a durable revision")]
551 InvalidModelInvocationCursor,
552 #[error("journal sequence is exhausted")]
554 JournalSequenceExhausted,
555 #[error("lifecycle projection revision is stale")]
557 StaleLifecycleRevision,
558 #[error("lifecycle transition is invalid for the locked run state")]
560 InvalidLifecycleTransition,
561 #[error("durable wait lifecycle changes require the atomic wait persistence API")]
563 DurableWaitMutationRequired,
564 #[error("lifecycle transition observation is later than the journal commit observation")]
566 LifecycleObservationAfterCommit,
567 #[error("run already has an unexpired worker lease")]
569 LeaseHeld,
570 #[error("run has no active worker lease")]
572 NoActiveLease,
573 #[error("worker fencing token is stale")]
575 StaleFence,
576 #[error("worker lease has expired")]
578 LeaseExpired,
579 #[error("database clock precedes a durable lease observation")]
581 DatabaseClockRegression,
582 #[error("worker lease renewal must strictly extend the current expiry")]
584 LeaseExpiryNotExtended,
585 #[error("worker lease renewal exceeds the configured maximum horizon")]
587 LeaseHorizonExceeded,
588 #[error("worker fencing epoch is exhausted")]
590 FencingEpochExhausted,
591 #[error("journal page size is invalid")]
593 InvalidPageSize,
594 #[error("checkpoint lineage page size is invalid")]
596 InvalidCheckpointPageSize,
597 #[error("noninitial graph replay limits are invalid")]
599 InvalidGraphReplayLimits,
600 #[error("tool invocation history page size is invalid")]
602 InvalidToolInvocationPageSize,
603 #[error("model invocation history page size is invalid")]
605 InvalidModelInvocationPageSize,
606 #[error("{record} could not be encoded for durable storage")]
608 Encoding {
609 record: &'static str,
611 },
612 #[error("durable {record} failed integrity validation")]
614 CorruptData {
615 record: &'static str,
617 },
618}
619
620impl StoreError {
621 pub(crate) fn database(operation: &'static str, source: sqlx_core::Error) -> Self {
622 match source
623 .as_database_error()
624 .and_then(sqlx_core::error::DatabaseError::code)
625 .as_deref()
626 {
627 Some("SKC01") => return Self::UnsupportedChildRuntime,
628 Some("SKC02") => return Self::UnsettledChildRuns,
629 Some("SKC03") => return Self::ChildBudgetObservationRequired,
630 Some("SKC04") => return Self::IncompleteChildAccounting,
631 Some("SKC06") => return Self::RunNotRunnable,
632 Some("SKC07") => return Self::ChildJoinRejected,
633 Some("SKC08") => return Self::UnsupportedFailureCloseRuntime,
634 Some("SKC09") => return Self::RunFailureClosing,
635 _ => {}
636 }
637 Self::Database { operation, source }
638 }
639
640 pub(crate) const fn corrupt(record: &'static str) -> Self {
641 Self::CorruptData { record }
642 }
643
644 pub(crate) const fn encoding(record: &'static str) -> Self {
645 Self::Encoding { record }
646 }
647
648 #[must_use]
653 pub const fn corrupt_record(&self) -> Option<&'static str> {
654 match self {
655 Self::CorruptData { record } => Some(record),
656 _ => None,
657 }
658 }
659
660 #[must_use]
663 pub fn is_retryable(&self) -> bool {
664 match self {
665 Self::Database { source, .. } => retryable_database_error(source),
666 _ => false,
667 }
668 }
669}
670
671fn retryable_database_error(error: &sqlx_core::Error) -> bool {
672 match error {
673 sqlx_core::Error::Io(_)
674 | sqlx_core::Error::Tls(_)
675 | sqlx_core::Error::PoolTimedOut
676 | sqlx_core::Error::PoolClosed
677 | sqlx_core::Error::WorkerCrashed => true,
678 sqlx_core::Error::Database(database) => database.code().is_some_and(|code| {
679 matches!(
680 code.as_ref(),
681 "40001" | "40P01" | "55P03" | "57014" | "57P01" | "57P02" | "57P03"
682 )
683 }),
684 _ => false,
685 }
686}