{ "openapi": "3.1.0", "info": { "title": "OPERE bounded formation protocol", "version": "0.3.0", "description": "STATIC PROTOCOL REFERENCE ONLY. This Cloudflare Pages deployment serves public pages and an illustrative walkthrough; it hosts no OPERE API, inference, execution, or live operating state. Configure a separately hosted OPERE runtime and replace the placeholder server URL before using this contract.\n\nMachine-first Outcome and Observe entry paths for bounded coding and document/data work. The calling AI retains task ownership. ready != verified != caller accepted != release. Live private inference and restricted-container execution require an available configured runtime and operating worker; unavailable components remain explicit blockers, with no simulated or host-execution fallback. Local open Qwen3 candidates are development proof, not a quality guarantee. Single-host implementation, not production or universal-domain support. No finance or billing operations exist in v3." }, "servers": [ { "url": "https://YOUR-OPERE-HOST.example/api/v3", "description": "Placeholder: replace with your separately hosted OPERE runtime URL. No API runs on this Cloudflare Pages site." } ], "security": [ { "machineBearer": [] } ], "paths": { "/requests/lookup": { "post": { "operationId": "formationRequestReceipt", "summary": "Read the exact principal-scoped request receipt", "description": "Read-only lookup. The fingerprint is SHA-256 of the exact original compact serialized FormationRequest, preserving field order. No input sources or credential are echoed. A matching receipt establishes OPERE received the request, not that the AI accepted work or completed it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "idempotencyKey", "fingerprint" ], "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the exact UTF-8 content string." } } } } } }, "responses": { "200": { "description": "Exact receipt or no record for this principal.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "received" ], "properties": { "received": { "const": false } } }, { "type": "object", "additionalProperties": false, "required": [ "received", "environmentId", "receivedAt", "entry" ], "properties": { "received": { "const": true }, "environmentId": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time" }, "entry": { "enum": [ "outcome", "observe" ] } } } ] } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connection/check": { "post": { "operationId": "formationConnectionCheck", "summary": "Record a safe authenticated machine connection check", "description": "Accepts an empty JSON object. Overwrites one principal-scoped receipt and latest successful request metadata. No provisioning, inference, probe or work occurs; this is not runtime readiness or a worker heartbeat. A human inspection cookie cannot invoke this machine endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} } } } }, "responses": { "200": { "description": "Authentication checked and receipt recorded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "receipt" ], "properties": { "receipt": { "$ref": "#/components/schemas/ConnectionCheckReceipt" } } } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi": { "get": { "operationId": "formationOpenApi", "summary": "Public static v3 discovery", "security": [], "responses": { "200": { "description": "This discovery document; it grants no authority and makes no runtime availability assertion.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/runtime": { "get": { "operationId": "formationRuntime", "summary": "Public private-runtime health", "security": [], "description": "Checks inference metadata/digest, prepared image availability and recent worker heartbeat; cached for ten seconds. Public discovery never starts a container. Each environment separately requires a restricted-container readiness probe. Model health does not prove generation or artifact quality. Unavailable is reported in a normal 200 response.", "responses": { "200": { "description": "Current bounded runtime health, including unavailable components.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "runtime" ], "properties": { "runtime": { "$ref": "#/components/schemas/RuntimeHealth" } } } } } } } } }, "/environments": { "get": { "operationId": "formationList", "summary": "List up to 20 recent environments owned by this machine principal", "responses": { "200": { "description": "Recent authoritative state; no pagination cursor.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "environments" ], "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" }, "maxItems": 20 } } } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "formationRequest", "summary": "Request through Outcome or Observe", "description": "Requires environment.form and workspace.writable grants. Entry is outcome or observe on the wire. Direct and observed sources are combined and validated together. Effective lease is capped by the principal policy and identity expiry. Formation is asynchronous.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormationRequest" } } } }, "responses": { "202": { "description": "Request retained and formation queued; normally requested. Exact receipt replay can return an earlier snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "get": { "operationId": "formationGet", "summary": "Read the owned environment, artifacts, evidence and blockers", "responses": { "200": { "description": "Current state. Lease expiry may project expired with unavailable resources before cleanup is persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/observations": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "post": { "operationId": "formationObserve", "summary": "Replace authorized sources, advance context and queue formation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObservationMutation" } } } }, "responses": { "202": { "description": "Queued work; this response does not assert readiness, verification, caller acceptance or completed release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/actions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "post": { "operationId": "formationAction", "summary": "Begin caller-owned work or read context", "description": "Only begin_work and read_context are supported. Both are revision-guarded, recorded operations, admitted only in ready, working, verified or accepted with no queued job. No shell, arbitrary command, repository mutation or host execution is exposed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionMutation" } } } }, "responses": { "200": { "description": "begin_work sets working; read_context returns output and also records a new revision.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "environment" ], "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "output": { "$ref": "#/components/schemas/ContextOutput" } } } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/artifacts": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "post": { "operationId": "formationSubmit", "summary": "Retain a current-context candidate and queue independent checks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactInput" } } } }, "responses": { "202": { "description": "Queued work; this response does not assert readiness, verification, caller acceptance or completed release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "post": { "operationId": "formationVerify", "summary": "Queue fresh checks for the latest current artifact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionMutation" } } } }, "responses": { "202": { "description": "Queued work; this response does not assert readiness, verification, caller acceptance or completed release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/accept": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "post": { "operationId": "formationAccept", "summary": "Caller acknowledges the latest currently verified artifact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptMutation" } } } }, "responses": { "200": { "description": "Caller acceptance recorded. Requires verified state, current context, latest artifact ID/hash and passing nonstale verification; does not release resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "post": { "operationId": "formationRetry", "summary": "Retry formation from an explicitly retryable blocked state", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionMutation" } } } }, "responses": { "202": { "description": "Queued work; this response does not assert readiness, verification, caller acceptance or completed release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/release": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "post": { "operationId": "formationRelease", "summary": "Withdraw resources and queue isolated cleanup while retaining history", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionMutation" } } } }, "responses": { "202": { "description": "Queued work; this response does not assert readiness, verification, caller acceptance or completed release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/events": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } ], "get": { "operationId": "formationEvents", "summary": "Replay revision snapshots or follow a bounded SSE response", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Exclusive revision cursor; takes precedence over Last-Event-ID. Default 0." }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Last received revision, not the event's string id." } ], "responses": { "200": { "description": "JSON: at most 100 snapshots plus cursor. Accept text/event-stream for environment frames whose SSE id is revision and data is Event; reconnect after the last received revision. Streams are bounded by 25 seconds, 100 events, 1 MiB and backpressure; at most three per principal. In-stream errors use event: error with {code,message}. Identity and ownership are rechecked on polling.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "events", "cursor" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "maxItems": 100 }, "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected. Inspect error.code; do not retry changed input under the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "machineBearer": { "type": "http", "scheme": "bearer", "description": "Offline-issued, scoped, expiring/revocable machine identity. Authorization: Bearer . Cookies and human inspection codes are not machine authority. Ownership is scoped to tenant AND principal. No v3 self-service identity/grant endpoint." } }, "schemas": { "MachineRequestEvidence": { "type": "object", "additionalProperties": false, "required": [ "at", "transport", "operation" ], "properties": { "at": { "type": "string", "format": "date-time" }, "transport": { "type": "string", "enum": [ "http", "mcp" ] }, "operation": { "type": "string", "minLength": 1, "maxLength": 64, "description": "At most 64 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." } } }, "ConnectionCheckReceipt": { "type": "object", "additionalProperties": false, "required": [ "id", "at", "transport", "operation", "authenticated", "provisioning" ], "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "transport": { "type": "string", "enum": [ "http", "mcp" ] }, "operation": { "const": "connection_check" }, "authenticated": { "const": true }, "provisioning": { "const": false } } }, "MachineEvidence": { "type": "object", "additionalProperties": false, "required": [], "properties": { "latestSuccessfulRequest": { "$ref": "#/components/schemas/MachineRequestEvidence" }, "connectionCheck": { "$ref": "#/components/schemas/ConnectionCheckReceipt" } } }, "FormationRequest": { "type": "object", "additionalProperties": false, "required": [ "entry", "idempotencyKey" ], "properties": { "entry": { "type": "string", "enum": [ "outcome", "observe" ], "description": "User-facing labels are exactly Outcome and Observe." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." }, "observation": { "$ref": "#/components/schemas/Observation" }, "sources": { "$ref": "#/components/schemas/Sources" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Principal/operation-scoped retry key. Exact serialized input replays the original snapshot; changed input with this key returns 409 idempotency_conflict. Preserve body and field order for retries; GET current state after replay." }, "leaseSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "oneOf": [ { "properties": { "entry": { "const": "outcome" } }, "required": [ "outcome" ] }, { "properties": { "entry": { "const": "observe" } }, "required": [ "observation" ] } ], "description": "Unknown fields rejected. HTTP JSON body including encoding overhead is limited to 65536 bytes. Direct and observation sources combined: at most eight distinct IDs and 65536 content bytes; policy and inference budgets can be lower." }, "Source": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mediaType", "content" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "At most 256 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." }, "mediaType": { "type": "string", "enum": [ "text/plain", "text/markdown", "application/json", "text/javascript" ] }, "content": { "type": "string", "maxLength": 65536, "description": "At most 65536 UTF-8 bytes; may be empty; unsafe control and directional formatting characters are rejected." } } }, "Sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" }, "maxItems": 8, "description": "Distinct IDs; at most 65536 combined content bytes. Executor constraints are narrower than intake media types. Caller must not supply hashes." }, "SourceVersion": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mediaType", "content", "hash" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "text/plain", "text/markdown", "application/json", "text/javascript" ] }, "content": { "type": "string" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the exact UTF-8 content string." } } }, "Observation": { "type": "object", "additionalProperties": false, "required": [ "summary", "sources" ], "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." }, "sources": { "$ref": "#/components/schemas/Sources" } } }, "RevisionMutation": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "idempotencyKey" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Latest environment revision, including worker transitions. Conflict returns 409; refresh state and reassess a new mutation." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Principal/operation-scoped retry key. Exact serialized input replays the original snapshot; changed input with this key returns 409 idempotency_conflict. Preserve body and field order for retries; GET current state after replay." } } }, "ObservationMutation": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "idempotencyKey", "observation" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Latest environment revision, including worker transitions. Conflict returns 409; refresh state and reassess a new mutation." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Principal/operation-scoped retry key. Exact serialized input replays the original snapshot; changed input with this key returns 409 idempotency_conflict. Preserve body and field order for retries; GET current state after replay." }, "observation": { "$ref": "#/components/schemas/Observation" } }, "description": "Replaces all sources, increments contextVersion even for identical input under a new key, stales all prior artifacts/checks and clears acceptance. Retains original entry and requestedOutcome; queues fresh inference." }, "ActionMutation": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "idempotencyKey", "operation" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Latest environment revision, including worker transitions. Conflict returns 409; refresh state and reassess a new mutation." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Principal/operation-scoped retry key. Exact serialized input replays the original snapshot; changed input with this key returns 409 idempotency_conflict. Preserve body and field order for retries; GET current state after replay." }, "operation": { "type": "string", "enum": [ "begin_work", "read_context" ] } } }, "ArtifactInput": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "idempotencyKey", "name", "mediaType", "content", "contextVersion" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Latest environment revision, including worker transitions. Conflict returns 409; refresh state and reassess a new mutation." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Principal/operation-scoped retry key. Exact serialized input replays the original snapshot; changed input with this key returns 409 idempotency_conflict. Preserve body and field order for retries; GET current state after replay." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "At most 256 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." }, "mediaType": { "type": "string", "enum": [ "application/json", "text/markdown", "text/plain" ] }, "content": { "type": "string", "maxLength": 65536, "description": "At most 65536 UTF-8 bytes; may be empty; unsafe control and directional formatting characters are rejected." }, "contextVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "description": "Requires ready/working/verified/accepted, no pending job and current contextVersion. New submission stales prior artifacts/checks and clears acceptance. At most 128 retained artifacts, cumulatively at most the smaller of the principal byte grant and 128 KiB. Snapshot size is also bounded to 448 KiB. Current executors verify only application/json: content must serialize CodingCandidate or DocumentCandidate for the admitted spec domain. Text intake alone does not imply verifiability." }, "CodingCandidate": { "type": "object", "additionalProperties": false, "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "path", "content" ], "properties": { "path": { "type": "string", "const": "src/invoice.js" }, "content": { "type": "string", "maxLength": 65536, "description": "At most 65536 UTF-8 bytes; may be empty; unsafe control and directional formatting characters are rejected." } } }, "minItems": 1, "maxItems": 1 } }, "description": "Payload serialized into ArtifactInput.content, not a top-level submission body. Exactly one existing source replacement beginning with export function calculateTotal(items) {. Context must contain only invoice-source named src/invoice.js with text/javascript media type. No added paths or tests. Scope, patch shape, six fixed and twelve fresh private arithmetic regressions are checked in the restricted container; passing is not general software correctness." }, "DocumentCandidate": { "type": "object", "additionalProperties": false, "required": [ "report", "facts" ], "properties": { "report": { "type": "string" }, "facts": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentFact" } } }, "description": "Payload serialized into ArtifactInput.content. Context sources must be JSON {facts:{key:scalar},items?:[{quantity,unitPrice}]}, with at most 32 fact keys and 256 items per source; source IDs match [a-zA-Z0-9_-]{1,64}. Every source fact and optional derived.total must occur exactly once, without extras. report must exactly equal the trusted renderDocumentReport output: Source report heading, then sorted JSON-valued lines with full source-hash citations. See formation-protocol.md for source bounds and exact rendering. This is not free-form document verification." }, "DocumentFact": { "type": "object", "additionalProperties": false, "required": [ "key", "value", "sourceId", "sourceHash" ], "properties": { "key": { "type": "string" }, "value": { "type": [ "string", "number", "boolean", "null" ] }, "sourceId": { "type": "string" }, "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the exact UTF-8 content string." } } }, "AcceptMutation": { "type": "object", "additionalProperties": false, "required": [ "expectedRevision", "idempotencyKey", "artifactId", "contextVersion" ], "properties": { "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Latest environment revision, including worker transitions. Conflict returns 409; refresh state and reassess a new mutation." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Principal/operation-scoped retry key. Exact serialized input replays the original snapshot; changed input with this key returns 409 idempotency_conflict. Preserve body and field order for retries; GET current state after replay." }, "artifactId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "At most 128 UTF-8 bytes; must contain non-whitespace; unsafe control and directional formatting characters are rejected." }, "contextVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } }, "ContextOutput": { "type": "object", "additionalProperties": false, "required": [ "contextVersion", "sources", "outcome" ], "properties": { "contextVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceVersion" } }, "outcome": { "type": "string" }, "observation": { "type": "string" } } }, "EnvironmentResponse": { "type": "object", "additionalProperties": false, "required": [ "environment" ], "properties": { "environment": { "$ref": "#/components/schemas/Environment" } } }, "Environment": { "type": "object", "additionalProperties": false, "required": [ "id", "tenantId", "principalId", "revision", "status", "entry", "outcome", "contextVersion", "sources", "resources", "artifacts", "verifications", "intelligence", "usage", "blockers", "createdAt", "updatedAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "principalId": { "type": "string" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "requested", "reasoning", "preparing", "ready", "working", "verifying", "verified", "accepted", "blocked", "releasing", "released", "expired" ] }, "entry": { "type": "string", "enum": [ "outcome", "observe" ] }, "requestedOutcome": { "type": "string" }, "outcome": { "type": "string" }, "observation": { "type": "string" }, "contextVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceVersion" } }, "spec": { "$ref": "#/components/schemas/EnvironmentSpec" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } }, "verifications": { "type": "array", "items": { "$ref": "#/components/schemas/Verification" } }, "intelligence": { "type": "array", "items": { "$ref": "#/components/schemas/IntelligenceRecord" } }, "usage": { "$ref": "#/components/schemas/ResourceUsage" }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/Blocker" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "acceptedArtifactId": { "type": "string" }, "acceptedAt": { "type": "string", "format": "date-time" }, "job": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "contextVersion" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "formation", "verification", "release" ] }, "artifactId": { "type": "string" }, "contextVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "claimedBy": { "type": "string" }, "claimExpiresAt": { "type": "string", "format": "date-time" } } } } }, "EnvironmentSpec": { "type": "object", "additionalProperties": false, "required": [ "domain", "outcome", "summary", "conditions", "checks", "missingInformation" ], "properties": { "domain": { "type": "string", "enum": [ "coding", "document" ], "description": "coding: invoice-source/src/invoice.js calculateTotal(items) only. document: supported scalar JSON facts and optional invoice totals, rendered with hash citations. Neither is a general-purpose domain executor." }, "outcome": { "type": "string" }, "summary": { "type": "string" }, "conditions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "capability", "reason", "sourceIds" ], "properties": { "capability": { "type": "string", "enum": [ "workspace.isolated", "runtime.node", "sources.read", "artifact.write" ] }, "reason": { "type": "string" }, "sourceIds": { "type": "array", "items": { "type": "string" } } } } }, "checks": { "type": "array", "items": { "type": "string" } }, "missingInformation": { "type": "array", "items": { "type": "string" } } } }, "Resource": { "type": "object", "additionalProperties": false, "required": [ "id", "capability", "detail", "available", "expiresAt" ], "properties": { "id": { "type": "string" }, "capability": { "type": "string" }, "detail": { "type": "string" }, "available": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "Artifact": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mediaType", "content", "hash", "contextVersion", "createdAt", "stale" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "application/json", "text/markdown", "text/plain" ] }, "content": { "type": "string" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the exact UTF-8 content string." }, "contextVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } } }, "Verification": { "type": "object", "additionalProperties": false, "required": [ "id", "artifactId", "artifactHash", "contextVersion", "passed", "checks", "executionMs", "at", "stale" ], "properties": { "id": { "type": "string" }, "artifactId": { "type": "string" }, "artifactHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the exact UTF-8 content string." }, "contextVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "passed": { "type": "boolean" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationCheck" } }, "executionMs": { "type": "number", "minimum": 0 }, "at": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } } }, "VerificationCheck": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "passed", "detail" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "passed": { "type": "boolean" }, "detail": { "type": "string" } } }, "IntelligenceRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "role", "model", "digest", "mode", "inputTokens", "outputTokens", "elapsedMs", "at" ], "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "interpretation", "reasoning", "escalation" ] }, "model": { "type": "string" }, "digest": { "type": "string" }, "mode": { "type": "string", "const": "live" }, "inputTokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "Provider-reported count, or null when unknown; never an estimated zero." }, "outputTokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "Provider-reported count, or null when unknown; never an estimated zero." }, "elapsedMs": { "type": "number", "minimum": 0 }, "at": { "type": "string", "format": "date-time" } } }, "ResourceUsage": { "type": "object", "additionalProperties": false, "required": [ "inferenceCalls", "inputTokens", "outputTokens", "inferenceMs", "executionMs", "operations", "artifactBytes" ], "properties": { "inferenceCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inputTokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "Provider-reported count, or null when unknown; never an estimated zero." }, "outputTokens": { "type": [ "integer", "null" ], "minimum": 0, "description": "Provider-reported count, or null when unknown; never an estimated zero." }, "inferenceMs": { "type": "number", "minimum": 0 }, "executionMs": { "type": "number", "minimum": 0 }, "operations": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "artifactBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "Blocker": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } }, "RuntimeHealth": { "type": "object", "additionalProperties": false, "required": [ "status", "inference", "executor" ], "properties": { "status": { "type": "string", "enum": [ "ready", "unavailable" ] }, "inference": { "type": "object", "additionalProperties": false, "required": [ "status", "model", "detail" ], "properties": { "status": { "type": "string", "enum": [ "ready", "unavailable" ] }, "model": { "type": "string" }, "digest": { "type": "string" }, "detail": { "type": "string" } } }, "executor": { "type": "object", "additionalProperties": false, "required": [ "status", "image", "detail" ], "properties": { "status": { "type": "string", "enum": [ "ready", "unavailable" ] }, "image": { "type": "string" }, "detail": { "type": "string" } } }, "worker": { "type": "object", "additionalProperties": false, "required": [ "status", "detail" ], "properties": { "status": { "type": "string", "enum": [ "ready", "unavailable" ] }, "lastSeenAt": { "type": "string", "format": "date-time" }, "detail": { "type": "string" } } } } }, "Event": { "type": "object", "additionalProperties": false, "required": [ "id", "environmentId", "tenantId", "principalId", "revision", "type", "at", "state" ], "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "tenantId": { "type": "string" }, "principalId": { "type": "string" }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "state": { "$ref": "#/components/schemas/Environment" } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }