Pre-alpha documentation
Admit one Agent as an atomic durable fact.
Validate one authenticated Agent intent and atomically commit its database-clock admission, first event, initial checkpoint, Active lifecycle, and scheduler visibility.
Commit the executable boundary once
One PostgreSQL transaction stores the authenticated Agent, request,
policy, granted scopes, finite budget, graph, and database time together
with the sequence-one agent-admitted event, superstep-zero checkpoint,
Active lifecycle, and every scheduler projection. No worker can claim the run
between those writes.
The revised scheduler index requires an initial checkpoint. The legacy
low-level admit_run API therefore creates an addressable but scheduler-invisible
row; new Agent ingress must use the atomic facade.
Freeze every dependency before traffic
Register the standard admission, Graph Driver, and lifecycle schemas plus every application schema before freezing one executable registry. Install the exact graph/reducer/node closure locally and register the same compiled graph for the tenant in PostgreSQL. A retry requires that digest-pinned deployment to remain available.
The public-safe admission event schema is published at https://stknot.com/schemas/runtime/agent-admission-event/1.0.0. Register it through register_standard_agent_admission_event_schema instead of pinning a copied digest.
Retain exact retry authority
Authenticate the principal and evaluate the immutable policy outside this
facade. Internal callers of admit allocate one complete
AgentRunIds bundle and retain the request bytes; a timeout must
reuse all five IDs. User-facing ingress should instead use DurableAgentRuns::submit, which persists the key mapping and permits fresh candidate IDs.
let ids = AgentRunIds::generate();
// Persist external_idempotency_key -> ids before the first attempt.
let request = DurableAgentAdmissionRequest::new(
tenant_id,
ids,
agent_descriptor,
agent_request,
evaluated_budget_layers,
graph_reference,
admission_authority,
initial_state,
)?;
let retry_bytes = serde_json::to_vec(&request)?;
let outcome = admission.admit(request).await?; An ambiguous retry probes and verifies committed evidence before applying the current database clock, so an exact request can converge after its original deadline. Changed input, policy, budget, graph, initial state, ready set, event, checkpoint, or identity is a conflict—not a second run.
Reject drift before mutation
-
Resolve code
Require the exact executable graph and exact Agent-to-Graph input/output schema binding.
-
Validate data offline
Validate typed input, authorization evidence, initial state, and the closed audit event against one frozen JSON Schema 2020-12 registry.
-
Recheck durable truth
PostgreSQL independently verifies graph registration, entry nodes, checkpoint shape, database-time budget admissibility, and every immutable event/checkpoint projection.
Schema rejection, deadline expiry, graph drift, and an injected late transaction failure leave no run, event, checkpoint, admission, or scheduler residue.
Protect the admission snapshot
Admission bytes may contain user input, trusted instructions, principal attributes, authorization evidence, and policy limits. Use least-privilege roles, verified TLS, encrypted backups, tenant isolation, access auditing, and an explicit retention policy. Digests prove identity; they do not authenticate a principal or make data secret. The first journal event is deliberately public-safe correlation metadata only.
Qualification evidence
The PostgreSQL 16/17 matrix runs mandatory provider and durable Runtime integration suites. Admission coverage includes migration 15, exact retry after time-sensitive boundaries, changed-intent and tamper rejection, invalid-state rollback with zero residue, 24-way convergence, and runtime rejection of Agent/Graph or authorization-schema drift before any write. Read the complete integration and rollout contract before adopting this exact public-preview surface.