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§
- Agent
Deadline Cursor - Tenant-bound range cursor. It remains usable after the candidate closes.
- Artifact
Registration - Exact immutable input for one idempotent artifact registration.
- Artifact
Storage Locator - Private storage coordinates for one immutable artifact object.
- Checkpoint
Lineage Page - One bounded, fully verified reverse checkpoint-lineage page.
- Checkpoint
Lineage Page Size - Hard-bounded number of checkpoints returned in one lineage page.
- Checkpoint
Pointer - Compact current-checkpoint pointer projected into the locked run row.
- Child
Cancellation Receipt - Immutable delivery evidence; not acknowledgement that external work stopped.
- Child
Cancellation Record - Verified immutable parent cancellation witness and optional child delivery receipt.
- Child
Join Record - Verified registration and optional publication/consumption, without copying child output payloads. Publication is not parent result consumption.
- Child
RunRecord - Fully verified ownership, the original child identities and committed spawn event.
- Claimed
RunRecovery - Fence-bound, corruption-quarantining read surface for one claimed run.
- Corruption
Quarantine Context - Stable context for automatically quarantining one failed recovery read.
- DueTimer
Page - One bounded tenant-level page of fully verified outstanding due timers.
- DueTimer
Page Cursor - Opaque continuation for one fixed-cutoff due-timer scan.
- Expired
Interrupt Page - One bounded tenant-level page of fully verified outstanding expired interrupts.
- Expired
Interrupt Page Cursor - Opaque continuation for one fixed-cutoff expired-interrupt scan.
- Graph
Replay Limits - Memory ceiling for independently replaying one historical graph barrier.
- Graph
Replay Report - Evidence summary returned after complete noninitial checkpoint replay.
- Journal
Page - One bounded, validated page from a run journal.
- Journal
Page Size - Hard-bounded number of events returned by one journal read.
- Live
Lease Observation - Exact lease proven live at one database-clock observation.
- Model
Invocation History Page - One bounded, fully verified ascending model-invocation history page.
- Model
Invocation History Page Size - Hard-bounded number of model invocation revisions in one history page.
- Node
Attempt History Page - One bounded, fully verified ascending physical-attempt history page.
- Node
Attempt History Page Size - Hard-bounded number of physical node attempts in one history page.
- Outbox
Attempt History Page - One bounded, fully verified ascending outbox-attempt history page.
- Outbox
Attempt History Page Size - Hard-bounded number of outbox attempts returned in one history page.
- Outbox
Claim - One atomically claimed delivery and its durable-before-dispatch start.
- Pending
Node Result Page - One bounded, fully verified page of unconsumed pending node results.
- Pending
Node Result Page Cursor - Exact stable-snapshot continuation for unconsumed pending-result scanning.
- Pending
Node Result Page Size - Hard-bounded number of fully decoded pending results in one recovery page.
- Postgres
Store - Connected
PostgreSQLdurability provider. - Postgres
Store Config - Complete, validated store startup configuration.
- Postgres
Store Config Builder - Builder for
PostgresStoreConfig. - Postgres
Store Options - Bounded connection, transaction, and lease settings for
crate::PostgresStore. - RunFailure
Close Cursor - Tenant-bound stable range cursor; not an authorization grant or permanent watermark.
- RunFailure
Close Record - 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.
- RunQuarantine
Component - Bounded non-secret machine code identifying the failed recovery component.
- RunQuarantine
Request - Immutable idempotency intent for quarantining one tenant-scoped run.
- Runnable
RunCandidate - One fully validated run visible to the tenant-level scheduler scan.
- Runnable
RunPage - One stable, bounded tenant-level scheduler candidate page.
- Runnable
RunPage Cursor - Opaque continuation for one fixed runnable-run database snapshot.
- Runnable
RunPage Size - Hard-bounded number of fully decoded runnable runs in one scheduler page.
- Scheduler
Fairness Policy Registration - Immutable canonical policy bytes registered for one scheduler shard.
- Scheduler
Fairness Reservation - One globally ordered, lost-acknowledgement-safe fairness slot reservation.
- Scheduler
Fairness Retention Policy - Bounded maintenance policy for durable fairness reservation evidence.
- Scheduler
Fairness Retention Report - Auditable result of one bounded fairness-reservation retention pass.
- Stored
Agent Admission - Fully verified durable Agent admission and its current run projection.
- Stored
Agent Submission - Fully verified tenant-scoped ingress idempotency mapping and Agent admission.
- Stored
Artifact - Fully verified immutable artifact registry record.
- Stored
Graph Definition - Fully validated immutable graph definition in one tenant registry.
- Stored
Outbox Destination - Fully validated immutable destination snapshot used by dispatch adapters.
- Stored
Run - Validated durable snapshot of one tenant-scoped run row.
- Stored
Scheduler Fairness Policy - Fully verified durable scheduler fairness policy snapshot.
- Stored
Tool Authorization Receipt - One verified immutable receipt and its authoritative database commit time.
- Tool
Authorization Receipt Page - One ascending, verified authorization-receipt audit page.
- Tool
Authorization Receipt Page Size - Bounded number of authorization receipts returned in one audit page.
- Tool
Invocation History Page - One bounded, fully verified ascending invocation-history page.
- Tool
Invocation History Page Size - Hard-bounded number of invocation revisions returned in one history page.
- Wait
Abandonment - One integrity-bound audit fact for a wait abandoned by a run-level edge.
- Wait
Discovery Page Size - Hard-bounded size for tenant-level timer/interrupt discovery pages.
Enums§
- Admission
Outcome - Result of idempotent run admission.
- Agent
Admission Commit Outcome - Result of atomically admitting and initializing one executable Agent run.
- Agent
Deadline Cancellation Outcome - Observation after serializing with all lifecycle, spawn and wait writers.
- Agent
Submission Commit Outcome - Result of an ingress-keyed atomic Agent submission.
- Append
Outcome - Result of an idempotent journal append.
- Artifact
Registration Outcome - Result of idempotently registering one immutable artifact and its locator.
- Barrier
Commit Outcome - Result of atomically consuming one complete result barrier and committing its anchoring event and successor checkpoint.
- Checkpoint
Commit Outcome - Result of atomically committing a journal event and initial graph checkpoint.
- Child
Cancellation Delivery - Atomic delivery result, with original evidence recovered on logical retries.
- Child
Cancellation Outcome - What the child had durably observed when its cancellation work was consumed.
- Child
Join Commit Outcome - Both outcomes return original identities; retry candidates cannot replace evidence.
- Child
RunCommit Outcome - Result of atomic child ownership/admission/account reservation.
- Child
RunSettlement Outcome - Result of replacing one reservation with immutable child terminal usage.
- Configuration
Error - Invalid
PostgreSQLprovider configuration. - Delayed
Retry Schedule Outcome - Result of projecting a recovery plan’s delayed retry into scheduler state.
- Graph
Definition Registration Outcome - Result of idempotently registering one immutable compiled graph version.
- Interrupt
Resolution Commit Outcome - Result of atomically resolving one exact durable interrupt.
- Lease
Claim Outcome - Result of claiming or explicitly superseding execution ownership.
- Lease
Release Outcome - Result of an exact-fence lease release.
- Lease
Renewal Outcome - Result of a lease renewal with stable desired expiry.
- Model
Invocation Commit Outcome - Result of atomically committing a journal event and model invocation revision.
- Node
Attempt Commit Outcome - Result of atomically committing a node-attempt start or completion event.
- Outbox
Claim Outcome - Result of an atomic tenant queue claim with a stable physical attempt ID.
- Outbox
Completion Outcome - Result of idempotently committing one delivery-attempt completion.
- Outbox
Destination Registration Outcome - Result of idempotently registering one immutable destination snapshot.
- Outbox
Enqueue Outcome - Result of atomically appending one journal fact and its exact outbox set.
- Pending
Node Result Commit Outcome - Legacy outcome shape for the pre-v6 direct pending-result API.
- Postgres
Configuration Profile - Security profile selected for a complete store connection configuration.
- Postgres
Transport Security - Database transport policy applied after parsing the connection URL.
- RunFailure
Close Outcome - First decision wins; Existing does not assert equivalence of retry candidates.
- RunProjection
- Lifecycle projection to commit atomically with one journal append.
- RunQuarantine
Cause - Closed reason taxonomy for stopping all execution of one durable run.
- RunQuarantine
Commit Outcome - Result of atomically recording evidence and removing a run from execution.
- Scheduler
Fairness Policy Registration Outcome - Result of registering one immutable scheduler fairness shard.
- Store
Error - Durable
PostgreSQLoperation failure with payload-redacted diagnostics. - Timer
Firing Commit Outcome - Result of atomically firing one exact due durable timer.
- Tool
Authorization Receipt Outcome - Result of an exact immutable authorization-receipt write.
- Tool
Invocation Commit Outcome - Result of atomically committing a journal event and tool invocation revision.
- Wait
Abandonment Commit Outcome - Result of atomically cancelling/failing a waiting run and abandoning its complete outstanding wait set.
- Wait
Abandonment Reason - Durable reason an outstanding wait was abandoned without resolution/firing.
- Wait
Checkpoint Commit Outcome - Result of atomically entering
waitingwith 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.