Skip to main content

PostgresStore

Struct PostgresStore 

Source
pub struct PostgresStore { /* private fields */ }
Expand description

Connected PostgreSQL durability provider.

Clones share one bounded connection pool. Debug intentionally omits pool internals and connection credentials.

Implementations§

Source§

impl PostgresStore

Source

pub async fn admit_child_run<V: GraphSchemaValidator + ?Sized>( &self, intent: ChildRunAdmissionIntent, node: &NodeAttemptStartHead, parent_append: JournalAppend, child_append: JournalAppend, child_checkpoint: CheckpointWrite, direct_usage: BudgetUsage, schemas: &V, ) -> Result<ChildRunCommitOutcome, StoreError>

Atomically creates one fresh isolated child and reserves its complete budget.

direct_usage is a trusted, complete DIRECT-only parent observation at the exact journal head in parent_append; it must exclude child subtree usage. Schema callbacks run before the mutation transaction. The transaction locks the tree coordinator, then ancestors root-to-parent, and rechecks readiness, a live node start/fence, immutable admission, all ancestor limits and budget. Parent model/tool invocations may not overlap outstanding child work.

Same logical key and spawn digest recover the original child BEFORE fresh lease/deadline/readiness checks. Candidate audit/checkpoint/Run IDs cannot replace it. Existing arbitrary root runs cannot be attached as children. Trusted caller authentication/delegation policy remains a server boundary.

Source

pub async fn load_child_run( &self, key: &ChildRunKey, ) -> Result<ChildRunRecord, StoreError>

Loads fully verified ownership and original child identities within one repeatable-read snapshot. Callers authenticate read access before lookup.

Source

pub async fn load_child_budget_account( &self, tenant: &TenantId, parent: RunId, ) -> Result<Option<ChildRunBudgetAccount>, StoreError>

Returns a verified accounting projection, not a fresh direct-usage report. Invocation providers must add/subtract delegated charges exactly once.

Source

pub async fn include_child_usage( &self, tenant: &TenantId, parent: RunId, direct: BudgetUsage, ) -> Result<BudgetUsage, StoreError>

Adds settled immediate-child subtree charges to complete DIRECT-only usage. Outstanding children fail closed. The eventual journal CAS and terminal mutation revalidate the account; this read alone never authorizes closure.

Source

pub async fn list_child_run_identities( &self, tenant: &TenantId, parent: RunId, ) -> Result<Vec<(Digest, RunId)>, StoreError>

Lists at most 256 retained key/child identity pairs without materializing private input snapshots. The next exact record load verifies all evidence.

Source

pub async fn pending_child_settlements( &self, tenant: &TenantId, ) -> Result<Vec<ChildRunKey>, StoreError>

Discovers at most sixteen durable terminal notifications for reconciliation. Records remain discoverable until a successful settlement transaction; there is no cursor/notification race or destructive dequeue before commit.

Source

pub async fn pending_child_settlements_after( &self, tenant: &TenantId, after: Option<&ChildRunKey>, ) -> Result<Vec<ChildRunKey>, StoreError>

Continues a bounded notification sweep after its last returned key. The immutable terminal anchor retains the cursor after settlement. Skip unpriced/quarantined items and continue so they cannot block later work. Restart from None after each complete sweep: commit order need not equal timestamp order. This is discovery, never a permanent delivery watermark.

Source

pub async fn settle_child_run( &self, key: &ChildRunKey, append: JournalAppend, ) -> Result<ChildRunSettlementOutcome, StoreError>

Settles one child’s complete immutable terminal evidence exactly once.

No external code runs under the transaction. It locks the tree, parent, then child; child terminal commits never lock parents. Control-plane or currently fenced worker audit writes are accepted. Unpriced outcomes stay outstanding and discoverable. This accounting operation is not a Join.

Source§

impl PostgresStore

Source

pub async fn register_child_join( &self, request: ChildRunJoinRequest, node: &NodeAttemptStartHead, append: JournalAppend, ) -> Result<ChildJoinCommitOutcome, StoreError>

Seals ALL children owned by one exact current activation, journals the registration, and releases the parent lease in the SAME transaction.

Requires an unfinished live physical start and exclusive ownership of the Run execution boundary: no other unfinished physical node in the current fence may exist. The original attempt remains executing, not a fabricated failure/completion. Higher-fence recovery may re-enter the logical node. No new child slot can be added after registration. The caller must stop dispatching on the released fence and arrange bounded publication scans. Cancellation bypasses this successful-wait gate, retaining all evidence.

Source

pub async fn publish_child_join( &self, request: &ChildRunJoinRequest, append: JournalAppend, ) -> Result<ChildJoinCommitOutcome, StoreError>

Publishes one immutable complete terminal binding and makes an Active parent claimable. Requires every sealed child’s verified priced settlement. No child outputs are merged, no budgets are charged, and no result is consumed here. Registration before/after completion uses the same durable discovery predicate: there is no destructive notification dequeue.

Source

pub async fn load_child_join( &self, activation: &NodeActivation, ) -> Result<Option<ChildJoinRecord>, StoreError>

Authenticated caller scope is required. Reads a consistent snapshot and verifies canonical identity, physical start, membership, terminal evidence, publication and optional result consumption. Returns no child outputs.

Source

pub async fn pending_child_joins_after( &self, tenant: &TenantId, after: Option<&ChildRunJoinRequest>, ) -> Result<Vec<ChildRunJoinRequest>, StoreError>

At most 16 registered, unquarantined Active parent joins whose children are all settled. Retain the last request as an in-process continuation; after a full sweep or restart begin with None. Continue past item errors. Completed cursor rows are retained; a cursor is not a permanent watermark.

Source§

impl PostgresStore

Source

pub async fn due_agent_deadlines_after( &self, tenant: &TenantId, after: Option<&AgentDeadlineCursor>, ) -> Result<Vec<AgentDeadlineCursor>, StoreError>

Discovers at most 16 due admitted runs, including Waiting and sealed Join runs. Continue past errors using the last candidate, reset to None at sweep end, and restart at None after process loss. This does not acquire a lease. The caller must authenticate and authorize tenant-wide maintenance first.

Source

pub async fn request_agent_deadline_cancellation<V: GraphSchemaValidator + ?Sized>( &self, tenant: &TenantId, run_id: RunId, event_id: EventId, failure_id: FailureId, schema: &SchemaReference, schemas: &V, ) -> Result<AgentDeadlineCancellationOutcome, StoreError>

Requests cancellation only after verifying the immutable admission and observing expiry under the run row lock. No wall-clock input is accepted. The deployment-owned schema must accept the documented deadline audit payload. New candidate IDs on retry converge on the original cancellation reason. A due deadline is not evidence that external work stopped or cost is known. This is a trusted control-plane API, not an untrusted tenant endpoint.

Source§

impl PostgresStore

Source

pub async fn request_run_failure_close( &self, checkpoint: &CheckpointHead, failure: Failure, direct_usage: BudgetUsage, append: JournalAppend, ) -> Result<RunFailureCloseOutcome, StoreError>

Persist a non-cancellation failure for an Active run whose direct work is fully settled. Caller supplies trusted COMPLETE direct usage, never child usage. Unknown direct cost or unfinished physical work rejects the whole transaction without releasing its recovery lease. All immediate unsettled children receive durable cancellation work; no recursive run locks.

Source

pub async fn load_run_failure_close( &self, tenant: &TenantId, run_id: RunId, ) -> Result<Option<RunFailureCloseRecord>, StoreError>

Verified read under a consistent snapshot, including original evidence after completion.

Source

pub async fn pending_run_failure_closes_after( &self, tenant: &TenantId, after: Option<&RunFailureCloseCursor>, ) -> Result<Vec<RunFailureCloseCursor>, StoreError>

At most 16 pending decisions. Preserve cursor through item failures, reset to None at sweep end and after process loss. Quarantine is not hidden.

Source

pub async fn complete_run_failure_close( &self, append: JournalAppend, ) -> Result<RunFailureCloseOutcome, StoreError>

Finalizes only with exact frozen direct plus fully verified settled child usage. Call with a control-plane audit append; no execution lease is acquired.

Source§

impl PostgresStore

Source

pub async fn load_child_cancellation( &self, key: &ChildRunKey, ) -> Result<ChildCancellationRecord, StoreError>

Loads a cancellation witness and verifies its ownership, lifecycle and exact anchors. Authentication and tenant delegation authorization must precede this trusted-store API.

Source

pub async fn pending_child_cancellations_after( &self, tenant: &TenantId, after: Option<&ChildRunKey>, ) -> Result<Vec<ChildRunKey>, StoreError>

Discovers at most 16 pending cancellation keys using an index range. Continue with the last key, even after delivery; restart at None after a full sweep. A full sweep must pass blocked/quarantined items; never retain an event-time watermark.

Source

pub async fn deliver_child_cancellation( &self, key: &ChildRunKey, append: JournalAppend, request: RunCancellationRequest, ) -> Result<ChildCancellationDelivery, StoreError>

Delivers a parent’s durable cancellation to one owned child in one transaction. Locks tree → parent → child. Child request, all existing wait abandonments, descendant work and immutable receipt commit together. No external code runs here. Existing child cancellation/terminal outcomes win without replacement. Logical retries recover the first receipt before checking candidate IDs or stale heads. This trusted control-plane operation never confirms cancellation or invents usage.

Source§

impl PostgresStore

Source

pub async fn record_tool_authorization_receipt( &self, receipt: ToolAuthorizationReceipt, ) -> Result<ToolAuthorizationReceiptOutcome, StoreError>

Durably records an exact Tool authorization before provider I/O.

A fresh write is accepted only while the referenced Tool invocation is at the exact current execution/reconciliation boundary. An exact retry remains idempotent after the invocation advances.

§Errors

Returns an invalid/conflict/not-found error for crossed provenance or reused receipt identity, an integrity failure for corrupted durable bytes, or an availability error when PostgreSQL cannot commit.

Source

pub async fn load_tool_authorization_receipt( &self, tenant_id: &TenantId, receipt_id: AuthorizationReceiptId, ) -> Result<StoredToolAuthorizationReceipt, StoreError>

Loads one exact immutable authorization receipt with full validation.

§Errors

Returns not-found, corruption, or database availability failures.

Source

pub async fn load_tool_authorization_receipt_page( &self, tenant_id: &TenantId, run_id: RunId, invocation_id: InvocationId, after: Option<&StoredToolAuthorizationReceipt>, page_size: ToolAuthorizationReceiptPageSize, ) -> Result<ToolAuthorizationReceiptPage, StoreError>

Lists one bounded verified receipt page for an exact Tool invocation.

§Errors

Returns an invalid cursor when the supplied full record crosses scope or no longer matches immutable storage; otherwise returns integrity or database errors.

Source§

impl PostgresStore

Source

pub async fn open_skill_acting_window( &self, request: SkillActingWindowOpenRequest, ) -> Result<SkillActingWindow, StoreError>

Atomically persists one exact approval and database-clock acting window.

Source

pub async fn load_active_skill_acting_window( &self, tenant: &TenantId, window_id: SkillActingWindowId, ) -> Result<SkillActingWindow, StoreError>

Loads an exact currently active window at database time.

Source

pub async fn assert_skill_acting_window_active( &self, expected: &SkillActingWindow, ) -> Result<(), StoreError>

Revalidates exact durable evidence and active state at database time.

Source

pub async fn revoke_skill_acting_window( &self, expected: &SkillActingWindow, reason: SkillActingWindowRevocationReason, ) -> Result<SkillActingWindowRevocation, StoreError>

Appends the first immutable revocation for an exact window.

Source§

impl PostgresStore

Source

pub const fn options(&self) -> &PostgresStoreOptions

Returns the validated immutable provider options used by this pool.

Source

pub async fn connect( database_url: &str, options: PostgresStoreOptions, ) -> Result<Self, StoreError>

Connects to a qualified PostgreSQL 16 or 17 server and verifies its schema.

Run Self::migrate_database with a deployment-authorized role before connecting an application runtime role. The connection URL is never retained in a public error.

§Errors

Returns StoreError for invalid configuration, connection failure, an unqualified server version, or missing/incompatible migration state.

Source

pub async fn connect_config( config: PostgresStoreConfig, ) -> Result<Self, StoreError>

Connects from a validated complete configuration and optionally runs migrations first through its dedicated migration URL.

Production auto-migration is accepted only when the configuration was built with a distinct migration URL. The explicit development profile may use its single local URL for both operations.

§Errors

Returns StoreError for migration, configuration, connection, server-version, or schema-verification failure.

Source

pub async fn connect_from_env() -> Result<Self, StoreError>

Reads crate::PostgresStoreConfig from the process environment and connects with that exact validated policy.

§Errors

Returns StoreError for environment, migration, connection, or schema failure.

Source

pub async fn connect_development(database_url: &str) -> Result<Self, StoreError>

Migrates and connects to an explicitly local development database.

This convenience disables transport security and reuses the same URL for migrations. It must never be used across an untrusted network or as a production deployment shortcut.

§Errors

Returns StoreError for invalid configuration, migration, connection, server-version, or schema-verification failure.

Source

pub async fn migrate_database( database_url: &str, options: PostgresStoreOptions, ) -> Result<(), StoreError>

Applies embedded, ordered, checksum-pinned migrations using a dedicated pool.

SQLx serializes migration runners with the PostgreSQL migration lock and refuses changed checksums or database versions missing from this binary. The temporary pool is closed before this method returns so DDL credentials do not leak into the runtime connection pool.

§Errors

Returns StoreError if connection, migration, or post-migration schema verification fails.

Source

pub async fn verify_schema(&self) -> Result<(), StoreError>

Verifies exact migration versions/checksums and required schema objects.

Runtime database roles need read access to public._sqlx_migrations in addition to their least-privilege StateKnot table permissions.

§Errors

Returns StoreError::SchemaNotMigrated, StoreError::IncompatibleSchema, StoreError::IncompleteSchema, or a database error.

Source

pub async fn health_check(&self) -> Result<(), StoreError>

Performs a bounded pool acquisition and database round trip.

§Errors

Returns StoreError when the database is unavailable.

Source

pub async fn observe_database_clock(&self) -> Result<Timestamp, StoreError>

Returns one point observation from the authoritative database clock.

The observation is suitable for control-plane intent timestamps that will subsequently be validated against a transactional commit time. It is not a lease, lock, or proof that any durable state remained unchanged after the query completed.

§Errors

Returns StoreError when the database is unavailable or its timestamp cannot be represented by the protocol-neutral clock type.

Source

pub async fn close(&self)

Gracefully closes the shared connection pool.

Source

pub async fn register_artifact( &self, registration: ArtifactRegistration, ) -> Result<ArtifactRegistrationOutcome, StoreError>

Idempotently registers one immutable artifact and its private object locator.

The artifact bytes must already exist at the supplied locator. This transaction performs no object-store I/O: it atomically binds the canonical ArtifactRef, one caller-generated idempotency digest, the locator, the causing journal event, and every same-tenant direct parent. Exact retries recover the original database-clock observation.

§Errors

Returns StoreError::ArtifactParentNotFound when any direct parent is absent, StoreError::ArtifactRegistrationConflict when an identity, idempotency key, or locator already owns different immutable evidence, or an encoding, corruption, or database error.

Source

pub async fn load_artifact( &self, identity: &ArtifactIdentity, ) -> Result<StoredArtifact, StoreError>

Loads and fully verifies one tenant-qualified immutable artifact record.

This trusted storage API returns private object coordinates. Callers that serve artifact bytes must authorize the principal before invoking it and must still verify the stored length and digest while streaming.

§Errors

Returns StoreError::ArtifactNotFound when the exact tenant-qualified identity is absent, or a corruption/database error.

Source

pub async fn register_graph_definition( &self, tenant_id: TenantId, graph: CompiledGraph, ) -> Result<GraphDefinitionRegistrationOutcome, StoreError>

Idempotently registers one immutable compiled graph version.

The tenant boundary is independent from the graph’s authenticated owner identity. Once an owner/name/version tuple commits in that tenant, every schema, reducer, node, route, limit, and digest is immutable; publish a new semantic version for any change.

§Errors

Returns StoreError::GraphDefinitionConflict when the graph identity already owns different canonical bytes, or an encoding, corruption, or database error.

Source

pub async fn load_graph_definition( &self, tenant_id: &TenantId, reference: &GraphReference, ) -> Result<StoredGraphDefinition, StoreError>

Loads one exact graph reference from a tenant registry.

Canonical bytes are deserialized through the compiler again and checked against every redundant key column before the definition is returned.

§Errors

Returns StoreError::GraphDefinitionNotFound when no exact identity, digest, and state-schema binding exists, or a corruption/database error.

Source

pub async fn register_scheduler_fairness_policy( &self, registration: SchedulerFairnessPolicyRegistration, ) -> Result<SchedulerFairnessPolicyRegistrationOutcome, StoreError>

Idempotently registers one immutable distributed fairness schedule.

A shard identity permanently binds canonical policy bytes, checksum, and cycle length. Deployments publish another shard identity to change weights, preventing replicas with mixed configuration from sharing a cursor accidentally.

§Errors

Returns StoreError::SchedulerFairnessPolicyConflict when the shard already owns different bytes, or a corruption/database failure.

Source

pub async fn load_scheduler_fairness_policy( &self, shard_id: &SchedulerShardId, ) -> Result<StoredSchedulerFairnessPolicy, StoreError>

Loads and verifies one immutable distributed fairness policy.

§Errors

Returns StoreError::SchedulerFairnessPolicyNotFound, a corruption failure, or a database error.

Source

pub async fn reserve_scheduler_fairness_slot( &self, shard_id: &SchedulerShardId, policy_digest: Digest, reservation_id: SchedulerReservationId, ) -> Result<SchedulerFairnessReservation, StoreError>

Atomically reserves the next shard-global weighted schedule slot.

reservation_id must be allocated once before the database call and retained across every retry. An ambiguous successful commit is recovered from the immutable reservation row without advancing the cursor again. The transaction never spans queue scanning, lease claiming, or run work.

§Errors

Returns explicit policy-not-found, policy/reservation conflict, sequence exhaustion, corruption, or database failures.

Source

pub async fn prune_scheduler_fairness_reservations( &self, policy: SchedulerFairnessRetentionPolicy, ) -> Result<SchedulerFairnessRetentionReport, StoreError>

Deletes one bounded batch of expired fairness reservation evidence.

The cutoff is derived from the authoritative database clock. Candidates are ordered by the retention index and locked with SKIP LOCKED, so multiple maintenance workers can cooperate without blocking scheduler reservations or each other. Shard policies and cursor positions are never modified.

A reservation handoff older than the configured retention window must be treated as expired by its owner and must not be retried after this method can delete it.

§Errors

Returns a database or integrity failure. Policy construction already enforces the one-hour safety floor and bounded transaction size.

Source

pub async fn admit_run( &self, provenance: AgentResultProvenance, ) -> Result<AdmissionOutcome, StoreError>

Idempotently creates a low-level, uninitialized pending run using a database commit timestamp.

A retry with the same tenant/run identity succeeds only when the durable admission provenance is identical. If the run has progressed, its current validated lifecycle is returned. Uninitialized rows are deliberately absent from scheduler discovery; only an explicit trusted low-level ID path can address them. New Agent APIs should use Self::admit_agent_run so admission and initialization cannot be observed separately.

§Errors

Returns StoreError for identity conflict, corruption, or database failure.

Source

pub async fn admit_agent_run<V>( &self, intent: AgentAdmissionIntent, append: JournalAppend, checkpoint_write: CheckpointWrite, schemas: &V, ) -> Result<AgentAdmissionCommitOutcome, StoreError>

Atomically admits and initializes one executable Agent run.

The immutable admission snapshot, pending-to-active lifecycle edge, sequence-one control-plane event, superstep-zero checkpoint, registered graph reference, and scheduler-visible run heads commit in one database transaction. The schema validator is invoked only outside the mutation transaction and must resolve a pre-registered digest-pinned local schema.

An exact retry first recovers durable evidence and therefore succeeds even when its original deadline has passed after an ambiguous commit. The stable tenant/run key is serialized across scheduler replicas with a transaction-scoped advisory lock; hash collisions can delay unrelated admissions but cannot weaken correctness.

Request and authorization-evidence schemas are trusted control-plane preconditions captured by AgentAdmissionIntent. This provider independently validates the registered graph, exact entry ready-set and initial state schema before committing.

§Errors

Rejects crossed scope, non-empty journals, worker authority, unregistered graphs, invalid initial state/ready sets, database-time budget expiry, identity conflicts, corruption, or database failures.

Source

pub async fn submit_agent_run<V>( &self, key: &AgentSubmissionKey, intent: AgentAdmissionIntent, append: JournalAppend, checkpoint_write: CheckpointWrite, schemas: &V, ) -> Result<AgentSubmissionCommitOutcome, StoreError>

Resolves one tenant-scoped ingress key to exactly one atomic Agent run.

The raw key is hashed with its tenant boundary before storage. A domain-separated submission digest binds every caller-controlled Agent, request, budget, graph, authority, initial-state, and initial-ready-set field while deliberately excluding the framework-generated provenance, admission-audit event, and checkpoint identities. Consequently, a retry after an ambiguous response may generate a fresh candidate identity bundle and still recover the original run. Reusing the key for different logical content fails closed.

New mappings serialize under a transaction-scoped advisory lock and are inserted in the same transaction as a new Agent admission. No mapping can reference a missing or different admission because migration 16 enforces a composite foreign key.

§Errors

Returns StoreError::AgentSubmissionConflict for key reuse with different content, plus the same admission, schema, integrity, and database errors as Self::admit_agent_run.

Source

pub async fn load_agent_submission( &self, tenant_id: &TenantId, key: &AgentSubmissionKey, ) -> Result<StoredAgentSubmission, StoreError>

Loads one durable ingress-key mapping and its current Agent run.

The raw key is used only to derive its tenant-scoped digest. Mapping, admission, initial event/checkpoint, graph definition, current lifecycle, and redundant digests are verified inside one repeatable-read snapshot.

§Errors

Returns StoreError::AgentSubmissionNotFound, a payload-redacted integrity failure, or a database error.

Source

pub async fn load_agent_admission( &self, tenant_id: &TenantId, run_id: RunId, ) -> Result<StoredAgentAdmission, StoreError>

Loads and fully revalidates one immutable Agent admission snapshot.

The returned value includes the current run plus its immutable initial event/checkpoint anchors. Canonical bytes, redundant columns, graph registry bytes, projection digest, foreign-key identities, and current wait-set projection are all checked inside one repeatable-read snapshot.

§Errors

Returns StoreError::AgentAdmissionNotFound, an integrity failure, or a database error.

Source

pub async fn load_run( &self, tenant_id: &TenantId, run_id: RunId, ) -> Result<StoredRun, StoreError>

Loads and validates one tenant-scoped run snapshot.

§Errors

Returns StoreError::RunNotFound, a corruption failure, or a database error.

Source

pub async fn quarantine_run( &self, request: RunQuarantineRequest, ) -> Result<RunQuarantineCommitOutcome, StoreError>

Atomically records integrity-safe evidence and removes a run from execution.

Quarantine facts are stored outside the run journal because that journal may be the object that failed verification. The exact journal expectation prevents a stale observation from quarantining a run after durable progress. A request carrying an expected fence additionally requires that exact attempt and epoch to own an unexpired lease in this transaction, so a stale recovery worker cannot quarantine its successor. A committed quarantine clears the active lease and is excluded from the runnable index in the same transaction. Losing the commit acknowledgement is recovered by retrying the identical quarantine_id and request.

§Errors

Returns explicit not-found, stale-observation, identity/conflict, corruption, or database failures. A run quarantined before migration 10 is preserved but cannot acquire fabricated audit evidence through this API.

Source

pub async fn with_corruption_quarantine<T, F>( &self, context: CorruptionQuarantineContext, recovery_read: F, ) -> Result<T, StoreError>
where F: Future<Output = Result<T, StoreError>>,

Runs one read-only recovery validation and quarantines only corruption.

The supplied future must not perform external side effects. It completes before a separate quarantine transaction begins. Successful values and non-corruption failures are returned unchanged. For StoreError::CorruptData, the provider derives the bounded component code, commits (or exactly recovers) the quarantine, then returns StoreError::RunQuarantined. A stale journal/fence observation, expired lease, or unavailable database is returned instead of claiming that isolation committed.

This helper does not grant execution authority: recovery still needs a live run fence and must re-check the quarantined run projection before dispatch.

§Errors

Returns the recovery read error, or an explicit quarantine transaction failure. Raw corrupt payloads are never copied into the quarantine row.

Source

pub async fn begin_claimed_run_recovery( &self, fence: RunFence, context: CorruptionQuarantineContext, ) -> Result<ClaimedRunRecovery<'_>, StoreError>

Starts one fence-bound recovery session for a claimed runnable run.

The supplied fence and quarantine context must name the same tenant/run. In one repeatable-read transaction the provider verifies the complete run projection and wait set, exact live lease against the database clock, runnable/quarantine state, and the context’s exact journal observation. The returned session then supplies only scope-bound recovery reads that automatically use the same stable corruption quarantine intent.

Creating a session does not authorize external dispatch. Recovered work must still enter the corresponding durable-before-dispatch start API under the exact fence.

§Errors

Returns StoreError::InvalidClaimedRunRecoveryContext for crossed scope, StoreError::StaleClaimedRunRecoveryObservation for journal progress, or explicit lifecycle, fencing, corruption/quarantine, and database failures. Corruption is quarantined before this method returns.

Source

pub async fn load_run_quarantine( &self, tenant_id: &TenantId, run_id: RunId, ) -> Result<RunQuarantine, StoreError>

Loads and fully verifies the immutable quarantine observation for a run.

Migration-created legacy quarantines deliberately have no synthetic row here and return StoreError::RunQuarantineNotFound.

§Errors

Returns StoreError::RunNotFound, StoreError::RunQuarantineNotFound, a corruption failure, or a database error.

Source

pub async fn load_interrupt_request( &self, tenant_id: &TenantId, run_id: RunId, interrupt_id: InterruptId, ) -> Result<InterruptRequest, StoreError>

Loads and verifies the immutable request half of one durable interrupt.

The request remains available after resolution or explicit abandonment; terminal history is exposed by the corresponding terminal APIs.

§Errors

Returns an exact not-found/kind mismatch, corruption, or database error.

Source

pub async fn load_durable_timer( &self, tenant_id: &TenantId, run_id: RunId, timer_id: TimerId, ) -> Result<DurableTimer, StoreError>

Loads and verifies one immutable durable timer registration.

§Errors

Returns an exact not-found/kind mismatch, corruption, or database error.

Source

pub async fn load_interrupt_record( &self, tenant_id: &TenantId, run_id: RunId, interrupt_id: InterruptId, ) -> Result<InterruptRecord, StoreError>

Loads and validates the complete request/resolution history of one interrupt.

§Errors

Returns not-found, kind/conflict, corruption, or database failures.

Source

pub async fn load_durable_timer_record( &self, tenant_id: &TenantId, run_id: RunId, timer_id: TimerId, ) -> Result<DurableTimerRecord, StoreError>

Loads and validates the complete registration/firing history of one timer.

§Errors

Returns not-found, kind/conflict, corruption, or database failures.

Source

pub async fn load_interrupt_abandonment( &self, tenant_id: &TenantId, run_id: RunId, interrupt_id: InterruptId, ) -> Result<WaitAbandonment, StoreError>

Loads and validates the immutable audit fact for one abandoned interrupt.

§Errors

Returns exact registration/abandonment not-found, kind mismatch, corruption, or database failures.

Source

pub async fn load_timer_abandonment( &self, tenant_id: &TenantId, run_id: RunId, timer_id: TimerId, ) -> Result<WaitAbandonment, StoreError>

Loads and validates the immutable audit fact for one abandoned timer.

§Errors

Returns exact registration/abandonment not-found, kind mismatch, corruption, or database failures.

Source

pub async fn load_due_timer_page( &self, tenant_id: &TenantId, cursor: Option<&DueTimerPageCursor>, page_size: WaitDiscoveryPageSize, ) -> Result<DueTimerPage, StoreError>

Loads one fixed-database-cutoff page of outstanding timers whose due instant has been reached.

New registrations cannot enter an existing cutoff because a timer’s due instant is strictly after its registration observation. Concurrent firings may remove rows, while the exact keyset cursor prevents repeats.

§Errors

Returns cursor, clock, corruption, or database failures.

Source

pub async fn load_expired_interrupt_page( &self, tenant_id: &TenantId, cursor: Option<&ExpiredInterruptPageCursor>, page_size: WaitDiscoveryPageSize, ) -> Result<ExpiredInterruptPage, StoreError>

Loads one fixed-database-cutoff page of unresolved interrupts at or past their exclusive expiry.

§Errors

Returns cursor, clock, corruption, or database failures.

Source

pub async fn load_runnable_run_page( &self, tenant_id: &TenantId, cursor: Option<&RunnableRunPageCursor>, page_size: RunnableRunPageSize, ) -> Result<RunnableRunPage, StoreError>

Loads one tenant-scoped, stable-snapshot page of runnable candidates.

The first page fixes a database transaction timestamp. Continuations retain that cutoff even when leases expire or new work arrives, so one bounded scan never chases a moving queue. Records are ordered by their effective availability and run identity. This method does not reserve a record: a scheduler must call Self::claim_lease for the selected run and handle StoreError::LeaseHeld as normal contention.

Scheduling fairness across tenants is deliberately outside the storage contract; callers choose a tenant before scanning its durable queue.

§Errors

Returns StoreError::InvalidRunnableRunCursor when a continuation crosses tenant scope or has an impossible key, and otherwise returns a clock-regression, corruption, or database failure.

Source

pub async fn register_outbox_destination( &self, destination: OutboxDestinationRef, config: JournalPayload, ) -> Result<OutboxDestinationRegistrationOutcome, StoreError>

Idempotently registers one immutable, tenant-owned destination snapshot.

config is a canonical schema-pinned routing envelope. Its digest must equal destination.snapshot_digest(). Raw credentials are outside this contract; configurations may name only external credential handles.

§Errors

Returns StoreError for digest mismatch, conflicting durable bytes, resource bounds, corruption, or database failure.

Source

pub async fn load_outbox_destination( &self, destination: &OutboxDestinationRef, ) -> Result<StoredOutboxDestination, StoreError>

Loads and validates one immutable destination snapshot.

§Errors

Returns StoreError::OutboxDestinationNotFound when absent, or a corruption/database error.

Source

pub async fn load_outbox_delivery( &self, tenant_id: &TenantId, run_id: RunId, delivery_id: DeliveryId, ) -> Result<OutboxDelivery, StoreError>

Loads and fully validates one immutable outbox delivery.

§Errors

Returns StoreError::OutboxDeliveryNotFound when absent, or a corruption/database error.

Source

pub async fn append_control_plane_with_outbox( &self, append: JournalAppend, projection: RunProjection, deliveries: Vec<OutboxDeliveryIntent>, ) -> Result<OutboxEnqueueOutcome, StoreError>

Atomically appends a control-plane event and a non-empty delivery set.

§Errors

Returns StoreError for invalid batch/scope, idempotency conflict, stale run state, missing destinations, corruption, or database failure.

Source

pub async fn append_worker_with_outbox( &self, append: JournalAppend, projection: RunProjection, deliveries: Vec<OutboxDeliveryIntent>, ) -> Result<OutboxEnqueueOutcome, StoreError>

Atomically appends a worker event and a non-empty delivery set under the exact current run fence.

§Errors

Returns StoreError for invalid batch/scope, stale/expired fencing, idempotency conflict, missing destinations, corruption, or database failure.

Source

pub async fn load_checkpoint( &self, tenant_id: &TenantId, run_id: RunId, checkpoint_id: CheckpointId, ) -> Result<Checkpoint, StoreError>

Loads and verifies one immutable tenant/run-scoped checkpoint by ID.

This does not require the checkpoint to remain the run’s current head; it is suitable for audit and exact lost-acknowledgement recovery.

§Errors

Returns StoreError::CheckpointNotFound, a corruption failure, or a database error.

Source

pub async fn load_current_checkpoint( &self, tenant_id: &TenantId, run_id: RunId, ) -> Result<Option<Checkpoint>, StoreError>

Loads the run’s exact current checkpoint in one repeatable-read snapshot.

None means the admitted run has not yet committed its first graph barrier. The compact pointer and full checkpoint must agree exactly.

§Errors

Returns a corruption failure if the pointer is dangling or mismatched, otherwise a database error.

Source

pub async fn load_checkpoint_lineage_page( &self, tenant_id: &TenantId, run_id: RunId, from: Option<&CheckpointHead>, page_size: CheckpointLineagePageSize, ) -> Result<CheckpointLineagePage, StoreError>

Loads one bounded checkpoint lineage page in newest-to-oldest order.

With no from cursor, the page starts at the current checkpoint observed together with the run row in one repeatable-read snapshot. A continuation must use the exact CheckpointLineagePage::next_cursor returned by the preceding verified page. Checkpoints are immutable, so later barrier commits cannot change the ancestry behind that cursor.

Every returned checkpoint is decoded from canonical bytes, matched to its redundant columns, linked to the preceding child, and bound to the exact fully decoded journal event at its anchor.

§Errors

Returns StoreError::InvalidCheckpointCursor for a crossed, future, or non-exact cursor; otherwise returns explicit run, corruption, or database failures.

Source

pub async fn load_tool_invocation( &self, tenant_id: &TenantId, run_id: RunId, invocation_id: InvocationId, ) -> Result<ToolInvocation, StoreError>

Loads the exact current revision of one logical tool invocation.

The intent, redundant current pointer, canonical record bytes, base checkpoint, and anchoring journal event are verified in one repeatable- read snapshot. Use Self::load_tool_invocation_history_page when a complete transition-chain audit is required.

§Errors

Returns StoreError::ToolInvocationNotFound, a corruption failure, or a database error.

Source

pub async fn load_tool_invocation_revision( &self, tenant_id: &TenantId, run_id: RunId, invocation_id: InvocationId, revision: ToolInvocationRevision, ) -> Result<(JournalEvent, ToolInvocation), StoreError>

Loads one exact immutable Tool revision and its verified journal event.

This indexed lookup does not scan history. It checks the intent/base checkpoint, local checksums, direct predecessor transition, projection anchor and (when selected) current pointer in one repeatable-read snapshot. It does not replace full-history verification or authorize a caller.

§Errors

Returns not-found, corruption or database errors without mutating state.

Source

pub async fn load_tool_invocation_history_page( &self, tenant_id: &TenantId, run_id: RunId, invocation_id: InvocationId, after: Option<&ToolInvocation>, page_size: ToolInvocationHistoryPageSize, ) -> Result<ToolInvocationHistoryPage, StoreError>

Loads one bounded ascending page of immutable invocation revisions.

The first page starts at revision zero. A continuation must pass the full exact last record returned by ToolInvocationHistoryPage::next_cursor, because retry validation needs the predecessor’s failure evidence rather than only a compact head. The final page must converge to the current invocation pointer observed in the same repeatable-read snapshot.

§Errors

Returns StoreError::InvalidToolInvocationCursor for a crossed or non-exact cursor; otherwise returns explicit not-found, corruption, or database failures.

Source

pub async fn load_model_invocation( &self, tenant_id: &TenantId, run_id: RunId, invocation_id: InvocationId, ) -> Result<ModelInvocation, StoreError>

Loads the exact current revision of one logical model invocation.

The immutable intent, compact revision wire, redundant current pointer, base checkpoint, and journal anchor are verified in one repeatable-read snapshot. Use Self::load_model_invocation_history_page to prove a complete retry chain.

§Errors

Returns StoreError::ModelInvocationNotFound, a corruption failure, or a database error.

Source

pub async fn load_model_invocation_history_page( &self, tenant_id: &TenantId, run_id: RunId, invocation_id: InvocationId, after: Option<&ModelInvocation>, page_size: ModelInvocationHistoryPageSize, ) -> Result<ModelInvocationHistoryPage, StoreError>

Loads one bounded ascending page of immutable model revisions.

A continuation cursor is the full prior record because a failed record’s error and durable timestamp are required to validate a delayed retry. The page size is one to bound decoding of maximum-size model payloads.

§Errors

Returns StoreError::InvalidModelInvocationCursor for a crossed or non-exact cursor; otherwise returns not-found, corruption, or database failures.

Source

pub async fn load_node_attempt( &self, tenant_id: &TenantId, run_id: &RunId, attempt_id: AttemptId, ) -> Result<NodeAttempt, StoreError>

Loads and fully verifies one physical node attempt.

Canonical start/completion bytes, every redundant projection, the base checkpoint, both worker journal anchors, and a successful pending-result binding are checked in one repeatable-read snapshot.

§Errors

Returns StoreError::NodeAttemptNotFound when the identity is absent from the tenant/run boundary; otherwise returns an integrity or database failure.

Source

pub async fn load_node_attempt_history_page( &self, activation: &NodeActivation, cursor: Option<&NodeAttempt>, page_size: NodeAttemptHistoryPageSize, ) -> Result<NodeAttemptHistoryPage, StoreError>

Loads one bounded, fully verified page of an activation’s physical history.

Pass the exact full attempt returned by NodeAttemptHistoryPage::next_cursor to continue. The provider reloads and verifies that cursor before using its immutable start position, so a constructed or cross-activation cursor fails closed.

§Errors

Returns an invalid cursor, durable integrity, or database failure.

Source

pub async fn load_pending_node_result( &self, activation: &NodeActivation, ) -> Result<PendingNodeResult, StoreError>

Loads and fully verifies one immutable pending node result.

The result’s canonical bytes, redundant projections, base checkpoint, worker journal anchor, binding rows, full invocation intents, exact committed revisions, and invocation journal anchors are checked in one repeatable-read snapshot.

§Errors

Returns StoreError::PendingNodeResultNotFound when the exact activation is absent; otherwise returns an integrity or database error.

Source

pub async fn load_unconsumed_pending_node_result_page( &self, base: &CheckpointHead, cursor: Option<&PendingNodeResultPageCursor>, page_size: PendingNodeResultPageSize, ) -> Result<PendingNodeResultPage, StoreError>

Loads one stable-snapshot page of fully verified unconsumed node results.

The first call passes no cursor. A continuation must use the exact PendingNodeResultPage::next_cursor from the preceding page. The cursor pins the run journal head, so any concurrent result commit makes continuation return StoreError::StalePendingNodeResultSnapshot instead of allowing keyset pagination to miss a lower activation key. Only the compact look-ahead row exceeds page_size; full result and invocation records are decoded within their independent hard bounds.

§Errors

Returns an invalid/stale cursor error, stale checkpoint error, durable corruption, or database failure. The supplied base must still be the exact current checkpoint of the run.

Source

pub async fn load_outbox_attempt_history_page( &self, tenant_id: &TenantId, run_id: RunId, delivery_id: DeliveryId, after: Option<&OutboxAttempt>, page_size: OutboxAttemptHistoryPageSize, ) -> Result<OutboxAttemptHistoryPage, StoreError>

Loads one bounded, fully verified outbox-attempt history page.

The provider replays the complete bounded history on every page so a cursor cannot hide an invalid predecessor. At most 64 small attempt records exist for one delivery.

§Errors

Returns StoreError::InvalidOutboxAttemptCursor for a crossed or non-exact cursor, and otherwise explicit not-found, corruption, or database failures.

Source

pub async fn claim_outbox_delivery( &self, tenant_id: &TenantId, attempt_id: AttemptId, ) -> Result<OutboxClaimOutcome, StoreError>

Atomically claims the earliest eligible unlocked delivery for one tenant.

A fresh start and run-wide attempt claim commit before the caller may perform network I/O. Retrying with the same attempt_id returns the original claim. OutboxClaimOutcome::NoWork means no eligible unlocked row was visible; another worker may temporarily hold skipped work.

§Errors

Returns StoreError for attempt identity conflict, corrupt history, timing exhaustion, or database failure.

Source

pub async fn acknowledge_outbox_attempt( &self, fence: &DeliveryFence, evidence_digest: Option<Digest>, ) -> Result<OutboxCompletionOutcome, StoreError>

Commits a protocol acknowledgement under the exact live delivery fence.

§Errors

Returns StoreError for stale/expired fencing, conflicting lost-ack retries, corruption, or database failure.

Source

pub async fn fail_outbox_attempt( &self, fence: &DeliveryFence, failure: Failure, ) -> Result<OutboxCompletionOutcome, StoreError>

Commits public-safe failure evidence under the exact live delivery fence.

safe_after schedules another attempt at a durable database-clock boundary; never moves the delivery to dead-letter. Reconcile-first is rejected by the core duplicate-tolerant outbox contract.

§Errors

Returns StoreError for stale/expired fencing, unsafe advice, conflicting lost-ack retries, corruption, or database failure.

Source

pub async fn claim_lease( &self, tenant_id: &TenantId, run_id: RunId, attempt_id: AttemptId, ) -> Result<LeaseClaimOutcome, StoreError>

Claims an unowned or expired runnable run for a stable UUIDv7 attempt.

The database row is locked before the database clock is observed. An unexpired different owner is never replaced by this method. Retrying the same attempt returns LeaseClaimOutcome::Idempotent without allocating another fencing epoch.

§Errors

Returns StoreError when the run is missing, not runnable, quarantined, currently leased, exhausted, corrupt, or unavailable.

Source

pub async fn supersede_lease( &self, tenant_id: &TenantId, run_id: RunId, successor_attempt_id: AttemptId, ) -> Result<LeaseClaimOutcome, StoreError>

Explicitly supersedes any current lease with a stable successor attempt.

This is a trusted control-plane operation for drain, repair, and forced takeover. It increments the epoch even when the previous lease remains unexpired, fencing the old worker in the same locked-row transaction. Retrying the same successor attempt is idempotent. Supersession also clears a future delayed-retry gate, but the successor’s recovery plan still cannot authorize that node before its durable retry evidence is due.

§Errors

Returns StoreError when the run is missing, not runnable, quarantined, the successor attempt has expired, epochs are exhausted, data is corrupt, or the database is unavailable.

Source

pub async fn renew_lease( &self, fence: &RunFence, desired_expires_at: Timestamp, ) -> Result<LeaseRenewalOutcome, StoreError>

Renews an exact live fence to a caller-stable desired exclusive expiry.

Retrying the same desired expiry returns LeaseRenewalOutcome::Idempotent. The expiry must strictly extend the current value and remain within the configured horizon from the database observation.

§Errors

Returns StoreError for stale/expired ownership, unsafe expiry, missing run, corruption, or database failure.

Source

pub async fn observe_live_lease( &self, fence: &RunFence, ) -> Result<LiveLeaseObservation, StoreError>

Observes one exact fence against the current database clock.

Unlike an idempotent renewal result, this read cannot confirm an already expired historical write. It verifies the complete run scope and current wait projection, runnable lifecycle, quarantine state, exact attempt and epoch, and exclusive lease expiry in one repeatable-read transaction. Success proves liveness only at LiveLeaseObservation::observed_at.

§Errors

Returns explicit not-found, lifecycle, quarantine, stale-fence, lease-expiry, corruption, clock, or database failures.

Source

pub async fn release_lease( &self, fence: &RunFence, ) -> Result<LeaseReleaseOutcome, StoreError>

Releases an active lease under its exact fence, retaining the issued epoch.

A retry after successful release is idempotent only while no successor epoch has been issued.

§Errors

Returns StoreError for a stale fence, missing run, corruption, or database failure.

Source

pub async fn append_control_plane( &self, append: JournalAppend, projection: RunProjection, ) -> Result<AppendOutcome, StoreError>

Appends a trusted control-plane event and projection atomically.

§Errors

Rejects worker sources and returns explicit conflict, integrity, or database failures.

Source

pub async fn append_worker( &self, append: JournalAppend, projection: RunProjection, ) -> Result<AppendOutcome, StoreError>

Appends a worker event under its exact unexpired database fence.

An identical already-committed event is returned before stale-head or stale-fence rejection so a lost acknowledgement can converge safely.

§Errors

Rejects control-plane sources and returns explicit fencing, conflict, integrity, or database failures.

Source

pub async fn prepare_tool_invocation( &self, append: JournalAppend, intent: ToolInvocationIntent, ) -> Result<ToolInvocationCommitOutcome, StoreError>

Atomically prepares one fenced logical tool invocation and journal event.

The activation’s exact base checkpoint must still be the locked run’s current checkpoint. The database rechecks the worker fence while inserting the event, intent, revision zero, and updated run head. An identical event retry converges even after the lease or journal head has advanced.

§Errors

Returns explicit authority, lifecycle, idempotency, checkpoint, activation, fencing, integrity, transition, or database failures.

Source

pub async fn advance_tool_invocation( &self, append: JournalAppend, expected: &ToolInvocationHead, transition: ToolInvocationTransition, ) -> Result<ToolInvocationCommitOutcome, StoreError>

Atomically advances one fenced logical tool invocation and journal event.

The full durable current record is reloaded under the run and invocation locks, compared with expected, and passed through the core state machine. Every SQL mutation rechecks the exact live run fence. No transaction contains external tool work: StartAttempt commits before dispatch, while result, error, and reconciliation evidence is obtained before its corresponding outcome transaction.

§Errors

Returns explicit authority, lifecycle, idempotency, stale-head, checkpoint, fencing, transition, integrity, or database failures.

Source

pub async fn advance_tool_invocation_with_child_budget( &self, append: JournalAppend, expected: &ToolInvocationHead, transition: ToolInvocationTransition, child_budget: Option<Digest>, ) -> Result<ToolInvocationCommitOutcome, StoreError>

Advances with the exact verified child-account digest, checked under the run lock. Lost-acknowledgement recovery does not require a fresh budget observation.

Source

pub async fn prepare_model_invocation( &self, append: JournalAppend, intent: ModelInvocationIntent, ) -> Result<ModelInvocationCommitOutcome, StoreError>

Atomically prepares one fenced logical model invocation and journal event.

The exact activation checkpoint must still be current and ready. No provider I/O belongs in this transaction; dispatch starts only after the caller separately commits a StartAttempt revision.

§Errors

Returns explicit authority, lifecycle, idempotency, checkpoint, activation, fencing, integrity, transition, or database failures.

Source

pub async fn advance_model_invocation( &self, append: JournalAppend, expected: &ModelInvocationHead, transition: ModelInvocationTransition, ) -> Result<ModelInvocationCommitOutcome, StoreError>

Atomically advances one fenced logical model invocation and journal event.

The complete current record is restored under run and invocation locks, compared with expected, and passed through the core state machine. A StartAttempt revision and global attempt claim commit before exactly one provider exchange; a complete response or failure commits afterward.

§Errors

Returns explicit authority, lifecycle, idempotency, stale-head, checkpoint, fencing, transition, integrity, or database failures.

Source

pub async fn advance_model_invocation_with_child_budget( &self, append: JournalAppend, expected: &ModelInvocationHead, transition: ModelInvocationTransition, child_budget: Option<Digest>, ) -> Result<ModelInvocationCommitOutcome, StoreError>

Advances with the exact verified child-account digest, checked under the run lock. Lost-acknowledgement recovery does not require a fresh budget observation.

Source

pub async fn start_node_attempt( &self, append: JournalAppend, activation: NodeActivation, attempt_id: AttemptId, ) -> Result<NodeAttemptCommitOutcome, StoreError>

Durably starts one physical node attempt before user node code executes.

The worker event, run-wide physical-attempt claim, immutable start, and run journal head commit in one fenced transaction. A retry may supersede an unfinished attempt only under a higher fencing epoch, and may follow a failure only after its explicit database-observed safe-after delay.

For a start call, only NodeAttemptCommitOutcome::Committed grants this caller permission to launch node code. Idempotent proves the exact start already exists but cannot distinguish a lost acknowledgement from a concurrent owner; treat it as in flight and never launch from that outcome alone. An orphaned start is recovered under a higher run fence.

§Errors

Returns explicit authority, activation, retry-history/limit, lifecycle, checkpoint, journal, fencing, idempotency, integrity, or database errors.

Source

pub async fn start_recovered_node_attempt( &self, append: JournalAppend, plan: &ReadyNodeRecoveryPlan, node_id: &NodeId, attempt_id: AttemptId, ) -> Result<NodeAttemptCommitOutcome, StoreError>

Durably starts one node selected by a verified recovery plan.

This is the production handoff from deterministic replay to execution: the plan must bind the same tenant/run, checkpoint and worker fence; the selected node must be classified as dispatchable; and the append’s exact journal expectation cannot precede the plan observation. The ordinary node-attempt transaction then reloads current state and the latest durable predecessor, verifies the proposed successor and retry timing with the database clock, repeats the live-fence predicate in SQL, commits the start, and only then returns.

Multiple ready siblings may use one plan one at a time with an advancing exact journal expectation. A concurrent stale append fails explicitly and can be rebuilt from the newly committed head without rerunning the recovery planner. Retrying the identical event and physical attempt ID preserves the underlying lost-acknowledgement convergence.

Only NodeAttemptCommitOutcome::Committed grants this caller a fresh launch. Idempotent is durable in-flight evidence, not dispatch authority; never launch node code from it alone. No user node code or external I/O runs inside this method.

§Errors

Returns StoreError::InvalidReadyNodeDispatchPlan for crossed plan, append, checkpoint, journal, or fence scope; StoreError::ReadyNodeNotDispatchable for completed, deferred, in-flight, failed, exhausted, or absent nodes; otherwise returns the same durable, idempotency, lifecycle, history, fencing, and database failures as Self::start_node_attempt.

Source

pub async fn schedule_delayed_retry_wakeup( &self, plan: &ReadyNodeRecoveryPlan, ) -> Result<DelayedRetryScheduleOutcome, StoreError>

Durably suppresses scheduler claims until a recovery plan’s next retry.

The plan must contain at least one deferred node and no dispatchable, in-flight, failed, or exhausted node. Completed siblings are permitted because their immutable results remain pending while the delayed sibling waits. The transaction revalidates the exact checkpoint, journal head, live worker fence, lifecycle, and database clock, then preserves queue age, records the inclusive retry gate, and releases the lease atomically.

Retrying after a lost acknowledgement returns DelayedRetryScheduleOutcome::Idempotent only while the same fencing epoch, checkpoint, journal head, and retry boundary still own the run. If database time reaches the boundary before the update, Due leaves the lease in place so the caller can rebuild the plan without release/reclaim churn.

§Errors

Returns StoreError::InvalidDelayedRetryPlan for a crossed or immediately actionable plan, and otherwise returns explicit stale checkpoint, journal, lifecycle, fencing, clock, corruption, or database failures.

Source

pub async fn fail_node_attempt( &self, append: JournalAppend, expected: &NodeAttemptStartHead, failure: Failure, usage: BudgetUsage, ) -> Result<NodeAttemptCommitOutcome, StoreError>

Atomically records terminal public-safe failure evidence for an attempt.

The worker event, immutable completion, and run journal head commit in one transaction. The failure must name the new event as its direct cause and may authorize retry only with Never or SafeAfter semantics.

§Errors

Returns explicit authority, stale-start, terminal-state, lifecycle, checkpoint, journal, fencing, causation, integrity, or database errors.

Source

pub async fn succeed_node_attempt( &self, append: JournalAppend, expected: &NodeAttemptStartHead, intent: PendingNodeResultIntent, usage: BudgetUsage, ) -> Result<NodeAttemptCommitOutcome, StoreError>

Atomically completes an attempt with its immutable pending node result.

The worker event, pending result, exact invocation bindings, successful completion, and run journal head commit together. The event projection binds the completion digest, which in turn binds the exact result head.

§Errors

Returns explicit authority, stale-start, semantic-result, binding, lifecycle, checkpoint, journal, fencing, integrity, or database errors.

Source

pub async fn commit_pending_node_result( &self, _append: JournalAppend, _intent: PendingNodeResultIntent, ) -> Result<PendingNodeResultCommitOutcome, StoreError>

Rejects the pre-v6 pending-result write path.

Existing migration-5 rows remain readable, but creating a new result without first committing a physical node-attempt start would fabricate execution history. Use Self::start_node_attempt followed by Self::succeed_node_attempt.

§Errors

Always returns StoreError::NodeAttemptRequired.

Source

pub async fn append_control_plane_checkpoint( &self, append: JournalAppend, projection: RunProjection, checkpoint: CheckpointWrite, ) -> Result<CheckpointCommitOutcome, StoreError>

Atomically appends a control-plane event and commits the initial graph checkpoint.

Successor checkpoints must use Self::append_control_plane_barrier so the exact complete pending-result set is consumed in the same transaction.

§Errors

Rejects worker sources and returns explicit idempotency, parent, journal, integrity, or database failures.

Source

pub async fn append_worker_checkpoint( &self, append: JournalAppend, projection: RunProjection, checkpoint: CheckpointWrite, ) -> Result<CheckpointCommitOutcome, StoreError>

Atomically appends a fenced worker event and commits the initial graph checkpoint.

The database rechecks the exact unexpired lease while inserting the event, checkpoint, and updated run heads. Successors must use Self::append_worker_barrier so results cannot be bypassed.

§Errors

Rejects control-plane sources and returns explicit fencing, idempotency, parent, journal, integrity, or database failures.

Source

pub async fn append_control_plane_initial_wait_checkpoint( &self, append: JournalAppend, expected_revision: RunRevision, checkpoint: CheckpointWrite, registrations: Vec<WaitRegistrationIntent>, ) -> Result<WaitCheckpointCommitOutcome, StoreError>

Atomically commits the first graph checkpoint while suspending an active run on a complete durable interrupt/timer set.

The database clock materializes every compact lifecycle marker, so the caller supplies immutable registration intents rather than guessed registration timestamps. Successor wait barriers use the separate complete-result barrier API.

§Errors

Rejects worker sources, non-root checkpoints, invalid wait batches, stale lifecycle/journal state, identity conflicts, or database failures.

Source

pub async fn append_worker_initial_wait_checkpoint( &self, append: JournalAppend, expected_revision: RunRevision, checkpoint: CheckpointWrite, registrations: Vec<WaitRegistrationIntent>, ) -> Result<WaitCheckpointCommitOutcome, StoreError>

Fenced worker form of Self::append_control_plane_initial_wait_checkpoint.

§Errors

Rejects control-plane sources, non-root checkpoints, expired fencing, invalid wait batches, conflicts, corruption, or database failures.

Source

pub async fn resolve_interrupt( &self, append: JournalAppend, expected_revision: RunRevision, resolution: InterruptResolutionIntent, ) -> Result<InterruptResolutionCommitOutcome, StoreError>

Atomically commits an authenticated resolution and removes exactly one outstanding interrupt from the lifecycle wait set.

Resolution is a control-plane operation: the core intent already carries the authenticated principal and bounded scope snapshot evaluated again at the authoritative database observation.

§Errors

Rejects worker sources, stale state, expired/unauthorized/substituted resolutions, terminal conflicts, corruption, or database failures.

Source

pub async fn fire_timer( &self, append: JournalAppend, expected_revision: RunRevision, firing: TimerFiringIntent, ) -> Result<TimerFiringCommitOutcome, StoreError>

Atomically records a database-clock-valid firing and removes exactly one outstanding timer from the lifecycle wait set.

§Errors

Rejects worker sources, early/substituted firings, stale state, terminal conflicts, corruption, or database failures.

Source

pub async fn append_control_plane_abandon_waits( &self, append: JournalAppend, expected_revision: RunRevision, transition: RunTransition, ) -> Result<WaitAbandonmentCommitOutcome, StoreError>

Atomically applies cancellation/failure to a waiting run and records one abandonment fact for every outstanding interrupt and timer.

§Errors

Rejects worker sources, non-cancellation/failure transitions, stale state, incomplete evidence sets, corruption, or database failures.

Source

pub async fn append_worker_abandon_waits( &self, append: JournalAppend, expected_revision: RunRevision, transition: RunTransition, ) -> Result<WaitAbandonmentCommitOutcome, StoreError>

Fenced worker form of Self::append_control_plane_abandon_waits.

§Errors

Rejects control-plane sources, invalid transitions, stale/expired fencing, incomplete evidence, corruption, or database failures.

Source

pub async fn append_control_plane_wait_barrier( &self, append: JournalAppend, expected_revision: RunRevision, barrier: CheckpointBarrier, registrations: Vec<WaitRegistrationIntent>, ) -> Result<WaitCheckpointCommitOutcome, StoreError>

Atomically consumes a complete result barrier, commits its successor checkpoint, and suspends the run on one durable wait batch.

§Errors

Rejects worker sources, incomplete/substituted barriers, invalid wait batches, stale lifecycle/journal/checkpoint state, corruption, or database failures.

Source

pub async fn append_worker_wait_barrier( &self, append: JournalAppend, expected_revision: RunRevision, barrier: CheckpointBarrier, registrations: Vec<WaitRegistrationIntent>, ) -> Result<WaitCheckpointCommitOutcome, StoreError>

Fenced worker form of Self::append_control_plane_wait_barrier.

§Errors

Rejects control-plane sources, incomplete/substituted barriers, invalid waits, stale/expired fencing or durable state, corruption, or database failures.

Source

pub async fn append_control_plane_barrier( &self, append: JournalAppend, projection: RunProjection, barrier: CheckpointBarrier, ) -> Result<BarrierCommitOutcome, StoreError>

Atomically consumes a complete result barrier and commits its control-plane event and successor checkpoint.

Full checkpoint and result records are verified in a repeatable-read preflight without the run lock. The mutation transaction then locks the run, rechecks every compact result identity, and inserts the event, checkpoint, append-only consumption rows, lifecycle projection, and run pointers atomically.

§Errors

Rejects worker sources and returns explicit barrier completeness, conflict, idempotency, lifecycle, checkpoint, journal, integrity, or database failures.

Source

pub async fn append_worker_barrier( &self, append: JournalAppend, projection: RunProjection, barrier: CheckpointBarrier, ) -> Result<BarrierCommitOutcome, StoreError>

Atomically consumes a complete result barrier and commits its fenced worker event and successor checkpoint.

Every write statement rechecks the exact unexpired lease against the database clock. Lease expiry at any statement rolls back the event, checkpoint, every consumption row, and both run pointers.

§Errors

Rejects control-plane sources and returns explicit barrier completeness, conflict, idempotency, lifecycle, checkpoint, journal, fencing, integrity, or database failures.

Source

pub async fn load_journal_page( &self, tenant_id: &TenantId, run_id: RunId, after: Option<&JournalHead>, page_size: JournalPageSize, ) -> Result<JournalPage, StoreError>

Reads one repeatable-read, bounded page and verifies its hash-chain suffix.

after is an exact trusted cursor, not only a sequence number. The first page verifies from sequence one. A final page must end at the run row’s exact journal head observed in the same database snapshot.

§Errors

Returns StoreError for a missing run, crossed/stale cursor, corruption, invalid page size, or database failure.

Trait Implementations§

Source§

impl Clone for PostgresStore

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for PostgresStore

Source§

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl SkillActivationStore for PostgresStore

Source§

fn open( &self, request: SkillActingWindowOpenRequest, ) -> BoxFuture<'_, Result<SkillActingWindow, SkillActivationStoreError>>

Atomically commits one approval and database-clock acting window.
Source§

fn load_active( &self, tenant_id: TenantId, window_id: SkillActingWindowId, ) -> BoxFuture<'_, Result<SkillActingWindow, SkillActivationStoreError>>

Loads one exact currently active window for process restart recovery.
Source§

fn assert_active( &self, window: SkillActingWindow, ) -> BoxFuture<'_, Result<(), SkillActivationStoreError>>

Revalidates exact durable evidence immediately before sensitive work.
Source§

fn revoke( &self, window: SkillActingWindow, reason: SkillActingWindowRevocationReason, ) -> BoxFuture<'_, Result<SkillActingWindowRevocation, SkillActivationStoreError>>

Commits the first immutable revocation event and returns it idempotently.
Source§

impl ToolAuthorizationReceiptSink for PostgresStore

Source§

fn record( &self, receipt: ToolAuthorizationReceipt, ) -> BoxFuture<'_, Result<(), ToolAuthorizationReceiptSinkError>>

Durably records one exact authorization decision before provider I/O.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DynClone for T
where T: Clone,

Source§

fn __clone_box(&self, _: Private) -> *mut ()

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more