Skip to main content

Crate stateknot_store_postgres

Crate stateknot_store_postgres 

Source
Expand description

PostgreSQL 16/17 durability provider for StateKnot.

The provider persists canonical journal bytes, serializes each run under a row lock, checks worker fencing with the database clock, and commits journal facts with their lifecycle projection, checkpoints, invocation revisions, or durable node-attempt starts/completions and immutable pending results in one transaction. An indexed, tenant-scoped readiness projection supplies bounded stable-snapshot scheduler candidates without reserving them. Transactional outbox deliveries bind an immutable destination and payload to the exact origin event; fixed fenced attempts commit before dispatch and recover with explicit at-least-once semantics. Durable interrupt/timer batches commit with initial or successor checkpoint barriers; database-clock terminal APIs, indexed discovery, and explicit cancellation/failure abandonment preserve complete wait evidence. Structured quarantine observations live outside a journal that may be corrupt and atomically revoke execution ownership with exact journal-observation and lost-ack safeguards. A recovery-read combinator triggers that transaction only for payload-redacted integrity failures. Fence-bound claimed recovery sessions additionally scope every exposed page to one run and persist/recheck the detecting attempt and epoch before quarantine, preventing superseded workers from isolating a successor. Their bounded ready-node planner deterministically reuses completed results, classifies fresh/crash/retry/in-flight/terminal work at database time, and feeds a plan-bound durable node-start handoff before any node code runs. Deferred-only plans atomically release ownership into an indexed durable not-before gate while preserving queue age; direct claims cannot bypass the gate, and due work becomes visible without a per-run polling write. The atomic Agent-admission boundary binds an authenticated immutable intent and database clock to an active run, sequence-one event, superstep-zero checkpoint, registered graph, and scheduler projections in one transaction; exact retries fully reload and verify the original commit. Tenant-scoped Agent submission keys store only one-way digests and commit their mapping in that same transaction, so ambiguous client retries converge on one run even when candidate IDs change. The provider never holds a database transaction across node, model, tool, remote-agent, or human work.

This pre-alpha slice assumes a trusted server-side pool. Do not distribute its database credentials to untrusted workers. The schema-26 trusted-server ACL profile in ops/trusted-role-profile.psql separates migration, runtime and reservation-retention accounts; deployment must explicitly apply/audit it. Connecting a pool validates schema, not that ACL profile. Worker-only procedures and the final worker/control-plane service boundary remain release blockers.

Structs§

AgentDeadlineCursor
Tenant-bound range cursor. It remains usable after the candidate closes.
ArtifactRegistration
Exact immutable input for one idempotent artifact registration.
ArtifactStorageLocator
Private storage coordinates for one immutable artifact object.
CheckpointLineagePage
One bounded, fully verified reverse checkpoint-lineage page.
CheckpointLineagePageSize
Hard-bounded number of checkpoints returned in one lineage page.
CheckpointPointer
Compact current-checkpoint pointer projected into the locked run row.
ChildCancellationReceipt
Immutable delivery evidence; not acknowledgement that external work stopped.
ChildCancellationRecord
Verified immutable parent cancellation witness and optional child delivery receipt.
ChildJoinRecord
Verified registration and optional publication/consumption, without copying child output payloads. Publication is not parent result consumption.
ChildRunRecord
Fully verified ownership, the original child identities and committed spawn event.
ClaimedRunRecovery
Fence-bound, corruption-quarantining read surface for one claimed run.
CorruptionQuarantineContext
Stable context for automatically quarantining one failed recovery read.
DueTimerPage
One bounded tenant-level page of fully verified outstanding due timers.
DueTimerPageCursor
Opaque continuation for one fixed-cutoff due-timer scan.
ExpiredInterruptPage
One bounded tenant-level page of fully verified outstanding expired interrupts.
ExpiredInterruptPageCursor
Opaque continuation for one fixed-cutoff expired-interrupt scan.
GraphReplayLimits
Memory ceiling for independently replaying one historical graph barrier.
GraphReplayReport
Evidence summary returned after complete noninitial checkpoint replay.
JournalPage
One bounded, validated page from a run journal.
JournalPageSize
Hard-bounded number of events returned by one journal read.
LiveLeaseObservation
Exact lease proven live at one database-clock observation.
ModelInvocationHistoryPage
One bounded, fully verified ascending model-invocation history page.
ModelInvocationHistoryPageSize
Hard-bounded number of model invocation revisions in one history page.
NodeAttemptHistoryPage
One bounded, fully verified ascending physical-attempt history page.
NodeAttemptHistoryPageSize
Hard-bounded number of physical node attempts in one history page.
OutboxAttemptHistoryPage
One bounded, fully verified ascending outbox-attempt history page.
OutboxAttemptHistoryPageSize
Hard-bounded number of outbox attempts returned in one history page.
OutboxClaim
One atomically claimed delivery and its durable-before-dispatch start.
PendingNodeResultPage
One bounded, fully verified page of unconsumed pending node results.
PendingNodeResultPageCursor
Exact stable-snapshot continuation for unconsumed pending-result scanning.
PendingNodeResultPageSize
Hard-bounded number of fully decoded pending results in one recovery page.
PostgresStore
Connected PostgreSQL durability provider.
PostgresStoreConfig
Complete, validated store startup configuration.
PostgresStoreConfigBuilder
Builder for PostgresStoreConfig.
PostgresStoreOptions
Bounded connection, transaction, and lease settings for crate::PostgresStore.
RunFailureCloseCursor
Tenant-bound stable range cursor; not an authorization grant or permanent watermark.
RunFailureCloseRecord
Verified immutable failure decision. Active business state is not runnable while this record is pending; completion retains the same original failure.
RunQuarantine
Fully verified immutable quarantine observation.
RunQuarantineComponent
Bounded non-secret machine code identifying the failed recovery component.
RunQuarantineRequest
Immutable idempotency intent for quarantining one tenant-scoped run.
RunnableRunCandidate
One fully validated run visible to the tenant-level scheduler scan.
RunnableRunPage
One stable, bounded tenant-level scheduler candidate page.
RunnableRunPageCursor
Opaque continuation for one fixed runnable-run database snapshot.
RunnableRunPageSize
Hard-bounded number of fully decoded runnable runs in one scheduler page.
SchedulerFairnessPolicyRegistration
Immutable canonical policy bytes registered for one scheduler shard.
SchedulerFairnessReservation
One globally ordered, lost-acknowledgement-safe fairness slot reservation.
SchedulerFairnessRetentionPolicy
Bounded maintenance policy for durable fairness reservation evidence.
SchedulerFairnessRetentionReport
Auditable result of one bounded fairness-reservation retention pass.
StoredAgentAdmission
Fully verified durable Agent admission and its current run projection.
StoredAgentSubmission
Fully verified tenant-scoped ingress idempotency mapping and Agent admission.
StoredArtifact
Fully verified immutable artifact registry record.
StoredGraphDefinition
Fully validated immutable graph definition in one tenant registry.
StoredOutboxDestination
Fully validated immutable destination snapshot used by dispatch adapters.
StoredRun
Validated durable snapshot of one tenant-scoped run row.
StoredSchedulerFairnessPolicy
Fully verified durable scheduler fairness policy snapshot.
StoredToolAuthorizationReceipt
One verified immutable receipt and its authoritative database commit time.
ToolAuthorizationReceiptPage
One ascending, verified authorization-receipt audit page.
ToolAuthorizationReceiptPageSize
Bounded number of authorization receipts returned in one audit page.
ToolInvocationHistoryPage
One bounded, fully verified ascending invocation-history page.
ToolInvocationHistoryPageSize
Hard-bounded number of invocation revisions returned in one history page.
WaitAbandonment
One integrity-bound audit fact for a wait abandoned by a run-level edge.
WaitDiscoveryPageSize
Hard-bounded size for tenant-level timer/interrupt discovery pages.

Enums§

AdmissionOutcome
Result of idempotent run admission.
AgentAdmissionCommitOutcome
Result of atomically admitting and initializing one executable Agent run.
AgentDeadlineCancellationOutcome
Observation after serializing with all lifecycle, spawn and wait writers.
AgentSubmissionCommitOutcome
Result of an ingress-keyed atomic Agent submission.
AppendOutcome
Result of an idempotent journal append.
ArtifactRegistrationOutcome
Result of idempotently registering one immutable artifact and its locator.
BarrierCommitOutcome
Result of atomically consuming one complete result barrier and committing its anchoring event and successor checkpoint.
CheckpointCommitOutcome
Result of atomically committing a journal event and initial graph checkpoint.
ChildCancellationDelivery
Atomic delivery result, with original evidence recovered on logical retries.
ChildCancellationOutcome
What the child had durably observed when its cancellation work was consumed.
ChildJoinCommitOutcome
Both outcomes return original identities; retry candidates cannot replace evidence.
ChildRunCommitOutcome
Result of atomic child ownership/admission/account reservation.
ChildRunSettlementOutcome
Result of replacing one reservation with immutable child terminal usage.
ConfigurationError
Invalid PostgreSQL provider configuration.
DelayedRetryScheduleOutcome
Result of projecting a recovery plan’s delayed retry into scheduler state.
GraphDefinitionRegistrationOutcome
Result of idempotently registering one immutable compiled graph version.
InterruptResolutionCommitOutcome
Result of atomically resolving one exact durable interrupt.
LeaseClaimOutcome
Result of claiming or explicitly superseding execution ownership.
LeaseReleaseOutcome
Result of an exact-fence lease release.
LeaseRenewalOutcome
Result of a lease renewal with stable desired expiry.
ModelInvocationCommitOutcome
Result of atomically committing a journal event and model invocation revision.
NodeAttemptCommitOutcome
Result of atomically committing a node-attempt start or completion event.
OutboxClaimOutcome
Result of an atomic tenant queue claim with a stable physical attempt ID.
OutboxCompletionOutcome
Result of idempotently committing one delivery-attempt completion.
OutboxDestinationRegistrationOutcome
Result of idempotently registering one immutable destination snapshot.
OutboxEnqueueOutcome
Result of atomically appending one journal fact and its exact outbox set.
PendingNodeResultCommitOutcome
Legacy outcome shape for the pre-v6 direct pending-result API.
PostgresConfigurationProfile
Security profile selected for a complete store connection configuration.
PostgresTransportSecurity
Database transport policy applied after parsing the connection URL.
RunFailureCloseOutcome
First decision wins; Existing does not assert equivalence of retry candidates.
RunProjection
Lifecycle projection to commit atomically with one journal append.
RunQuarantineCause
Closed reason taxonomy for stopping all execution of one durable run.
RunQuarantineCommitOutcome
Result of atomically recording evidence and removing a run from execution.
SchedulerFairnessPolicyRegistrationOutcome
Result of registering one immutable scheduler fairness shard.
StoreError
Durable PostgreSQL operation failure with payload-redacted diagnostics.
TimerFiringCommitOutcome
Result of atomically firing one exact due durable timer.
ToolAuthorizationReceiptOutcome
Result of an exact immutable authorization-receipt write.
ToolInvocationCommitOutcome
Result of atomically committing a journal event and tool invocation revision.
WaitAbandonmentCommitOutcome
Result of atomically cancelling/failing a waiting run and abandoning its complete outstanding wait set.
WaitAbandonmentReason
Durable reason an outstanding wait was abandoned without resolution/firing.
WaitCheckpointCommitOutcome
Result of atomically entering waiting with a checkpoint and complete durable interrupt/timer registration set.

Constants§

AUTO_MIGRATE_ENV
Explicit migration switch read by PostgresStoreConfig::from_env.
DATABASE_URL_ENV
Runtime connection URL read by PostgresStoreConfig::from_env.
DEV_MODE_ENV
Explicit development-profile switch read by PostgresStoreConfig::from_env.
MIGRATION_DATABASE_URL_ENV
Optional deployment-authorized migration URL read by PostgresStoreConfig::from_env.