Drive a Graph from durable evidence.

Freeze one exact executable deployment

Build the registry before the scheduler can claim work. Every JSON Schema is offline, JSON Schema 2020-12, RFC 8785 canonical, and SHA-256 pinned. Every graph digest must close over one exact reducer plus every declared node executor. Missing, duplicate, mismatched, unresolved, and orphan bindings stop startup.

let mut schemas = JsonSchemaRegistryBuilder::with_default_limits();
register_standard_graph_driver_event_schema(&mut schemas)?;
register_standard_graph_lifecycle_event_schema(&mut schemas)?;
register_standard_agent_cancellation_event_schema(&mut schemas)?;
register_application_schemas(&mut schemas)?;

let mut executables = ExecutableGraphRegistryBuilder::new(schemas.build()?);
executables.register_graph(compiled_graph)?;
executables.register_reducer(reducer)?;
for executor in node_executors {
    executables.register_node(executor)?;
}

let driver = DurableGraphDriver::new(
    store,
    executables.build()?,
    DurableGraphDriverOptions::default(),
)?;

Install the standard audit schema through its registration function. Its immutable identity is https://stknot.com/schemas/runtime/graph-driver-event/1.0.0. Do not hard-code its digest into application code.

Agent Loop deployments must also install the lifecycle schema at https://stknot.com/schemas/runtime/graph-lifecycle-event/1.0.0 through register_standard_graph_lifecycle_event_schema.

Lifecycle deployments must also install the cancellation schema at https://stknot.com/schemas/runtime/agent-cancellation-event/1.0.0 through register_standard_agent_cancellation_event_schema.

Replay before executing

A claimed run first reloads and recompiles the checkpoint-pinned graph. The runtime then replays every committed noninitial checkpoint with the exact installed schemas and reducer, bounded pending-result memory, journal anchors, parent checkpoints, and immutable ready sets. Missing or contradictory durable evidence is quarantined beneath the current live fence before any node code can run.

A committed start is execution authority

The Driver commits one physical node-attempt start before spawning node code. Only a fresh NodeAttemptCommitOutcome::Committed launches the executor. An Idempotent start may represent a lost acknowledgement or another executor, so it is always treated as in flight.

While node code runs, no database transaction remains open. The Driver refreshes near-expiry ownership before launch, renews beneath a database-time-derived monotonic expiry watchdog, propagates a monotonic cancellation signal, enforces a hard deadline, and commits completion against the latest journal head. External model and tool effects must use their invocation ledgers; a raw external write inside a node cannot inherit reconciliation guarantees.

The process shutdown signal is separate from durable run cancellation. While a node is active, the Driver polls the run projection; once a cancellation request is observed it stops new dispatch, signals the node, applies a bounded cooperative grace period, and returns an exact lifecycle handoff.

let claim = store
    .claim_lease(&tenant_id, run_id, attempt_id)
    .await?;

let result = driver
    .drive(claim.lease().fence().clone(), shutdown_signal)
    .await?;

let (outcome, report) = result.into_parts();

Overlap work without making timing semantic

Executors remain Exclusive by default. Declare JournalIsolated only when execution appends no run Journal or invocation-ledger facts and its result cannot depend on sibling timing. This is a trusted deployment contract; external model or Tool work belongs in an ordered durable coordinator.

The Driver serializes all fresh starts in canonical NodeId order, runs the eligible batch under one lease/cancellation watchdog, buffers out-of-order completion, and commits terminal facts back in the same order. The effective width is bounded by process policy, compiled Graph policy, ready work, and the remaining event quantum. Exclusive nodes form batch boundaries.

impl GraphNodeExecutor for ReadOnlyComputeNode {
    fn scheduling(&self) -> GraphNodeScheduling {
        GraphNodeScheduling::JournalIsolated
    }

    // graph(), node_id(), and execute() omitted
}

let options = DurableGraphDriverOptions::default()
    .with_parallel_node_limit(8)?;

Handle every outcome explicitly

LifecycleBarrierReady

Immediately complete the Wait or successful Terminal metadata and use the handoff’s exact plan, journal head, revision, and live lease in one atomic provider commit. Never serialize or reconstruct this handoff.

Blocked

In-flight work must not be dispatched again beneath the same fence. Failed or exhausted work goes to the run-level failure policy with the plan’s exact evidence; retry authority is never inferred.

Deferred

The database-time wakeup and lease release are already durable. Do not create a second in-process timer.

Yielded

The bounded durable-event quantum ended between mutations and the lease was released. Re-enter through scheduler discovery and a new claim.

CancellationRequested

Durable run cancellation was observed. Use the exact lease-bound handoff for lifecycle confirmation; DurableAgentLoop performs this automatically and never invents usage.

Cancelled

The process-owned shutdown signal stopped local work and released the exact fence. A later claim performs durable recovery.

Normal application workers should use DurableAgentLoop to bind these handoffs to atomic lifecycle commits and exact-fence error cleanup.

Bound time, memory, and mutation retries

• GraphReplayLimits defaults to 64 MiB of retained compact results per historical barrier; the hard ceiling is 512 MiB.
• One drive call defaults to 1,024 Driver-owned durable events and yields only between durable operations.
• Ready-node concurrency defaults to one, must be enabled explicitly, and has a process hard ceiling of 64.
• The renewal interval must fit at least three times inside the provider lease duration. The default node deadline is 15 minutes.
• Cancellation polling and cooperative grace default to 250 ms and 5 s; hard maxima are 60 s and 5 minutes.
• Storage mutation retries are bounded and reuse the same durable event and attempt identities with capped exponential backoff.

Monitor replay counts and retained bytes, attempt starts and completions, batch starts and maximum observed width, Continue barriers, lease renewals, and mutation retries through GraphDriveReport.

Crash recovery has one authority path

1. Same fence

   An unfinished attempt remains in flight and cannot be launched twice.

2. Higher fence

   After lease expiry or trusted supersession, the successor fence can take over the unfinished physical attempt once.

3. Continue barrier

   The Driver consumes the complete result set, atomically commits the successor checkpoint, and independently validates it on the next noninitial replay.

4. Wait or Terminal

   The Driver retains the exact lease and returns a short-lived commit handoff instead of fabricating lifecycle metadata it does not own.

5. Cancellation

   The Driver hands exact durable intent to lifecycle. Exact ledger usage and database time become one terminal confirmation; unavailable evidence leaves the request recoverable.

Qualification evidence

CI runs the mandatory Runtime suite on PostgreSQL 16 and 17. Eight retain the Driver recovery/ordering coverage: Continue followed by noninitial replay and Terminal handoff; same-fence duplicate suppression; execution beyond the original lease through renewal; near-expiry refresh before launch; invalid initial-state quarantine before execution; higher-fence takeover; three siblings that complete in reverse order but commit canonically; and a higher-fence takeover of an orphaned parallel member. Remaining cases cover atomic success/Wait/failure/cancellation lifecycle commits, exact lost-ack recovery, Agent Loop cleanup, tenant and weighted scheduling, durable model/tool execution and streaming, provider-native multi-turn recovery, exact cancellation, atomic Agent admission, and durable run/result reads. Each database version also runs the provider suite. See the complete integration and operations contract before deploying this pre-alpha surface.