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
impl PostgresStore
Sourcepub 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>
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.
Sourcepub async fn load_child_run(
&self,
key: &ChildRunKey,
) -> Result<ChildRunRecord, StoreError>
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.
Sourcepub async fn load_child_budget_account(
&self,
tenant: &TenantId,
parent: RunId,
) -> Result<Option<ChildRunBudgetAccount>, StoreError>
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.
Sourcepub async fn include_child_usage(
&self,
tenant: &TenantId,
parent: RunId,
direct: BudgetUsage,
) -> Result<BudgetUsage, StoreError>
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.
Sourcepub async fn list_child_run_identities(
&self,
tenant: &TenantId,
parent: RunId,
) -> Result<Vec<(Digest, RunId)>, StoreError>
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.
Sourcepub async fn pending_child_settlements(
&self,
tenant: &TenantId,
) -> Result<Vec<ChildRunKey>, StoreError>
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.
Sourcepub async fn pending_child_settlements_after(
&self,
tenant: &TenantId,
after: Option<&ChildRunKey>,
) -> Result<Vec<ChildRunKey>, StoreError>
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.
Sourcepub async fn settle_child_run(
&self,
key: &ChildRunKey,
append: JournalAppend,
) -> Result<ChildRunSettlementOutcome, StoreError>
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
impl PostgresStore
Sourcepub async fn register_child_join(
&self,
request: ChildRunJoinRequest,
node: &NodeAttemptStartHead,
append: JournalAppend,
) -> Result<ChildJoinCommitOutcome, StoreError>
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.
Sourcepub async fn publish_child_join(
&self,
request: &ChildRunJoinRequest,
append: JournalAppend,
) -> Result<ChildJoinCommitOutcome, StoreError>
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.
Sourcepub async fn load_child_join(
&self,
activation: &NodeActivation,
) -> Result<Option<ChildJoinRecord>, StoreError>
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.
Sourcepub async fn pending_child_joins_after(
&self,
tenant: &TenantId,
after: Option<&ChildRunJoinRequest>,
) -> Result<Vec<ChildRunJoinRequest>, StoreError>
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
impl PostgresStore
Sourcepub async fn due_agent_deadlines_after(
&self,
tenant: &TenantId,
after: Option<&AgentDeadlineCursor>,
) -> Result<Vec<AgentDeadlineCursor>, StoreError>
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.
Sourcepub 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>
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
impl PostgresStore
Sourcepub async fn request_run_failure_close(
&self,
checkpoint: &CheckpointHead,
failure: Failure,
direct_usage: BudgetUsage,
append: JournalAppend,
) -> Result<RunFailureCloseOutcome, StoreError>
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.
Sourcepub async fn load_run_failure_close(
&self,
tenant: &TenantId,
run_id: RunId,
) -> Result<Option<RunFailureCloseRecord>, StoreError>
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.
Sourcepub async fn pending_run_failure_closes_after(
&self,
tenant: &TenantId,
after: Option<&RunFailureCloseCursor>,
) -> Result<Vec<RunFailureCloseCursor>, StoreError>
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.
Sourcepub async fn complete_run_failure_close(
&self,
append: JournalAppend,
) -> Result<RunFailureCloseOutcome, StoreError>
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
impl PostgresStore
Sourcepub async fn load_child_cancellation(
&self,
key: &ChildRunKey,
) -> Result<ChildCancellationRecord, StoreError>
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.
Sourcepub async fn pending_child_cancellations_after(
&self,
tenant: &TenantId,
after: Option<&ChildRunKey>,
) -> Result<Vec<ChildRunKey>, StoreError>
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.
Sourcepub async fn deliver_child_cancellation(
&self,
key: &ChildRunKey,
append: JournalAppend,
request: RunCancellationRequest,
) -> Result<ChildCancellationDelivery, StoreError>
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
impl PostgresStore
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.
Loads one exact immutable authorization receipt with full validation.
§Errors
Returns not-found, corruption, or database availability failures.
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
impl PostgresStore
Sourcepub async fn open_skill_acting_window(
&self,
request: SkillActingWindowOpenRequest,
) -> Result<SkillActingWindow, StoreError>
pub async fn open_skill_acting_window( &self, request: SkillActingWindowOpenRequest, ) -> Result<SkillActingWindow, StoreError>
Atomically persists one exact approval and database-clock acting window.
Sourcepub async fn load_active_skill_acting_window(
&self,
tenant: &TenantId,
window_id: SkillActingWindowId,
) -> Result<SkillActingWindow, StoreError>
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.
Sourcepub async fn assert_skill_acting_window_active(
&self,
expected: &SkillActingWindow,
) -> Result<(), StoreError>
pub async fn assert_skill_acting_window_active( &self, expected: &SkillActingWindow, ) -> Result<(), StoreError>
Revalidates exact durable evidence and active state at database time.
Sourcepub async fn revoke_skill_acting_window(
&self,
expected: &SkillActingWindow,
reason: SkillActingWindowRevocationReason,
) -> Result<SkillActingWindowRevocation, StoreError>
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
impl PostgresStore
Sourcepub const fn options(&self) -> &PostgresStoreOptions
pub const fn options(&self) -> &PostgresStoreOptions
Returns the validated immutable provider options used by this pool.
Sourcepub async fn connect(
database_url: &str,
options: PostgresStoreOptions,
) -> Result<Self, StoreError>
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.
Sourcepub async fn connect_config(
config: PostgresStoreConfig,
) -> Result<Self, StoreError>
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.
Sourcepub async fn connect_from_env() -> Result<Self, StoreError>
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.
Sourcepub async fn connect_development(database_url: &str) -> Result<Self, StoreError>
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.
Sourcepub async fn migrate_database(
database_url: &str,
options: PostgresStoreOptions,
) -> Result<(), StoreError>
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.
Sourcepub async fn verify_schema(&self) -> Result<(), StoreError>
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.
Sourcepub async fn health_check(&self) -> Result<(), StoreError>
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.
Sourcepub async fn observe_database_clock(&self) -> Result<Timestamp, StoreError>
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.
Sourcepub async fn register_artifact(
&self,
registration: ArtifactRegistration,
) -> Result<ArtifactRegistrationOutcome, StoreError>
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.
Sourcepub async fn load_artifact(
&self,
identity: &ArtifactIdentity,
) -> Result<StoredArtifact, StoreError>
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.
Sourcepub async fn register_graph_definition(
&self,
tenant_id: TenantId,
graph: CompiledGraph,
) -> Result<GraphDefinitionRegistrationOutcome, StoreError>
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.
Sourcepub async fn load_graph_definition(
&self,
tenant_id: &TenantId,
reference: &GraphReference,
) -> Result<StoredGraphDefinition, StoreError>
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.
Sourcepub async fn register_scheduler_fairness_policy(
&self,
registration: SchedulerFairnessPolicyRegistration,
) -> Result<SchedulerFairnessPolicyRegistrationOutcome, StoreError>
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.
Sourcepub async fn load_scheduler_fairness_policy(
&self,
shard_id: &SchedulerShardId,
) -> Result<StoredSchedulerFairnessPolicy, StoreError>
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.
Sourcepub async fn reserve_scheduler_fairness_slot(
&self,
shard_id: &SchedulerShardId,
policy_digest: Digest,
reservation_id: SchedulerReservationId,
) -> Result<SchedulerFairnessReservation, StoreError>
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.
Sourcepub async fn prune_scheduler_fairness_reservations(
&self,
policy: SchedulerFairnessRetentionPolicy,
) -> Result<SchedulerFairnessRetentionReport, StoreError>
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.
Sourcepub async fn admit_run(
&self,
provenance: AgentResultProvenance,
) -> Result<AdmissionOutcome, StoreError>
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.
Sourcepub async fn admit_agent_run<V>(
&self,
intent: AgentAdmissionIntent,
append: JournalAppend,
checkpoint_write: CheckpointWrite,
schemas: &V,
) -> Result<AgentAdmissionCommitOutcome, StoreError>where
V: GraphSchemaValidator + ?Sized,
pub async fn admit_agent_run<V>(
&self,
intent: AgentAdmissionIntent,
append: JournalAppend,
checkpoint_write: CheckpointWrite,
schemas: &V,
) -> Result<AgentAdmissionCommitOutcome, StoreError>where
V: GraphSchemaValidator + ?Sized,
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.
Sourcepub async fn submit_agent_run<V>(
&self,
key: &AgentSubmissionKey,
intent: AgentAdmissionIntent,
append: JournalAppend,
checkpoint_write: CheckpointWrite,
schemas: &V,
) -> Result<AgentSubmissionCommitOutcome, StoreError>where
V: GraphSchemaValidator + ?Sized,
pub async fn submit_agent_run<V>(
&self,
key: &AgentSubmissionKey,
intent: AgentAdmissionIntent,
append: JournalAppend,
checkpoint_write: CheckpointWrite,
schemas: &V,
) -> Result<AgentSubmissionCommitOutcome, StoreError>where
V: GraphSchemaValidator + ?Sized,
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.
Sourcepub async fn load_agent_submission(
&self,
tenant_id: &TenantId,
key: &AgentSubmissionKey,
) -> Result<StoredAgentSubmission, StoreError>
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.
Sourcepub async fn load_agent_admission(
&self,
tenant_id: &TenantId,
run_id: RunId,
) -> Result<StoredAgentAdmission, StoreError>
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.
Sourcepub async fn load_run(
&self,
tenant_id: &TenantId,
run_id: RunId,
) -> Result<StoredRun, StoreError>
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.
Sourcepub async fn quarantine_run(
&self,
request: RunQuarantineRequest,
) -> Result<RunQuarantineCommitOutcome, StoreError>
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.
Sourcepub async fn with_corruption_quarantine<T, F>(
&self,
context: CorruptionQuarantineContext,
recovery_read: F,
) -> Result<T, StoreError>
pub async fn with_corruption_quarantine<T, F>( &self, context: CorruptionQuarantineContext, recovery_read: F, ) -> 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.
Sourcepub async fn begin_claimed_run_recovery(
&self,
fence: RunFence,
context: CorruptionQuarantineContext,
) -> Result<ClaimedRunRecovery<'_>, StoreError>
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.
Sourcepub async fn load_run_quarantine(
&self,
tenant_id: &TenantId,
run_id: RunId,
) -> Result<RunQuarantine, StoreError>
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.
Sourcepub async fn load_interrupt_request(
&self,
tenant_id: &TenantId,
run_id: RunId,
interrupt_id: InterruptId,
) -> Result<InterruptRequest, StoreError>
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.
Sourcepub async fn load_durable_timer(
&self,
tenant_id: &TenantId,
run_id: RunId,
timer_id: TimerId,
) -> Result<DurableTimer, StoreError>
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.
Sourcepub async fn load_interrupt_record(
&self,
tenant_id: &TenantId,
run_id: RunId,
interrupt_id: InterruptId,
) -> Result<InterruptRecord, StoreError>
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.
Sourcepub async fn load_durable_timer_record(
&self,
tenant_id: &TenantId,
run_id: RunId,
timer_id: TimerId,
) -> Result<DurableTimerRecord, StoreError>
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.
Sourcepub async fn load_interrupt_abandonment(
&self,
tenant_id: &TenantId,
run_id: RunId,
interrupt_id: InterruptId,
) -> Result<WaitAbandonment, StoreError>
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.
Sourcepub async fn load_timer_abandonment(
&self,
tenant_id: &TenantId,
run_id: RunId,
timer_id: TimerId,
) -> Result<WaitAbandonment, StoreError>
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.
Sourcepub async fn load_due_timer_page(
&self,
tenant_id: &TenantId,
cursor: Option<&DueTimerPageCursor>,
page_size: WaitDiscoveryPageSize,
) -> Result<DueTimerPage, StoreError>
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.
Sourcepub async fn load_expired_interrupt_page(
&self,
tenant_id: &TenantId,
cursor: Option<&ExpiredInterruptPageCursor>,
page_size: WaitDiscoveryPageSize,
) -> Result<ExpiredInterruptPage, StoreError>
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.
Sourcepub async fn load_runnable_run_page(
&self,
tenant_id: &TenantId,
cursor: Option<&RunnableRunPageCursor>,
page_size: RunnableRunPageSize,
) -> Result<RunnableRunPage, StoreError>
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.
Sourcepub async fn register_outbox_destination(
&self,
destination: OutboxDestinationRef,
config: JournalPayload,
) -> Result<OutboxDestinationRegistrationOutcome, StoreError>
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.
Sourcepub async fn load_outbox_destination(
&self,
destination: &OutboxDestinationRef,
) -> Result<StoredOutboxDestination, StoreError>
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.
Sourcepub async fn load_outbox_delivery(
&self,
tenant_id: &TenantId,
run_id: RunId,
delivery_id: DeliveryId,
) -> Result<OutboxDelivery, StoreError>
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.
Sourcepub async fn append_control_plane_with_outbox(
&self,
append: JournalAppend,
projection: RunProjection,
deliveries: Vec<OutboxDeliveryIntent>,
) -> Result<OutboxEnqueueOutcome, StoreError>
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.
Sourcepub async fn append_worker_with_outbox(
&self,
append: JournalAppend,
projection: RunProjection,
deliveries: Vec<OutboxDeliveryIntent>,
) -> Result<OutboxEnqueueOutcome, StoreError>
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.
Sourcepub async fn load_checkpoint(
&self,
tenant_id: &TenantId,
run_id: RunId,
checkpoint_id: CheckpointId,
) -> Result<Checkpoint, StoreError>
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.
Sourcepub async fn load_current_checkpoint(
&self,
tenant_id: &TenantId,
run_id: RunId,
) -> Result<Option<Checkpoint>, StoreError>
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.
Sourcepub async fn load_checkpoint_lineage_page(
&self,
tenant_id: &TenantId,
run_id: RunId,
from: Option<&CheckpointHead>,
page_size: CheckpointLineagePageSize,
) -> Result<CheckpointLineagePage, StoreError>
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.
Sourcepub async fn load_tool_invocation(
&self,
tenant_id: &TenantId,
run_id: RunId,
invocation_id: InvocationId,
) -> Result<ToolInvocation, StoreError>
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.
Sourcepub async fn load_tool_invocation_revision(
&self,
tenant_id: &TenantId,
run_id: RunId,
invocation_id: InvocationId,
revision: ToolInvocationRevision,
) -> Result<(JournalEvent, ToolInvocation), StoreError>
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.
Sourcepub 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>
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.
Sourcepub async fn load_model_invocation(
&self,
tenant_id: &TenantId,
run_id: RunId,
invocation_id: InvocationId,
) -> Result<ModelInvocation, StoreError>
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.
Sourcepub 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>
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.
Sourcepub async fn load_node_attempt(
&self,
tenant_id: &TenantId,
run_id: &RunId,
attempt_id: AttemptId,
) -> Result<NodeAttempt, StoreError>
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.
Sourcepub async fn load_node_attempt_history_page(
&self,
activation: &NodeActivation,
cursor: Option<&NodeAttempt>,
page_size: NodeAttemptHistoryPageSize,
) -> Result<NodeAttemptHistoryPage, StoreError>
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.
Sourcepub async fn load_pending_node_result(
&self,
activation: &NodeActivation,
) -> Result<PendingNodeResult, StoreError>
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.
Sourcepub async fn load_unconsumed_pending_node_result_page(
&self,
base: &CheckpointHead,
cursor: Option<&PendingNodeResultPageCursor>,
page_size: PendingNodeResultPageSize,
) -> Result<PendingNodeResultPage, StoreError>
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.
Sourcepub 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>
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.
Sourcepub async fn claim_outbox_delivery(
&self,
tenant_id: &TenantId,
attempt_id: AttemptId,
) -> Result<OutboxClaimOutcome, StoreError>
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.
Sourcepub async fn acknowledge_outbox_attempt(
&self,
fence: &DeliveryFence,
evidence_digest: Option<Digest>,
) -> Result<OutboxCompletionOutcome, StoreError>
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.
Sourcepub async fn fail_outbox_attempt(
&self,
fence: &DeliveryFence,
failure: Failure,
) -> Result<OutboxCompletionOutcome, StoreError>
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.
Sourcepub async fn claim_lease(
&self,
tenant_id: &TenantId,
run_id: RunId,
attempt_id: AttemptId,
) -> Result<LeaseClaimOutcome, StoreError>
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.
Sourcepub async fn supersede_lease(
&self,
tenant_id: &TenantId,
run_id: RunId,
successor_attempt_id: AttemptId,
) -> Result<LeaseClaimOutcome, StoreError>
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.
Sourcepub async fn renew_lease(
&self,
fence: &RunFence,
desired_expires_at: Timestamp,
) -> Result<LeaseRenewalOutcome, StoreError>
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.
Sourcepub async fn observe_live_lease(
&self,
fence: &RunFence,
) -> Result<LiveLeaseObservation, StoreError>
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.
Sourcepub async fn release_lease(
&self,
fence: &RunFence,
) -> Result<LeaseReleaseOutcome, StoreError>
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.
Sourcepub async fn append_control_plane(
&self,
append: JournalAppend,
projection: RunProjection,
) -> Result<AppendOutcome, StoreError>
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.
Sourcepub async fn append_worker(
&self,
append: JournalAppend,
projection: RunProjection,
) -> Result<AppendOutcome, StoreError>
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.
Sourcepub async fn prepare_tool_invocation(
&self,
append: JournalAppend,
intent: ToolInvocationIntent,
) -> Result<ToolInvocationCommitOutcome, StoreError>
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.
Sourcepub async fn advance_tool_invocation(
&self,
append: JournalAppend,
expected: &ToolInvocationHead,
transition: ToolInvocationTransition,
) -> Result<ToolInvocationCommitOutcome, StoreError>
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.
Sourcepub async fn advance_tool_invocation_with_child_budget(
&self,
append: JournalAppend,
expected: &ToolInvocationHead,
transition: ToolInvocationTransition,
child_budget: Option<Digest>,
) -> Result<ToolInvocationCommitOutcome, StoreError>
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.
Sourcepub async fn prepare_model_invocation(
&self,
append: JournalAppend,
intent: ModelInvocationIntent,
) -> Result<ModelInvocationCommitOutcome, StoreError>
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.
Sourcepub async fn advance_model_invocation(
&self,
append: JournalAppend,
expected: &ModelInvocationHead,
transition: ModelInvocationTransition,
) -> Result<ModelInvocationCommitOutcome, StoreError>
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.
Sourcepub async fn advance_model_invocation_with_child_budget(
&self,
append: JournalAppend,
expected: &ModelInvocationHead,
transition: ModelInvocationTransition,
child_budget: Option<Digest>,
) -> Result<ModelInvocationCommitOutcome, StoreError>
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.
Sourcepub async fn start_node_attempt(
&self,
append: JournalAppend,
activation: NodeActivation,
attempt_id: AttemptId,
) -> Result<NodeAttemptCommitOutcome, StoreError>
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.
Sourcepub async fn start_recovered_node_attempt(
&self,
append: JournalAppend,
plan: &ReadyNodeRecoveryPlan,
node_id: &NodeId,
attempt_id: AttemptId,
) -> Result<NodeAttemptCommitOutcome, StoreError>
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.
Sourcepub async fn schedule_delayed_retry_wakeup(
&self,
plan: &ReadyNodeRecoveryPlan,
) -> Result<DelayedRetryScheduleOutcome, StoreError>
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.
Sourcepub async fn fail_node_attempt(
&self,
append: JournalAppend,
expected: &NodeAttemptStartHead,
failure: Failure,
usage: BudgetUsage,
) -> Result<NodeAttemptCommitOutcome, StoreError>
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.
Sourcepub async fn succeed_node_attempt(
&self,
append: JournalAppend,
expected: &NodeAttemptStartHead,
intent: PendingNodeResultIntent,
usage: BudgetUsage,
) -> Result<NodeAttemptCommitOutcome, StoreError>
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.
Sourcepub async fn commit_pending_node_result(
&self,
_append: JournalAppend,
_intent: PendingNodeResultIntent,
) -> Result<PendingNodeResultCommitOutcome, StoreError>
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.
Sourcepub async fn append_control_plane_checkpoint(
&self,
append: JournalAppend,
projection: RunProjection,
checkpoint: CheckpointWrite,
) -> Result<CheckpointCommitOutcome, StoreError>
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.
Sourcepub async fn append_worker_checkpoint(
&self,
append: JournalAppend,
projection: RunProjection,
checkpoint: CheckpointWrite,
) -> Result<CheckpointCommitOutcome, StoreError>
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.
Sourcepub async fn append_control_plane_initial_wait_checkpoint(
&self,
append: JournalAppend,
expected_revision: RunRevision,
checkpoint: CheckpointWrite,
registrations: Vec<WaitRegistrationIntent>,
) -> Result<WaitCheckpointCommitOutcome, StoreError>
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.
Sourcepub async fn append_worker_initial_wait_checkpoint(
&self,
append: JournalAppend,
expected_revision: RunRevision,
checkpoint: CheckpointWrite,
registrations: Vec<WaitRegistrationIntent>,
) -> Result<WaitCheckpointCommitOutcome, StoreError>
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.
Sourcepub async fn resolve_interrupt(
&self,
append: JournalAppend,
expected_revision: RunRevision,
resolution: InterruptResolutionIntent,
) -> Result<InterruptResolutionCommitOutcome, StoreError>
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.
Sourcepub async fn fire_timer(
&self,
append: JournalAppend,
expected_revision: RunRevision,
firing: TimerFiringIntent,
) -> Result<TimerFiringCommitOutcome, StoreError>
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.
Sourcepub async fn append_control_plane_abandon_waits(
&self,
append: JournalAppend,
expected_revision: RunRevision,
transition: RunTransition,
) -> Result<WaitAbandonmentCommitOutcome, StoreError>
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.
Sourcepub async fn append_worker_abandon_waits(
&self,
append: JournalAppend,
expected_revision: RunRevision,
transition: RunTransition,
) -> Result<WaitAbandonmentCommitOutcome, StoreError>
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.
Sourcepub async fn append_control_plane_wait_barrier(
&self,
append: JournalAppend,
expected_revision: RunRevision,
barrier: CheckpointBarrier,
registrations: Vec<WaitRegistrationIntent>,
) -> Result<WaitCheckpointCommitOutcome, StoreError>
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.
Sourcepub async fn append_worker_wait_barrier(
&self,
append: JournalAppend,
expected_revision: RunRevision,
barrier: CheckpointBarrier,
registrations: Vec<WaitRegistrationIntent>,
) -> Result<WaitCheckpointCommitOutcome, StoreError>
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.
Sourcepub async fn append_control_plane_barrier(
&self,
append: JournalAppend,
projection: RunProjection,
barrier: CheckpointBarrier,
) -> Result<BarrierCommitOutcome, StoreError>
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.
Sourcepub async fn append_worker_barrier(
&self,
append: JournalAppend,
projection: RunProjection,
barrier: CheckpointBarrier,
) -> Result<BarrierCommitOutcome, StoreError>
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.
Sourcepub async fn load_journal_page(
&self,
tenant_id: &TenantId,
run_id: RunId,
after: Option<&JournalHead>,
page_size: JournalPageSize,
) -> Result<JournalPage, StoreError>
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
impl Clone for PostgresStore
Source§impl Debug for PostgresStore
impl Debug for PostgresStore
Source§impl SkillActivationStore for PostgresStore
impl SkillActivationStore for PostgresStore
Source§fn open(
&self,
request: SkillActingWindowOpenRequest,
) -> BoxFuture<'_, Result<SkillActingWindow, SkillActivationStoreError>>
fn open( &self, request: SkillActingWindowOpenRequest, ) -> BoxFuture<'_, Result<SkillActingWindow, SkillActivationStoreError>>
Source§fn load_active(
&self,
tenant_id: TenantId,
window_id: SkillActingWindowId,
) -> BoxFuture<'_, Result<SkillActingWindow, SkillActivationStoreError>>
fn load_active( &self, tenant_id: TenantId, window_id: SkillActingWindowId, ) -> BoxFuture<'_, Result<SkillActingWindow, SkillActivationStoreError>>
Source§fn assert_active(
&self,
window: SkillActingWindow,
) -> BoxFuture<'_, Result<(), SkillActivationStoreError>>
fn assert_active( &self, window: SkillActingWindow, ) -> BoxFuture<'_, Result<(), SkillActivationStoreError>>
Source§fn revoke(
&self,
window: SkillActingWindow,
reason: SkillActingWindowRevocationReason,
) -> BoxFuture<'_, Result<SkillActingWindowRevocation, SkillActivationStoreError>>
fn revoke( &self, window: SkillActingWindow, reason: SkillActingWindowRevocationReason, ) -> BoxFuture<'_, Result<SkillActingWindowRevocation, SkillActivationStoreError>>
Source§impl ToolAuthorizationReceiptSink for PostgresStore
impl ToolAuthorizationReceiptSink for PostgresStore
Source§fn record(
&self,
receipt: ToolAuthorizationReceipt,
) -> BoxFuture<'_, Result<(), ToolAuthorizationReceiptSinkError>>
fn record( &self, receipt: ToolAuthorizationReceipt, ) -> BoxFuture<'_, Result<(), ToolAuthorizationReceiptSinkError>>
Auto Trait Implementations§
impl !RefUnwindSafe for PostgresStore
impl !UnwindSafe for PostgresStore
impl Forget for PostgresStore
impl Freeze for PostgresStore
impl Move for PostgresStore
impl Send for PostgresStore
impl Sync for PostgresStore
impl Unpin for PostgresStore
impl UnsafeUnpin for PostgresStore
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
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