Submit once. Recover the same durable Agent run.

Commit the key with the run

Authenticate the tenant, freeze policy and deployment inputs, then call submit. The key mapping and a new atomic admission commit in one transaction, so no successful mapping can point at a half-created run.

let runs = DurableAgentRuns::new(store.clone(), executable_registry)?;
let key = AgentSubmissionKey::generate();

let request = DurableAgentAdmissionRequest::new(
    tenant_id.clone(),
    AgentRunIds::generate(),
    agent_descriptor,
    agent_request,
    evaluated_budget_layers,
    graph_reference,
    admission_authority,
    initial_state,
)?;

let admitted = runs.submit(&key, request).await?;
let run_id = admitted.snapshot().provenance().run_id();

A generated key contains 148 random bits. External keys must use 16–128 bytes from [A-Za-z0-9._~-] and should provide at least 128 bits of unpredictability. PostgreSQL stores only a tenant-scoped digest; raw keys are absent from durable rows and redacted from Debug.

Retry logical content, not candidate identities

After an ambiguous response, reuse the key and every immutable logical input: Agent, request, budgets, graph, authorization evidence, and initial state. The new attempt may allocate fresh run/thread/invocation/event/checkpoint IDs; the original selected run still wins.

// Rebuild the same logical content. Candidate IDs may be fresh.
let retry = DurableAgentAdmissionRequest::new(
    tenant_id.clone(),
    AgentRunIds::generate(),
    retained_agent_descriptor,
    retained_agent_request,
    retained_budget_layers,
    retained_graph_reference,
    retained_authority,
    retained_initial_state,
)?;

let resolved = runs.submit(&key, retry).await?;
assert_eq!(resolved.snapshot().provenance().run_id(), original_run_id);

let current = runs.load_by_key(&tenant_id, &key).await?;

Changed logical content returns a conflict. A second key for the same run also conflicts. After local deployment revalidation, durable key evidence precedes new database-time and initial-checkpoint admission checks. A valid lost-ACK retry can therefore resolve after its original deadline; missing executable code still fails closed.

Poll a closed public snapshot

Observation identity

Use (run_id, revision). Revision is monotonic; equal revisions represent the same lifecycle observation.

Nonterminal state

active, waiting, and cancellation_requested require an explicit outcome: null.

Terminal state

succeeded returns a schema- and budget-verified AgentResult; failed and cancelled return a public-safe failure, completion time, and cumulative usage.

Quarantine

A quarantined run remains observable but is never silently represented as runnable work.

The response excludes request input, authorization evidence, graph state, leases, scheduler internals, and private diagnostics. Every load rechecks the immutable deployment, schemas, admission anchors, lifecycle, provenance, output, and accounting before returning it.

Authorize before every lookup

Tenant IDs, run IDs, and submission keys are correlation identities—not access credentials. Authenticate and authorize the caller before load or load_by_key, keep PostgreSQL credentials inside the trusted service, and translate not-found/conflict responses without leaking cross-tenant existence.

Roll out migration 16 without weakening retries

Apply migrations with a separate role, require exact checksum and object verification at startup, then deploy the frozen executable registry before enabling traffic. Never delete a key mapping while a client may retry it; deletion would permit a second run. Future retention must remove run, admission, and key evidence together after the retry guarantee expires.

PostgreSQL 16/17 qualification covers a populated v15→v16 upgrade, 24-way convergence, changed-content and second-key conflicts, raw-key non-persistence, tamper rejection, late transactional rollback, and verified succeeded, failed, and confirmed-cancelled results through the public facade. Read the complete integration contract before adopting this public-preview API.