The HITL Contract

The HITL contract. A GC can screenshot this page. It is the policy the Cognitive API enforces, not a programme of record.

Only Institute · PrimeSwarm
11 September 2026

Companion papers: We Sit in Front of the Model You Already Have · The Industry Wants a Write-Path Gate · Two Keys, Not a Cliché

Machine copy: GET /v1/hitl/contract on the Cognitive API (no auth).

---

House line. Statistical AI guesses. We sit in front of the write and leave a receipt.

This is the human-in-the-loop contract. It is fail-closed. It is not SOC 2. It is not ISO 42001. It is not Ory, Okta, or Entra.

---

What is always YELLOW

Write	Tier until a human binds	After bind
Send (POST /v1/send)	YELLOW. allowed: false. 64-character proof id. No SMTP.	Local spool .eml only. Transport local-spool.
File (POST /v1/file)	YELLOW. Same queue. Path is a basename, never a host path.	Local spool .file only.

Capability send:email or write:file means the agent may propose. It does not mean the agent may write. An agent JWT (primeswarm.agent) cannot resume a send or a file. A human (primeswarm.admin) must bind.

Replay of a spent proof id is RED.

What may be GREEN

Reads with a declared capability (arxiv, memory) may GREEN. Declared write:memory may GREEN. Observe-then-enforce is allowed on reads. Fail-open is not allowed on send or file. If the HITL plane cannot persist the queue, the propose is RED.

Two names on the receipt

A bound write names:

1. agent_id — the catalog agent that proposed (outbound-mailer, not a shared service account).
2. proposed_by — the JWT subject that queued it.
3. bound_by — the JWT subject of the human who resumed.

If the log only says the service account did it, the receipt is incomplete.

Not yet (Estate)

These are parked. Do not sell them as live.

• Per-agent credentials (stop sharing primeswarm.agent as the only agent role).
• Delegation tuples: user X authorized agent Y on tenant Z.
• A kill switch that revokes an agent everywhere, not only this proof.
• OpenTelemetry export into a customer SIEM.

Identity plane: sit in front of Ory, Okta, or Entra. Do not replace them.

How to bind

POST /v1/actions/resume
{ "proof_id": "<64 hex>", "approve": true | false }

Approve writes the spool and returns GREEN. Deny returns RED and writes nothing. The queue is reloaded from PRIMESWARM_HITL_DIR after process restart. A proof that existed before the restart is still YELLOW until a human binds.