Pre-alpha documentation

Documentation that follows the code.

StateKnot documentation distinguishes implemented evidence from active design work and planned v1 capabilities.

The honest starting point

StateKnot does not yet expose a stable public model/tool Agent API. Its product crates are available as the exact 0.1.0-alpha.1 public preview. Today you can compile a deterministic Graph, freeze its executable deployment, replay noninitial checkpoints, and run a tenant-scoped durable Graph loop through atomic lifecycle commits on PostgreSQL. Provider-neutral durable model/tool attempts, weighted cross-tenant selection, a typed Agent contract, and the first OpenAI Responses and Anthropic Messages adapters are also implemented. Atomic durable Agent admission binds those contracts to scheduler-visible work, while durable ingress keys and the public run/result facade recover lost acknowledgements and verify terminal reads. The prebuilt provider-native Agent graph now adds recovered multi-turn Tools, bounded ordered read-only concurrency, serialized write barriers, policy, accounting, and exact cancellation. AgentService v1 now exposes submission, verified reads, and cancellation as an authorization-first embedding boundary. The general MCP Tool client now adds bounded dynamic discovery, JSON/request-scoped SSE, custom headers, MRTR, and interactive OAuth authorization; the strict MCP Remote Tool profile preserves the stronger durable binding. The MCP Server profile now exposes bounded Tools, Resources, Prompts, Completion, and MRTR behind the strict production transport. The A2A 1.0 Server profile now adds bounded Agent Card, messaging, task, streaming, cancellation, resubscription, and push-management boundaries across HTTP+JSON, JSON-RPC, and SSE; its frozen official TCK gate passes 177 cases with zero failures or errors. The A2A 1.0 Client and durable remote agent implement all eleven dual-binding operations and preserve lost sends as PostgreSQL-backed Unknown outcomes. They also support bounded operator-attested context/history lookup and message-ID replay. The durable artifact boundary polls accepted tasks directly without resending, then registers terminal parts as immutable PostgreSQL facts backed by private, fully verified S3-compatible object bytes. Stable network Agent transport, MCP Tasks, a production durable A2A task/push backend, Client live-peer and recovery-attestation qualification, gRPC, and production qualification remain release blockers.

Choose a path

Install the public alpha

Pin 0.1.0-alpha.1 exactly, then review the compatibility, MSRV, durable-data, and release contract before adopting it.

Read the release policy

Validate the repository

Install the pinned Rust toolchain and run the same formatting, lint, test, and documentation gates used by CI.

Start locally

Build a typed Agent contract

Generate and pin typed schemas, bind provider profiles offline, and construct the first-party OpenAI Responses and Anthropic Messages adapters.

Build the contract

Admit an Agent atomically

Bind authenticated intent, finite budgets, database time, the first event, and the initial graph checkpoint as one retryable durable fact.

Integrate admission

Submit and read a durable run

Persist one tenant-scoped idempotency decision, recover the original run after a lost response, and read a verified terminal result.

Integrate runs and results

Expose AgentService v1

Authorize exact Agent revisions before existence disclosure, recover durable submissions, read verified Runs, and request two-phase cancellation.

Integrate the service

Compile a deterministic graph

Run the maintained Rust example, understand the compiler's fail-closed checks, and register one exact immutable definition.

Build the graph

Understand durability

Follow one run through journal facts, immutable checkpoints, lease fencing, pending results, barriers, and recovery.

Read the model

Drive a durable Graph

Freeze executable schemas, reducers, and nodes; replay noninitial checkpoints; then run canonical bounded sibling batches under one fence.

Integrate the Driver

Run the durable Agent Loop

Bind lifecycle evidence, atomic Wait/Terminal/failure/cancellation commits, and one tenant-scoped scheduler tick to the proven Driver.

Integrate the loop

Execute durable invocations

Freeze exact model/tool providers, commit physical starts before external I/O, validate streams, and retry terminal persistence without redispatch.

Integrate invocations

Call a general MCP Tool

Discover a bounded stateless MCP 2026-07-28 Tool catalog, consume JSON/request-scoped SSE, and mediate multi-round input safely.

Use the Tool client

Authorize an MCP resource

Integrate challenge-driven OAuth discovery, PKCE, exact issuer/callback validation, bounded replay, and durable credential stores.

Configure OAuth

Bind one MCP Remote Tool

Discover a strict stateless MCP 2026-07-28 Tool once, pin its identity and schemas, and preserve ambiguous write outcomes.

Integrate MCP

Expose an MCP Server

Freeze bounded Tool, Resource, and Prompt catalogs, authorize decoded operations, mediate MRTR, and mount one strict stateless HTTP service.

Build the Server profile

Call a durable A2A agent

Freeze one Agent Card and local contract; then preserve unknown sends or reconcile them through an explicitly attested remote guarantee.

Integrate the A2A Client

Persist durable artifacts

Poll accepted A2A tasks without resending, then bind terminal parts to immutable PostgreSQL metadata and private verified object bytes.

Configure artifact storage

Run the provider-native Agent

Compile one pinned multi-turn model/tool graph, overlap bounded read-only Tools behind write barriers, and recover transcripts without redispatch.

Integrate the Agent graph

Schedule tenants fairly

Compile immutable weights, reserve one replica-global order, inspect exact starvation bounds, and retain lost-ack evidence.

Configure fairness

Operate PostgreSQL

Review the implemented provider boundary, secure defaults, migration sequence, and mandatory integration test path.

Open the guide

Check the claims

Separate implemented code from active work and v1 scope before depending on an API or protocol surface.

View status

What these docs cover now

Core contracts: Typed, bounded domain values for agents, models, tools, runs, compiled graphs, deterministic barriers, checkpoints, invocations, waits, results, and recovery evidence.
PostgreSQL durability: Exact migrations, journal and checkpoint integrity, leases and fencing, invocation ledgers, pending results, barriers, durable waits, outbox delivery, quarantine, ready-node recovery planning, indexed delayed-retry wakeups, and the tenant-scoped immutable graph registry.
Durable Graph runtime: Offline executable registration, independent bounded replay, durable-before-dispatch node execution, lease renewal, automatic Continue barriers, and typed lifecycle handoffs.
Lifecycle and Agent Loop: Trusted terminal evidence, database-time Wait registration, atomic success/failure transitions, exact lost-ack convergence, bounded cleanup, and one tenant-scoped scheduler quantum.
Atomic Agent admission: Authenticated immutable intent, deterministic finite budgets, database-clock commit, sequence-one audit event, superstep-zero checkpoint, exact lost-ack retry, and fully verified durable loads.
Durable Agent runs and results: Tenant-scoped ingress idempotency, fresh-ID retry convergence, verified public lifecycle snapshots, terminal results, and fail-closed run/key lookups.
AgentService v1: Exact-version deployment binding, authorization before existence disclosure, durable submission recovery, verified reads, and caller-retained two-phase cancellation identities.
Typed Agent and provider adapters: Generated, canonical digest-pinned input/output schemas; offline provider-profile binding; bounded typed request/result validation; and first-party OpenAI Responses and Anthropic Messages unary and SSE transports.
General MCP Tool client: Bounded stateless discovery and pagination, JSON/request-scoped SSE, standard and nested custom headers, invalid-Tool isolation, request-scoped authorization, no network schema dereference, and exact multi-round request state.
Strict MCP Remote Tool: MCP 2026-07-28 modern discovery, stateless complete-JSON transport, exact local schema and server-identity pins, attempt-scoped authorization, and reconciliation-first lost-write behavior.
A2A Client and durable remote agent: Strict Agent Card and interface discovery, all eleven HTTP+JSON and JSON-RPC operations, both bounded SSE surfaces, attempt-scoped bearer authorization, local schema authority, explicit delivery semantics, and Unknown/no-redispatch recovery through PostgreSQL.
Durable A2A artifact storage: Direct no-resend task recovery, bounded terminal-part ingestion, immutable PostgreSQL metadata, private conditional object publication, authorization-before-lookup, and complete length and SHA-256 verification.
Architecture decisions: Draft RFCs and qualification scenarios that constrain implementation; drafts are not stable compatibility promises.

Public Alpha API reference

docs.rs publishes the exact stateknot 0.1.0-alpha.1 reference. When reviewing a change that has not been released, generate documentation from that exact checkout:

Shell

RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps --locked --open