stateknot_store_postgres/lib.rs
1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! `PostgreSQL` 16/17 durability provider for `StateKnot`.
5//!
6//! The provider persists canonical journal bytes, serializes each run under a
7//! row lock, checks worker fencing with the database clock, and commits journal
8//! facts with their lifecycle projection, checkpoints, invocation revisions, or
9//! durable node-attempt starts/completions and immutable pending results in one
10//! transaction. An indexed, tenant-scoped readiness projection supplies bounded
11//! stable-snapshot scheduler candidates without reserving them. Transactional
12//! outbox deliveries bind an immutable destination and payload to the exact
13//! origin event; fixed fenced attempts commit before dispatch and recover with
14//! explicit at-least-once semantics. Durable interrupt/timer batches commit
15//! with initial or successor checkpoint barriers; database-clock terminal APIs,
16//! indexed discovery, and explicit cancellation/failure abandonment preserve
17//! complete wait evidence. Structured quarantine observations live outside a
18//! journal that may be corrupt and atomically revoke execution ownership with
19//! exact journal-observation and lost-ack safeguards. A recovery-read combinator
20//! triggers that transaction only for payload-redacted integrity failures.
21//! Fence-bound claimed recovery sessions additionally scope every exposed page
22//! to one run and persist/recheck the detecting attempt and epoch before
23//! quarantine, preventing superseded workers from isolating a successor. Their
24//! bounded ready-node planner deterministically reuses completed results,
25//! classifies fresh/crash/retry/in-flight/terminal work at database time, and
26//! feeds a plan-bound durable node-start handoff before any node code runs.
27//! Deferred-only plans atomically release ownership into an indexed durable
28//! not-before gate while preserving queue age; direct claims cannot bypass the
29//! gate, and due work becomes visible without a per-run polling write. The
30//! atomic Agent-admission boundary binds an authenticated immutable intent and
31//! database clock to an active run, sequence-one event, superstep-zero
32//! checkpoint, registered graph, and scheduler projections in one transaction;
33//! exact retries fully reload and verify the original commit. Tenant-scoped
34//! Agent submission keys store only one-way digests and commit their mapping in
35//! that same transaction, so ambiguous client retries converge on one run even
36//! when candidate IDs change. The provider never holds a database transaction
37//! across node, model, tool, remote-agent, or human work.
38//!
39//! This pre-alpha slice assumes a trusted server-side pool. Do not distribute
40//! its database credentials to untrusted workers. The schema-26 trusted-server
41//! ACL profile in `ops/trusted-role-profile.psql` separates migration, runtime
42//! and reservation-retention accounts; deployment must explicitly apply/audit it.
43//! Connecting a pool validates schema, not that ACL profile. Worker-only procedures and
44//! the final worker/control-plane service boundary remain release blockers.
45
46#![forbid(unsafe_code)]
47
48mod config;
49mod error;
50mod model;
51mod store;
52
53pub use config::{
54 AUTO_MIGRATE_ENV, DATABASE_URL_ENV, DEV_MODE_ENV, MIGRATION_DATABASE_URL_ENV,
55 PostgresConfigurationProfile, PostgresStoreConfig, PostgresStoreConfigBuilder,
56 PostgresStoreOptions, PostgresTransportSecurity,
57};
58pub use error::{ConfigurationError, StoreError};
59pub use model::{
60 AdmissionOutcome, AgentAdmissionCommitOutcome, AgentSubmissionCommitOutcome, AppendOutcome,
61 ArtifactRegistration, ArtifactRegistrationOutcome, ArtifactStorageLocator,
62 BarrierCommitOutcome, CheckpointCommitOutcome, CheckpointLineagePage,
63 CheckpointLineagePageSize, CheckpointPointer, CorruptionQuarantineContext,
64 DelayedRetryScheduleOutcome, DueTimerPage, DueTimerPageCursor, ExpiredInterruptPage,
65 ExpiredInterruptPageCursor, GraphDefinitionRegistrationOutcome, GraphReplayLimits,
66 GraphReplayReport, InterruptResolutionCommitOutcome, JournalPage, JournalPageSize,
67 LeaseClaimOutcome, LeaseReleaseOutcome, LeaseRenewalOutcome, LiveLeaseObservation,
68 ModelInvocationCommitOutcome, ModelInvocationHistoryPage, ModelInvocationHistoryPageSize,
69 NodeAttemptCommitOutcome, NodeAttemptHistoryPage, NodeAttemptHistoryPageSize,
70 OutboxAttemptHistoryPage, OutboxAttemptHistoryPageSize, OutboxClaim, OutboxClaimOutcome,
71 OutboxCompletionOutcome, OutboxDestinationRegistrationOutcome, OutboxEnqueueOutcome,
72 PendingNodeResultCommitOutcome, PendingNodeResultPage, PendingNodeResultPageCursor,
73 PendingNodeResultPageSize, RunProjection, RunQuarantine, RunQuarantineCause,
74 RunQuarantineCommitOutcome, RunQuarantineComponent, RunQuarantineRequest, RunnableRunCandidate,
75 RunnableRunPage, RunnableRunPageCursor, RunnableRunPageSize,
76 SchedulerFairnessPolicyRegistration, SchedulerFairnessPolicyRegistrationOutcome,
77 SchedulerFairnessReservation, SchedulerFairnessRetentionPolicy,
78 SchedulerFairnessRetentionReport, StoredAgentAdmission, StoredAgentSubmission, StoredArtifact,
79 StoredGraphDefinition, StoredOutboxDestination, StoredRun, StoredSchedulerFairnessPolicy,
80 TimerFiringCommitOutcome, ToolInvocationCommitOutcome, ToolInvocationHistoryPage,
81 ToolInvocationHistoryPageSize, WaitAbandonment, WaitAbandonmentCommitOutcome,
82 WaitAbandonmentReason, WaitCheckpointCommitOutcome, WaitDiscoveryPageSize,
83};
84pub use store::{
85 AgentDeadlineCancellationOutcome, AgentDeadlineCursor, ChildCancellationDelivery,
86 ChildCancellationOutcome, ChildCancellationReceipt, ChildCancellationRecord,
87 ChildJoinCommitOutcome, ChildJoinRecord, ChildRunCommitOutcome, ChildRunRecord,
88 ChildRunSettlementOutcome, ClaimedRunRecovery, PostgresStore, RunFailureCloseCursor,
89 RunFailureCloseOutcome, RunFailureCloseRecord, StoredToolAuthorizationReceipt,
90 ToolAuthorizationReceiptOutcome, ToolAuthorizationReceiptPage,
91 ToolAuthorizationReceiptPageSize,
92};