Expose durable Agents through one service boundary.

Freeze the public contract

Exact deployments

The startup registry pins one descriptor and compiled Graph per exact Agent identity. Duplicate versions, schema disagreement, and runtime deployment drift fail closed.

Authorization first

A mandatory authorizer evaluates submission, read, and cancel before deployment or durable target existence is disclosed. The caller must come from an already verified token or mTLS identity.

Durable ingress

A tenant-scoped submission key converges lost acknowledgements on the original Run. Changed logical content is a conflict, not a second Run.

Two-phase cancellation

The service commits intent with stable caller-retained IDs. Workers stop new dispatch; lifecycle confirms the terminal state only from sufficient usage and external-effect evidence.

Build one immutable startup snapshot

Register every Graph, reducer, node, typed schema, admission schema, and service-control schema before constructing the facade. Submission never runs model or Tool code inline.

register_standard_agent_service_control_event_schema(&mut schema_builder)?;

let executable = executable_builder.build()?;
let mut deployments = AgentServiceRegistryBuilder::new();
deployments.register(Arc::new(provider_native_definition.clone()))?;

let service = AgentServiceV1::new(
    store.clone(),
    executable,
    deployments.build(),
    Arc::new(authorizer),
)?;

Submit, inspect, and cancel by durable identity

let admitted = service
    .submit(caller.clone(), &submission_key, &agent_identity, request)
    .await?;
let run_id = admitted.snapshot().provenance().run_id();

let snapshot = service.load(caller.clone(), run_id).await?;

// Persist once, then reuse this exact pair after timeout.
let ids = AgentCancellationIds::generate();
let cancellation = service
    .request_cancellation(caller, run_id, ids)
    .await?;

After a timeout, retry submission with the same tenant, Agent identity, key, and logical request. Retry cancellation with the same run_id and exact AgentCancellationIds. New cancellation IDs represent a competing request and must not be hidden as idempotent success.

Persist public-safe control evidence

The cancellation journal binds the exact caller-retained event/failure IDs and an authoritative PostgreSQL timestamp. Its event data stores admission, policy, and decision digests plus the stable failure ID. Caller input, principal text, policy payloads, credentials, and failure messages are deliberately absent. Inspect the published schema.

Keep transport responsibilities outside

• Verify TLS, tokens, or mTLS before constructing the caller.
• Derive tenant and principal from verified credentials, never request-body identity claims.
• Persist submission and cancellation IDs before calling the facade.
• Add bounded public errors, rate limits, overload control, tracing, scheduler/worker roles, graceful drain, and backup/restore procedures.
• Do not place a remote policy request inside a database transaction; consume retained policy evidence instead.

Run the PostgreSQL proof

STATEKNOT_REQUIRE_POSTGRES_TESTS=1 \
cargo test -p stateknot-runtime --test postgres \
  agent_service_authorizes_submits_recovers_and_cancels_without_redispatch \
  --locked

The focused test proves authorization-first missing-resource handling, exact submission recovery, key-based reads, cancellation commit/retry/conflict, and zero model or Tool dispatch. Read the complete integration contract before exposing a network API.