Skip to main content

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};