{ "openapi": "3.1.0", "info": { "title": "QilbeeDB Platform API", "version": "0.13.0", "description": "Durable identity, scoped memory with model-bound semantic vector retrieval, evidence-driven procedural learning and learned-tool development receipts for AI agents. Scoped experience receipts record attempts and observations without automatic qualification." }, "servers": [ { "url": "http://localhost:7474", "description": "Local Docker or development server" } ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "tags": [ { "name": "Platform" }, { "name": "Identity" }, { "name": "Memory" }, { "name": "Learning", "description": "Administrative contracts, immutable candidates, evaluation admission and compatible selection." }, { "name": "Tools", "description": "Immutable artifacts, executor profiles and durable development/repair reports from external workers." }, { "name": "Experiences", "description": "Scoped attempt registrations and immutable observations. No execution dispatch or automatic procedure qualification." }, { "name": "Administration", "description": "Installation master and explicitly delegated global administration." }, { "name": "Human login", "description": "Provisioned human accounts and short-lived administrative sessions." }, { "name": "Administration directory", "description": "Bounded enumeration within the authenticated administrative authority." } ], "paths": { "/health": { "get": { "operationId": "health", "summary": "Read process health", "description": "", "tags": [ "Platform" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/openapi.json": { "get": { "operationId": "openapi", "summary": "Download this API contract", "tags": [ "Platform" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/identity": { "get": { "operationId": "whoAmI", "summary": "Inspect the current durable credential", "description": "", "tags": [ "Identity" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialResponse" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/credentials": { "post": { "operationId": "issueCredential", "summary": "Issue a credential in the authenticated tenant", "description": "Requires credential_admin. Secret delivery is one-time and not idempotent. Use exact grants or an explicit company_scopes_v1 scope_policy. A company policy allows external IDs within its selectors, requires grants=[] and excludes credential_admin; capabilities and credential lifetime remain explicit.", "tags": [ "Identity" ], "responses": { "201": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedCredential" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueRequest" } } } } }, "get": { "operationId": "listTenantCredentials", "summary": "List tenant credentials", "description": "Return sanitized metadata, including revoked or disabled entries. Scope is selected before the ordered-key seek. Requires credential_admin in the authenticated tenant. Default 25, maximum 100 records; response at most 4 MiB (reduce limit on 400). Pages are live forward-only key traversal, not a snapshot. Concurrent insertions before the cursor require a new traversal. No full total is claimed.", "tags": [ "Administration directory" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryTenantCredentialsResponse" } } } } }, "parameters": [ { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ] } }, "/api/v1/credentials/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "inspectCredential", "summary": "Inspect sanitized credential history", "description": "Requires credential_admin in the same tenant.", "tags": [ "Identity" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/credentials/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "rotateCredential", "summary": "Rotate a credential at an expected revision", "description": "Requires credential_admin in the same tenant. Rotation never revives a revoked credential.", "tags": [ "Identity" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedCredential" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionRequest" } } } } } }, "/api/v1/credentials/{id}/revoke": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "revokeCredential", "summary": "Revoke a credential at an expected revision", "description": "Requires credential_admin in the same tenant. Rotation never revives a revoked credential.", "tags": [ "Identity" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionRequest" } } } } } }, "/api/v1/memory/commands": { "post": { "operationId": "applyMemoryCommand", "summary": "Atomically create, update or delete a scoped record", "description": "Requires memory_write and an exact grant. Same key and normalized command return the original receipt, including after deletion. Changed commands conflict. No implicit retention quota.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCommand" } } } } } }, "/api/v1/memory/records/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." } }, { "name": "mission_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." } }, { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." } }, { "name": "visibility", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Visibility" } } ], "get": { "operationId": "readMemoryRecord", "summary": "Read a current unexpired record in the authorized scope", "description": "Requires memory_read and an exact grant. Omit mission_id for missionless memory. Tenant and private subject come from the credential.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/memory/query": { "post": { "operationId": "queryMemory", "summary": "Query current scoped records with explicit continuation", "description": "Requires memory_read. Case-insensitive substring over primary/secondary/context; exact type/tag filters. UUID ordering, 1,000 results and 10,000 scanned entries per request. Live pagination is not a snapshot or changes feed. No synthetic similarity scores. Optional filter.scan_limit bounds candidate work independently of returned results; empty pages can still have a next_after cursor.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } } } }, "/api/v1/learning/policies": { "post": { "operationId": "registerLearningPolicy", "summary": "Register an immutable administrative policy", "description": "Requires policy_admin. Identical retries preserve the original entry. Changed definitions conflict.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyEntryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningPolicyRequest" } } } } } }, "/api/v1/learning/policies/{id}": { "get": { "operationId": "getLearningPolicy", "summary": "Read an administrative policy", "description": "Requires policy_admin within the authenticated tenant.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyEntryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/api/v1/learning/contexts": { "post": { "operationId": "registerLearningContext", "summary": "Register an exact evaluation context", "description": "Requires policy_admin. Context versions are immutable.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextEntryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningContextRequest" } } } } } }, "/api/v1/learning/contexts/{id}": { "get": { "operationId": "getLearningContext", "summary": "Read an evaluation context", "description": "Requires policy_admin within the authenticated tenant.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextEntryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/api/v1/learning/proposals": { "post": { "operationId": "proposeProcedure", "summary": "Register a candidate bound to policy and context", "description": "Requires procedure_propose and an exact scope grant. Returns the original candidate receipt on identical replay.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningProposalRequest" } } } } } }, "/api/v1/learning/procedures/read": { "post": { "operationId": "readProcedure", "summary": "Read the current procedure and original receipt", "description": "Requires memory_read and an exact scope grant.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcedureResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningReadRequest" } } } } } }, "/api/v1/learning/evaluations": { "post": { "operationId": "admitEvaluation", "summary": "Submit a paired evaluation or explicit uncertain outcome", "description": "Requires procedure_evaluate, an exact grant and the policy evaluator subject. HTTP 200 confirms durable admission; inspect outcome to distinguish accepted evidence from rejection or uncertainty.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdmissionResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningEvaluationRequest" } } } } } }, "/api/v1/learning/evaluations/read": { "post": { "operationId": "readEvaluationAdmission", "summary": "Read the original admission receipt", "description": "Requires memory_read and an exact scope grant.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdmissionResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningReceiptRequest" } } } } } }, "/api/v1/learning/select": { "post": { "operationId": "selectProcedure", "summary": "Select a qualified compatible procedure or exact baseline", "description": "Requires memory_read and an exact scope grant. Budget counts UTF-8 instruction bytes, not tokens. Context and policy identities must match qualification exactly.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSelectionResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSelectRequest" } } } } } }, "/": { "get": { "operationId": "openApiReference", "summary": "Open the browser API reference", "security": [], "responses": { "307": { "description": "Open the browser API reference", "headers": { "Location": { "schema": { "type": "string", "const": "/docs" } } } } } } }, "/docs": { "get": { "operationId": "getApiReference", "summary": "Read the browser API reference", "security": [], "responses": { "200": { "description": "Read the browser API reference", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/docs/reference.js": { "get": { "operationId": "getApiReferenceScript", "summary": "Load the same-origin API reference script", "security": [], "responses": { "200": { "description": "Load the same-origin API reference script", "content": { "application/javascript": { "schema": { "type": "string" } } } } } } }, "/api/v1/tools/artifacts": { "post": { "operationId": "registerToolArtifact", "summary": "Register an immutable artifact", "description": "Requires tool_develop and exact scope. Stores source without executing or approving it.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolArtifactResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolArtifactRequest" } } } } } }, "/api/v1/tools/artifacts/read": { "post": { "operationId": "readToolArtifact", "summary": "Read an exact artifact", "description": "Requires tool_read and exact scope. Verifies stored digests.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolArtifactResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolArtifactRead" } } } } } }, "/api/v1/tools/executors": { "post": { "operationId": "registerToolExecutor", "summary": "Register an external executor profile", "description": "Requires tool_admin. Immutable administrative declaration, not sandbox attestation.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolExecutorResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolExecutorRequest" } } } } } }, "/api/v1/tools/executors/{id}": { "get": { "operationId": "readToolExecutor", "summary": "Read an external executor profile", "description": "Requires tool_admin in the profile tenant.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolExecutorResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." } } ] } }, "/api/v1/tools/development/requests": { "post": { "operationId": "createToolDevelopment", "summary": "Record development or repair intent", "description": "Requires tool_develop and exact scope. Returns original receipt. Does not dispatch work.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDevelopmentReceiptResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDevelopmentCreate" } } } } } }, "/api/v1/tools/development/read": { "post": { "operationId": "readToolDevelopment", "summary": "Read current development state", "description": "Requires tool_read and exact scope. Unknown accounting remains null.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDevelopmentResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDevelopmentRead" } } } } } }, "/api/v1/tools/development/commands": { "post": { "operationId": "recordToolDevelopmentEvent", "summary": "Report a worker outcome or request cancellation", "description": "Requires tool_report plus bound executor subject for report, or tool_develop plus requesting subject for cancellation; exact scope required. Revision checked, immutable event retries. 200 does not imply development success or publication.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEventResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCommandRequest" } } } } } }, "/api/v1/tools/development/events/read": { "post": { "operationId": "readToolDevelopmentEvent", "summary": "Read an original development event", "description": "Requires tool_read and exact scope. Returns the original snapshot, which can differ from current state.", "tags": [ "Tools" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEventResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEventRead" } } } } } }, "/api/v1/memory/embeddings": { "post": { "operationId": "attachMemoryEmbedding", "summary": "Attach a model-bound vector to an exact memory revision", "description": "Requires memory_write and exact scope. Embedding plus original receipt commits atomically. Source changes invalidate eligibility. Vectors are generated externally; anonymous legacy embeddings are not assigned a model. Vector requests have a 2 MiB JSON body cap and support up to 32768 dimensions, subject to the configured operator ceiling.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Invalid fields, vectors or unsupported contract version; embedding_dimension_limit for zero or excessive operator dimensions.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 2,097,152 bytes (2 MiB), including every JSON field and formatting", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingCommandRequest" } } } } } }, "/api/v1/memory/search": { "post": { "operationId": "searchMemorySemantic", "summary": "Rank memory by cosine similarity", "description": "Requires memory_read and exact scope. Exact cosine ranking of a bounded scan page. Check exhaustive and next_after before interpreting results as global top-k; only the exact model space and current visible source revisions qualify. Query embeddings are supplied by the client. Reads a single request-local storage snapshot without holding the memory writer lock. Score remains cosine, preserving the 0.4.0 contract. Vector requests have a 2 MiB JSON body cap and support up to 32768 dimensions, subject to the configured operator ceiling.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Qilbee-Ranking-Version": { "description": "Immutable cosine ranking version; JSON envelope remains compatible with 0.4.0.", "schema": { "type": "string", "const": "cosine_exact_v1" } }, "X-Qilbee-Retrieval-Micros": { "description": "Server retrieval wall time in microseconds; excludes authorization, queueing, serialization, transport and embedding generation.", "schema": { "type": "integer", "minimum": 0 } }, "X-Qilbee-Candidate-Selection-Version": { "schema": { "type": "string", "const": "current_records_v1" }, "description": "Current-record candidate selection plan, independent of the ranking profile." }, "X-Qilbee-Scanned-Records": { "schema": { "type": "integer", "minimum": 0 }, "description": "Current candidates examined; this is the scan_limit work counter, including records without the selected embedding space." }, "X-Qilbee-Candidate-Index-Bytes": { "schema": { "type": "integer", "minimum": 0 }, "description": "Logical admitted candidate key/value bytes. Excludes lookahead, integrity indexes and dependencies." }, "X-Qilbee-Scanned-Bytes": { "schema": { "type": "integer", "minimum": 0 }, "description": "Serialized current records and selected-space bindings examined. Not physical I/O, response size or process memory." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version; embedding_dimension_limit for zero or excessive operator dimensions.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 2,097,152 bytes (2 MiB), including every JSON field and formatting", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticRequest" } } } } } }, "/api/v1/memory/search/lexical": { "post": { "operationId": "searchMemoryLexical", "summary": "Rank memory with BM25", "description": "Requires memory_read and an exact scope grant. One authorized snapshot provides current records and statistics. Check exhaustive before interpreting a corpus page as complete; separate BM25 page scores cannot be merged into a global ranking. No embeddings required. Ranking version: bm25_v1.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Qilbee-Candidate-Selection-Version": { "schema": { "type": "string", "const": "current_records_v1" }, "description": "Current-record candidate selection plan, independent of the ranking profile." }, "X-Qilbee-Scanned-Records": { "schema": { "type": "integer", "minimum": 0 }, "description": "Current candidates examined; this is the scan_limit work counter, including records without the selected embedding space." }, "X-Qilbee-Candidate-Index-Bytes": { "schema": { "type": "integer", "minimum": 0 }, "description": "Logical admitted candidate key/value bytes. Excludes lookahead, integrity indexes and dependencies." }, "X-Qilbee-Scanned-Bytes": { "schema": { "type": "integer", "minimum": 0 }, "description": "Serialized current records and selected-space bindings examined. Not physical I/O, response size or process memory." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LexicalResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version; retrieval_scan_limit for a zero or excessive operator scan-byte budget.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LexicalRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "mode": "lexical", "query": { "text": "ZX17 retry failure", "limit": 10, "scan_limit": 10000, "scan_bytes_limit": 8388608, "after": null, "episode_type": null, "tag": null } } } } } } }, "/api/v1/memory/search/hybrid": { "post": { "operationId": "searchMemoryHybrid", "summary": "Rank memory with experimental versioned hybrid fusion", "description": "Requires memory_read and an exact scope grant. One authorized snapshot provides current records and statistics. Check exhaustive before interpreting a corpus page as complete; separate BM25 page scores cannot be merged into a global ranking. Text and externally generated query vector are explicit. Pin weighted_rrf_v1 or weighted_rrf_v2; weights, method and candidate cap are server-owned. Inspect embedding_coverage and candidates_truncated. Raw channel scores, ranks, contributions and vector receipts explain each hit. Storage errors fail the entire request; missing vectors are reported, never silently labeled full hybrid coverage. Experimental: no held-out relevance gain is claimed. Vector requests have a 2 MiB JSON body cap and support up to 32768 dimensions, subject to the configured operator ceiling.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Qilbee-Candidate-Selection-Version": { "schema": { "type": "string", "const": "current_records_v1" }, "description": "Current-record candidate selection plan, independent of the ranking profile." }, "X-Qilbee-Scanned-Records": { "schema": { "type": "integer", "minimum": 0 }, "description": "Current candidates examined; this is the scan_limit work counter, including records without the selected embedding space." }, "X-Qilbee-Candidate-Index-Bytes": { "schema": { "type": "integer", "minimum": 0 }, "description": "Logical admitted candidate key/value bytes. Excludes lookahead, integrity indexes and dependencies." }, "X-Qilbee-Scanned-Bytes": { "schema": { "type": "integer", "minimum": 0 }, "description": "Serialized current records and selected-space bindings examined. Not physical I/O, response size or process memory." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version; embedding_dimension_limit for zero or excessive operator dimensions; retrieval_scan_limit for a zero or excessive operator scan-byte budget.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 2,097,152 bytes (2 MiB), including every JSON field and formatting", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "mode": "hybrid", "query": { "text": "ZX17 retry failure", "limit": 10, "scan_limit": 10000, "scan_bytes_limit": 8388608, "after": null, "episode_type": null, "tag": null, "space": { "provider": "fixture", "model": "fixture-embedding", "revision": "v1", "dimensions": 3 }, "vector": [ 1.0, 0.0, 0.0 ], "ranking_version": "weighted_rrf_v1", "min_score": 0.0 } } } } } } }, "/api/v1/memory/ranking-profiles": { "get": { "operationId": "listRankingProfiles", "summary": "Discover immutable server ranking profiles", "description": "Requires a current credential with memory_read. Returns only server-wide implementation metadata, not scope data, embedding inventories, tenant policy or production admission. No scope or query parameters are needed. The profiles are generated from the same definitions used during retrieval; an experimental profile is not a recommended default. Pin the full returned profile in an evaluation plan.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingCatalog" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/experiences": { "post": { "operationId": "createExperience", "summary": "Register an immutable attempt", "description": "Requires experience_write and exact scope. Resolves a tenant-registered context and optional same-scope parent event. A private attempt must name its own subject as reporter. Returns the original receipt on an identical same-subject retry. Does not start execution.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Receipt recorded or read successfully; inspect the outcome and unknown accounting fields.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceReceiptResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceCreateRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "request": { "id": "attempt-v1", "context_id": "context-v1", "reporter_subject_id": "observer", "accounting_unit": "test-credit-v1", "input": { "reference": "fixture:input", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "parent": null } } } } } } }, "/api/v1/experiences/read": { "post": { "operationId": "readExperience", "summary": "Read the current attempt state", "description": "Requires experience_read and exact scope. Returns current state; historical retries return original receipts instead.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Receipt recorded or read successfully; inspect the outcome and unknown accounting fields.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "attempt_id": "attempt-v1" } } } } } }, "/api/v1/experiences/events": { "post": { "operationId": "observeExperience", "summary": "Record an authenticated observation", "description": "Requires experience_report, exact scope and the immutable reporter subject. Atomically records an event and state transition. New events check revision; identical same-subject event retries return the original event. Terminal outcomes cannot change, but same-outcome observations may resolve late consumption. Missing or null usage means unknown, never zero. Reports do not promote procedures or prove external effects.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Receipt recorded or read successfully; inspect the outcome and unknown accounting fields.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceEventResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceObserveRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "attempt_id": "attempt-v1", "command": { "event_id": "observation-v1", "expected_revision": 1, "context_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "outcome": "unknown", "evidence": { "reference": "fixture:trace", "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, "cost_units": null, "latency_ms": null } } } } } } }, "/api/v1/experiences/events/read": { "post": { "operationId": "readExperienceEvent", "summary": "Read an immutable historical observation", "description": "Requires experience_read and exact scope. Reads the exact event ID, even after later events. No cursor or implicit latest-event behavior.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Receipt recorded or read successfully; inspect the outcome and unknown accounting fields.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceEventResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceEventReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "attempt_id": "attempt-v1", "event_id": "observation-v1" } } } } } }, "/api/v1/experiences/history": { "post": { "operationId": "readExperienceHistory", "summary": "Read bounded experience history", "description": "Requires experience_read. Preserve the cursor unchanged. Scans at most limit events in ID UTF-8 byte-length/byte order; filters out revisions after the first-page fence. Empty pages can have continuation. complete means the fenced history has been traversed; a full final page may require one empty continuation. This is a logical revision snapshot, not a retained RocksDB snapshot.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceHistoryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceHistoryRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "attempt_id": "attempt-v1", "query": { "limit": 32, "cursor": null } } } } } } }, "/api/v1/experiences/artifacts": { "post": { "operationId": "bindExperienceArtifact", "summary": "Bind an immutable tool artifact to an observation", "description": "Requires experience_report and tool_read for the same scope, and the bound reporter subject. Verifies stored artifact content and exact event identity. The role remains a reporter assertion, not verified execution. Immutable binding IDs and synchronous durability.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceArtifactResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceArtifactBindRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "attempt_id": "attempt-v1", "binding": { "id": "binding-v1", "event_id": "observation-v1", "artifact_id": "tool-v1", "artifact_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "role": "candidate" } } } } } } }, "/api/v1/experiences/artifacts/read": { "post": { "operationId": "readExperienceArtifact", "summary": "Read a verified artifact binding", "description": "Requires experience_read and tool_read for the same scope. Revalidates the immutable observation and stored artifact identity.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceArtifactResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceArtifactReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "attempt_id": "attempt-v1", "binding_id": "binding-v1" } } } } } }, "/api/v1/experiences/lineage": { "post": { "operationId": "readExperienceLineage", "summary": "Read pinned experience ancestry", "description": "Requires experience_read. Visits only exact parent events named by immutable receipts, from immediate parent toward the root, up to max_depth. Never substitutes the latest parent outcome. complete=false and next_parent identify a truncated traversal, not a missing or failed execution. This is recorded provenance, not causal or counterfactual proof.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceLineageResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceLineageRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "attempt_id": "attempt-v1", "max_depth": 16 } } } } } }, "/api/v1/experiences/export": { "post": { "operationId": "exportExperiences", "summary": "Export an exact observation cohort", "description": "Requires experience_read. One immutable event per distinct attempt, all sharing the supplied context digest and accounting unit. All-or-error: mismatched hashes/context/unit return 409, missing events 404, duplicate attempts or invalid bounds 400. Canonical attempt-ID byte order and server-owned method identity make the response repeatable. No live-state substitution, inference, promotion, corpus completeness or independent-evidence claim. Unknown reports keep totals null.", "tags": [ "Experiences" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceExportResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperienceExportRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "selection": { "context_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "accounting_unit": "test-credit-v1", "events": [ { "attempt_id": "attempt-v1", "event_id": "observation-v1", "event_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ] } } } } } } }, "/api/v1/memory/changes": { "post": { "operationId": "readMemoryChanges", "summary": "Read a durable scoped memory change feed", "description": "Requires memory_read. Journal entries commit atomically with memory mutations and newly attached embeddings. No memory content is copied. after is exclusive; through is an optional inclusive fence. complete is relative to that fence, not a closed stream. Persist next_cursor; preserve high_watermark as through while catching up. No historical backfill, expiry events or retention pruning in this release. Wrong-scope or ahead-of-journal cursors return 409.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryChangesResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryChangesRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "query": { "after": null, "through": null, "limit": 100 } } } } } } }, "/api/v1/memory/reviews": { "post": { "operationId": "reviewMemory", "summary": "Record an authorized revision-checked memory decision", "description": "Requires memory_review for the exact scope. Review is an authenticated assertion, not external fact verification. Rejection excludes current content before retrieval statistics. Each decision advances revision, invalidating old vectors. Content updates clear current review; history remains durable. Deleted records cannot be reviewed. Current-state and history routes return no payload. See the memory review guide for correction and retry semantics.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete review receipt or current metadata state.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReviewResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReviewRequest" }, "example": { "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "command": { "contract_version": 1, "idempotency_key": "review-case-42", "record_id": "00000000-0000-4000-8000-000000000042", "expected_revision": 1, "disposition": "rejected", "evidence_ref": "case://quality/42" } } } } } } }, "/api/v1/memory/reviews/state": { "post": { "operationId": "readMemoryReviewState", "summary": "Read current metadata even when ordinary serving excludes the memory", "description": "Requires memory_review for the exact scope. Review is an authenticated assertion, not external fact verification. Rejection excludes current content before retrieval statistics. Each decision advances revision, invalidating old vectors. Content updates clear current review; history remains durable. Deleted records cannot be reviewed. Current-state and history routes return no payload. See the memory review guide for correction and retry semantics.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete review receipt or current metadata state.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReviewStateResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "review_not_found: no record state in this authorized scope.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewNotFoundError" }, "example": { "contract_version": 1, "error": { "code": "review_not_found", "message": "The requested review state or revision was not found" } } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReviewStateRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "record_id": "00000000-0000-4000-8000-000000000042" } } } } } }, "/api/v1/memory/reviews/read": { "post": { "operationId": "readMemoryReview", "summary": "Read an immutable historical review receipt", "description": "Requires memory_review for the exact scope. Review is an authenticated assertion, not external fact verification. Rejection excludes current content before retrieval statistics. Each decision advances revision, invalidating old vectors. Content updates clear current review; history remains durable. Deleted records cannot be reviewed. Current-state and history routes return no payload. See the memory review guide for correction and retry semantics.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete review receipt or current metadata state.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReviewResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "review_not_found: the requested immutable review revision is absent in this authorized scope.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewNotFoundError" }, "example": { "contract_version": 1, "error": { "code": "review_not_found", "message": "The requested review state or revision was not found" } } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReviewReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "record_id": "00000000-0000-4000-8000-000000000042", "revision": 2 } } } } } }, "/api/v1/memory/eligibility": { "post": { "operationId": "explainMemoryEligibility", "summary": "Explain bounded transitive memory eligibility", "description": "Requires memory_review in the exact scope. Returns metadata only, including current root revision and the first invalidating dependency. Uses one request-local snapshot and time; fail-fast diagnostic is not exhaustive when eligible is false. At most eight dependency edges and 64 distinct source IDs are admissible per derived root. Shared dependency work limits also apply. No payloads, evidence references or vectors are returned.", "tags": [ "Memory" ], "responses": { "200": { "description": "Current eligibility and metadata-only first-failure explanation.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEligibilityResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReviewStateRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "record_id": "00000000-0000-4000-8000-000000000042" } } } } } }, "/api/v1/memory/checkpoints": { "post": { "operationId": "commitMemoryCheckpoint", "summary": "Save subject-owned monotonic consumer progress", "description": "Requires memory_read and memory_checkpoint in the exact scope. Subject comes from authentication. expected_revision zero creates missing progress; updates require the current revision. Cursors cannot regress, switch journals or exceed the current journal watermark. Original retry receipts may be older than current state. Checkpoint writes do not produce memory-change events. External effects and consumer leases are not part of this transaction.", "tags": [ "Memory" ], "responses": { "200": { "description": "Durable checkpoint receipt or current subject-owned progress.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCheckpointResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCheckpointRequest" }, "example": { "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "command": { "contract_version": 1, "idempotency_key": "context-cache-page-1", "consumer_id": "context-cache", "expected_revision": 0, "cursor": { "journal_id": "00000000-0000-4000-8000-000000000042", "sequence": 100 } } } } } } } }, "/api/v1/memory/checkpoints/read": { "post": { "operationId": "readMemoryCheckpoint", "summary": "Read current progress for this subject and consumer", "description": "Requires memory_read and memory_checkpoint in the exact scope. Subject comes from authentication. expected_revision zero creates missing progress; updates require the current revision. Cursors cannot regress, switch journals or exceed the current journal watermark. Original retry receipts may be older than current state. Checkpoint writes do not produce memory-change events. External effects and consumer leases are not part of this transaction.", "tags": [ "Memory" ], "responses": { "200": { "description": "Durable checkpoint receipt or current subject-owned progress.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCheckpointReadResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current checkpoint exists for this subject and consumer in the authorized scope.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointNotFoundError" }, "examples": { "checkpoint_not_found": { "value": { "contract_version": 1, "error": { "code": "checkpoint_not_found", "message": "No checkpoint exists for this subject and consumer in the authorized scope" } } } } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCheckpointReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "consumer_id": "context-cache" } } } } } }, "/api/v2/memory/changes": { "post": { "operationId": "verifiedMemoryChanges", "summary": "Read prefix-anchored memory changes", "description": "Requires memory_read. Validates complete version-2 cursors against the authorized scope history, including after divergent restore and sequence catch-up. The baseline bounds the verified suffix; older events are not backfilled. Limits 1–256. Fixed through fence, after exclusive. 409 requires reconciliation; no silent fallback to version 1.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedMemoryChangesResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The client cursor does not match current scoped history. Reconcile the scope, baseline and consumer state; changing an idempotency key is not a remedy.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedJournalConflictError" }, "examples": { "journal_history_conflict": { "value": { "contract_version": 1, "error": { "code": "journal_history_conflict", "message": "The cursor does not match the current scoped journal history; reconcile consumer state" } } } } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedMemoryChangesRequest" }, "example": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "query": { "after": null, "through": null, "limit": 100 } } } } } } }, "/api/v2/memory/changes/activate": { "post": { "operationId": "activateVerifiedJournal", "summary": "Establish a verified journal baseline", "description": "Requires both memory_read and memory_write. Idempotently returns the original baseline for this authorized scope; no event or memory is invented. Existing v1 events and receipts are preserved. Activation is atomic and survives restart, including for an empty scope. Read the v2 feed to obtain a current watermark after activation.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedJournalActivationResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedJournalActivationRequest" }, "example": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" } } } } } } }, "/api/v2/memory/checkpoints": { "post": { "operationId": "commitVerifiedMemoryCheckpoint", "summary": "Save verified consumer progress", "description": "Requires memory_read and memory_checkpoint. Subject-owned, monotonic anchored progress with revision AND checkpoint-digest compare-and-set. Initial revision is zero with null expected_checkpoint_digest. Copy later expectations from a current read. Historical retries return their original receipt. Cursor history is validated before new admission. v1 checkpoints remain independent.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedMemoryCheckpointResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Inspect error.code: reconcile journal history, use explicit recovery for intentional rewind, reread stale progress, or retry the original idempotent command.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedCheckpointConflictError" }, "examples": { "journal_history_conflict": { "value": { "contract_version": 1, "error": { "code": "journal_history_conflict", "message": "The cursor does not match the current scoped journal history; reconcile consumer state" } } }, "checkpoint_regression": { "value": { "contract_version": 1, "error": { "code": "checkpoint_regression", "message": "Ordinary checkpoint progress cannot move backward; explicit reconciliation is required" } } }, "revision_conflict": { "value": { "contract_version": 1, "error": { "code": "revision_conflict", "message": "The expected revision or authorizing credential changed" } } }, "idempotency_conflict": { "value": { "contract_version": 1, "error": { "code": "idempotency_conflict", "message": "The idempotency key was already used for a different command" } } } } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedMemoryCheckpointRequest" }, "example": { "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "command": { "contract_version": 2, "idempotency_key": "initial-checkpoint", "consumer_id": "cache", "expected_revision": 0, "expected_checkpoint_digest": null, "cursor": { "version": 2, "journal_id": "00000000-0000-0000-0000-000000000001", "generation": "00000000-0000-0000-0000-000000000002", "sequence": 0, "prefix_digest": "0000000000000000000000000000000000000000000000000000000000000000" } } } } } } } }, "/api/v2/memory/checkpoints/read": { "post": { "operationId": "readVerifiedMemoryCheckpoint", "summary": "Read current verified consumer progress", "description": "Requires memory_read and memory_checkpoint. Returns only this credential subject's current v2 checkpoint in the exact scope, validates stored integrity and journal history, or 404. Never imports an unanchored v1 checkpoint.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedMemoryCheckpointReadResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current checkpoint exists for this subject and consumer in the authorized scope.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointNotFoundError" }, "examples": { "checkpoint_not_found": { "value": { "contract_version": 1, "error": { "code": "checkpoint_not_found", "message": "No checkpoint exists for this subject and consumer in the authorized scope" } } } } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedMemoryCheckpointReadRequest" }, "example": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "consumer_id": "cache" } } } } } }, "/api/v2/memory/checkpoints/recover": { "post": { "operationId": "recoverVerifiedCheckpoint", "summary": "Record explicit consumer checkpoint recovery", "description": "Requires memory_read and memory_checkpoint. Replaces an existing subject-owned checkpoint using exact revision and digest expectations and a currently valid verified cursor. Can rewind only through this explicit recovery route. Stores immutable before/after evidence, current state and retry receipt atomically. Evidence is caller-declared, not externally verified; no external actions are undone. In feature previews that expose consumer diagnostics, an intrinsically intact, subject-owned checkpoint may be reconciled even when its prior cursor is incompatible with current history. Its exact revision and digest can be obtained from consumer diagnostics. This does not bypass checkpoint integrity or target-journal verification; the immutable recovery receipt retains the previous checkpoint.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedCheckpointRecoveryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Inspect error.code: recovery does not override history validation, current checkpoint comparison or idempotency. A missing current checkpoint uses revision_conflict.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedRecoveryConflictError" }, "examples": { "journal_history_conflict": { "value": { "contract_version": 1, "error": { "code": "journal_history_conflict", "message": "The cursor does not match the current scoped journal history; reconcile consumer state" } } }, "revision_conflict": { "value": { "contract_version": 1, "error": { "code": "revision_conflict", "message": "The expected revision or authorizing credential changed" } } }, "idempotency_conflict": { "value": { "contract_version": 1, "error": { "code": "idempotency_conflict", "message": "The idempotency key was already used for a different command" } } } } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedCheckpointRecoveryRequest" }, "example": { "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "command": { "contract_version": 2, "idempotency_key": "reconcile-1", "consumer_id": "cache", "expected_revision": 1, "expected_checkpoint_digest": "0000000000000000000000000000000000000000000000000000000000000000", "cursor": { "version": 2, "journal_id": "00000000-0000-0000-0000-000000000001", "generation": "00000000-0000-0000-0000-000000000002", "sequence": 0, "prefix_digest": "0000000000000000000000000000000000000000000000000000000000000000" }, "evidence_ref": "recovery://consumer/cache/rebuild-1" } } } } } } }, "/api/v2/memory/checkpoints/recoveries/read": { "post": { "operationId": "readVerifiedCheckpointRecovery", "summary": "Read immutable checkpoint recovery evidence", "description": "Requires memory_read and memory_checkpoint for the owner subject and scope. Look up a recovery receipt by consumer_id and resulting checkpoint revision. This is historical evidence, not current progress. Missing recovery revisions return 404.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete response; inspect coverage and immutable identities.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedCheckpointRecoveryResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No recovery receipt exists for this subject, consumer and resulting checkpoint revision.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryNotFoundError" }, "examples": { "recovery_not_found": { "value": { "contract_version": 1, "error": { "code": "recovery_not_found", "message": "No recovery receipt exists for this subject, consumer and revision" } } } } } } }, "409": { "description": "Expected revision, immutable request/event content, terminal outcome or context digest conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedCheckpointRecoveryReadRequest" }, "example": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "consumer_id": "cache", "revision": 2 } } } } } }, "/api/v2/memory/changes/audit": { "post": { "operationId": "auditMemoryJournal", "summary": "Audit a bounded anchored journal range", "description": "Requires memory_read. Checks the same scoped event digests and consecutive prefix links as the v2 feed but returns only range metadata and counts, without event or record identities. Limit 1–256. Continue with checked_through as after and preserve high_watermark as through. Complete covers only the requested range after the baseline; it is not a full-volume, legacy-history or external-evidence attestation. Inconsistency returns 500 with no partial page.", "tags": [ "Memory" ], "responses": { "200": { "description": "Coverage of the selected range only. Inactive anchoring is not evidence of an empty or verified database.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryJournalAuditResponse" }, "example": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "audit": { "baseline": null, "checked_after": null, "checked_through": null, "high_watermark": null, "active": false, "links_checked": 0, "complete": true } } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No current record in the authorized scope", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The client cursor does not match current scoped history. Reconcile the scope, baseline and consumer state; changing an idempotency key is not a remedy.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedJournalConflictError" }, "examples": { "journal_history_conflict": { "value": { "contract_version": 1, "error": { "code": "journal_history_conflict", "message": "The cursor does not match the current scoped journal history; reconcile consumer state" } } } } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedMemoryChangesRequest" }, "example": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "query": { "after": null, "through": null, "limit": 100 } } } } } } }, "/api/v1/learning/strategies": { "post": { "operationId": "proposeExperienceStrategy", "summary": "Register a strategy candidate from exact experience observations", "description": "Requires procedure_propose and experience_read for the exact scope. Validates 1-16 distinct immutable development observations and registers the strategy and procedure atomically. Does not admit evaluation evidence or activate a procedure. Extraction remains external.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCandidateResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Strategy, source observation, policy or context is missing in the authorized namespace.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed immutable candidate, conflicting procedure ID, or mismatched evidence/context digest.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCandidateRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "strategy": { "id": "receipt-recovery-v1", "policy_id": "policy-v1", "context_id": "context-v1", "instructions": "Read the operation receipt before deciding whether to retry.", "preconditions": [ "The operation provides a durable receipt lookup." ], "counterexamples": [ "A timeout alone does not establish that the operation failed." ], "extractor": { "provider": "external-provider", "model": "external-extractor", "model_revision": "model-v1", "prompt_revision": "extraction-v1", "evidence_ref": "trace://development/receipt-recovery" }, "selection": { "context_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "accounting_unit": "tokens", "events": [ { "attempt_id": "development-failure-1", "event_id": "observed-failure", "event_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ] } } } } } } } }, "/api/v1/learning/strategies/read": { "post": { "operationId": "readExperienceStrategy", "summary": "Read the original strategy evidence receipt", "description": "Requires memory_read and experience_read for the exact scope. Revalidates the immutable observation and procedure bindings. The receipt retains original candidate state after later qualification; read the procedure for current state.", "tags": [ "Learning" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCandidateResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Strategy, source observation, policy or context is missing in the authorized namespace.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed immutable candidate, conflicting procedure ID, or mismatched evidence/context digest.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyCandidateReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "strategy_id": "receipt-recovery-v1" } } } } } }, "/api/v2/memory/consumers/diagnose": { "post": { "operationId": "diagnoseMemoryConsumer", "summary": "Inspect subject-owned consumer progress and history compatibility", "description": "Requires memory_read and memory_checkpoint for the exact scope. Reads current progress, journal boundaries and an optional caller-held witness from one snapshot without advancing progress. Missing checkpoints return 200 with unknown pending positions; well-formed incompatible cursors are reported in statuses. Stored corruption returns 500 with no partial diagnostic. This bounded boundary check does not audit middle history or prove external effects. Retain an external witness to compare with restored history; restoring the witness alongside the database can hide lost work.", "tags": [ "Memory" ], "responses": { "200": { "description": "Scoped snapshot diagnostic; inspect checkpoint_status and witness_status before using pending_positions.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryConsumerDiagnosticsResponse" }, "examples": { "uninitialized": { "value": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "diagnostics": { "consumer_id": "search-cache", "active": false, "baseline": null, "high_watermark": null, "checkpoint": null, "checkpoint_status": "missing", "pending_positions": null, "witness_status": "not_provided", "checkpoint_relative_to_witness": null } } } } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryConsumerDiagnosticsRequest" }, "example": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "consumer_id": "cache" }, "examples": { "current_state": { "value": { "contract_version": 2, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "shared" }, "consumer_id": "search-cache", "witness": null } } } } } } } }, "/api/v1/admin/identity": { "get": { "operationId": "globalIdentity", "summary": "Inspect the current global credential", "description": "No secret or verifier is returned. Global credentials do not authenticate tenant data endpoints.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalCredentialResponse" } } } } } } }, "/api/v1/admin/credentials": { "post": { "operationId": "issueGlobalCredential", "summary": "Delegate global administrative capabilities", "description": "Requires global_credential_admin. Capabilities must be a subset of the issuer and expiry cannot exceed the issuer. The issued credential is never the bootstrap master. Delivery is one-time, not idempotent.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedGlobalCredential" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalIssueRequest" } } } } }, "get": { "operationId": "listGlobalCredentials", "summary": "List global credentials", "description": "Return sanitized metadata, including revoked or disabled entries. Scope is selected before the ordered-key seek. Requires the installation master. Default 25, maximum 100 records; response at most 4 MiB (reduce limit on 400). Pages are live forward-only key traversal, not a snapshot. Concurrent insertions before the cursor require a new traversal. No full total is claimed.", "tags": [ "Administration directory" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryGlobalCredentialsResponse" } } } } }, "parameters": [ { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ] } }, "/api/v1/admin/credentials/{id}": { "get": { "operationId": "inspectGlobalCredential", "summary": "Inspect a global credential and its history", "description": "Requires global_credential_admin and a capability superset of the target.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalCredentialResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/admin/credentials/{id}/rotate": { "post": { "operationId": "rotateGlobalCredential", "summary": "Rotate a global credential", "description": "Requires expected_revision. Allowed for self or global_credential_admin with a capability superset of the target. Delegates cannot change the bootstrap master. Revocation is durable; offline master recovery is the only recovery route.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedGlobalCredential" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionRequest" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/admin/credentials/{id}/revoke": { "post": { "operationId": "revokeGlobalCredential", "summary": "Revoke a global credential", "description": "Requires expected_revision. Allowed for self or global_credential_admin with a capability superset of the target. Delegates cannot change the bootstrap master. Revocation is durable; offline master recovery is the only recovery route.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalCredentialResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionRequest" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/admin/tenants": { "post": { "operationId": "registerTenant", "summary": "Register a company and its first administrator", "description": "Requires tenant_create. Atomically creates tenant authority, registration receipt and initial tenant credential. Existing tenant IDs return 409; no authority is replaced. One-time secret delivery is not idempotent.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredTenant" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTenantRequest" } } } } }, "get": { "operationId": "listTenants", "summary": "List tenants", "description": "Return sanitized metadata, including revoked or disabled entries. Scope is selected before the ordered-key seek. Requires tenant_inspect. Default 25, maximum 100 records; response at most 4 MiB (reduce limit on 400). Pages are live forward-only key traversal, not a snapshot. Concurrent insertions before the cursor require a new traversal. No full total is claimed.", "tags": [ "Administration directory" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryTenantsResponse" } } } } }, "parameters": [ { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ] } }, "/api/v1/admin/tenants/{tenant}": { "get": { "operationId": "inspectTenant", "summary": "Inspect tenant registration provenance", "description": "Requires tenant_inspect. No tenant memory or secrets are returned.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInspection" } } } }, "404": { "description": "The tenant does not exist; caller authority was checked first.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Exact tenant identifier, URL encoded." } ] } }, "/api/v1/admin/tenants/{tenant}/admin-credentials": { "post": { "operationId": "issueTenantAdmin", "summary": "Appoint or recover a tenant administrator", "description": "Requires tenant_admin. Creates a new auditable tenant credential with credential_admin and policy_admin and no memory grants. It does not revoke existing administrators. Secret delivery is one-time.", "tags": [ "Administration" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedCredential" } } } }, "404": { "description": "The tenant does not exist; caller authority was checked first.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantAdminRequest" } } } }, "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Exact tenant identifier, URL encoded." } ] } }, "/api/v1/login": { "post": { "operationId": "loginTenant", "summary": "Tenant username/password login", "description": "Provisioned accounts only; no anonymous signup. Same 401 for unknown, incorrect, locked, disabled or revoked accounts. Five failed attempts lock an account for five minutes durably. Per process: 8 attempts per name and authority per minute, 120 total per minute, 2 concurrent password operations. A session lasts at most 15 minutes or the underlying credential expiry. At most 32 sessions per account; a new session evicts the oldest when full. No cookies or refresh tokens.", "tags": [ "Human login" ], "security": [], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginSessionResponse" } } } }, "429": { "description": "Login rate limit reached; wait at least one minute", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Both password workers are occupied; retry with backoff", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantLoginRequest" } } } } } }, "/api/v1/login-accounts": { "post": { "operationId": "createTenantLoginAccount", "summary": "create tenant login account", "description": "Requires credential_admin in this tenant. Create a unique case-sensitive account bound to an active credential in this authority. Existing names return 409. The API key is never returned by login.", "tags": [ "Human login" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } }, "503": { "description": "Both password workers are occupied; retry with backoff", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountCreate" } } } } }, "get": { "operationId": "listTenantLoginAccounts", "summary": "List tenant login accounts", "description": "Return sanitized metadata, including revoked or disabled entries. Scope is selected before the ordered-key seek. Requires credential_admin in the authenticated tenant. Default 25, maximum 100 records; response at most 4 MiB (reduce limit on 400). Pages are live forward-only key traversal, not a snapshot. Concurrent insertions before the cursor require a new traversal. No full total is claimed.", "tags": [ "Administration directory" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryTenantLoginAccountsResponse" } } } } }, "parameters": [ { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ] } }, "/api/v1/login-accounts/{id}": { "get": { "operationId": "inspectTenantLoginAccount", "summary": "inspect tenant login account", "description": "Requires credential_admin in this tenant. Return sanitized metadata and administrative history; password verifiers, failure counters and session tokens are never returned.", "tags": [ "Human login" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/login-accounts/{id}/password": { "post": { "operationId": "changePasswordTenantLoginAccount", "summary": "changePassword tenant login account", "description": "Requires credential_admin in this tenant. Replace the password using expected_revision and atomically invalidate all sessions. A disabled account cannot be reactivated. API keys remain unchanged.", "tags": [ "Human login" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } }, "503": { "description": "Both password workers are occupied; retry with backoff", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginPasswordChange" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/login-accounts/{id}/disable": { "post": { "operationId": "disableTenantLoginAccount", "summary": "disable tenant login account", "description": "Requires credential_admin in this tenant. Irreversibly disable username/password login and invalidate every session using expected_revision. This does not revoke independently issued API keys.", "tags": [ "Human login" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountDisable" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/admin/login": { "post": { "operationId": "loginGlobal", "summary": "Global username/password login", "description": "Provisioned accounts only; no anonymous signup. Same 401 for unknown, incorrect, locked, disabled or revoked accounts. Five failed attempts lock an account for five minutes durably. Per process: 8 attempts per name and authority per minute, 120 total per minute, 2 concurrent password operations. A session lasts at most 15 minutes or the underlying credential expiry. At most 32 sessions per account; a new session evicts the oldest when full. No cookies or refresh tokens.", "tags": [ "Human login" ], "security": [], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginSessionResponse" } } } }, "429": { "description": "Login rate limit reached; wait at least one minute", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Both password workers are occupied; retry with backoff", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalLoginRequest" } } } } } }, "/api/v1/admin/login-accounts": { "post": { "operationId": "createGlobalLoginAccount", "summary": "create global login account", "description": "Requires the installation master. Create a unique case-sensitive account bound to an active credential in this authority. Existing names return 409. The API key is never returned by login.", "tags": [ "Human login" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } }, "503": { "description": "Both password workers are occupied; retry with backoff", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountCreate" } } } } }, "get": { "operationId": "listGlobalLoginAccounts", "summary": "List global login accounts", "description": "Return sanitized metadata, including revoked or disabled entries. Scope is selected before the ordered-key seek. Requires the installation master. Default 25, maximum 100 records; response at most 4 MiB (reduce limit on 400). Pages are live forward-only key traversal, not a snapshot. Concurrent insertions before the cursor require a new traversal. No full total is claimed.", "tags": [ "Administration directory" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryGlobalLoginAccountsResponse" } } } } }, "parameters": [ { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ] } }, "/api/v1/admin/login-accounts/{id}": { "get": { "operationId": "inspectGlobalLoginAccount", "summary": "inspect global login account", "description": "Requires the installation master. Return sanitized metadata and administrative history; password verifiers, failure counters and session tokens are never returned.", "tags": [ "Human login" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/admin/login-accounts/{id}/password": { "post": { "operationId": "changePasswordGlobalLoginAccount", "summary": "changePassword global login account", "description": "Requires the installation master. Replace the password using expected_revision and atomically invalidate all sessions. A disabled account cannot be reactivated. API keys remain unchanged.", "tags": [ "Human login" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } }, "503": { "description": "Both password workers are occupied; retry with backoff", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginPasswordChange" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/admin/login-accounts/{id}/disable": { "post": { "operationId": "disableGlobalLoginAccount", "summary": "disable global login account", "description": "Requires the installation master. Irreversibly disable username/password login and invalidate every session using expected_revision. This does not revoke independently issued API keys.", "tags": [ "Human login" ], "security": [ { "globalCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAccountDisable" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/logout": { "post": { "operationId": "logoutSession", "summary": "Revoke the current login session", "description": "Requires a current login session. Invalid, expired, already logged-out sessions and permanent API keys return 401. Other sessions and API keys remain unchanged.", "tags": [ "Human login" ], "security": [ { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 8,192 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponse" } } } } } } }, "/api/v1/memory/records/batch": { "post": { "operationId": "readMemoryRecordBatch", "summary": "Read 1–100 current memories in one scoped snapshot", "description": "Requires memory_read for one exact scope; tenant and private subject are credential-derived. Preserves request order and checks root and transitive eligibility at one server time. Null means unavailable, without disclosing a reason. No continuation or partial success: invalid/duplicate IDs, 8 MiB root-byte exhaustion or aggregate dependency work exhaustion fail the request. Uses the shared retrieval admission slots, after authorization. This does not activate a journal, advance a checkpoint or certify future freshness; mutations and time can invalidate records after evaluation.", "tags": [ "Memory" ], "responses": { "200": { "description": "Complete requested batch observed at one storage snapshot and one evaluation clock", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryBatchReadResponse" }, "examples": { "unavailable": { "summary": "Uniform unavailable result, without a reason", "value": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "batch": { "evaluated_at_millis": 1700000000000, "entries": [ { "record_id": "018f0000-0000-4000-8000-000000000001", "record": null } ], "record_bytes": 0, "dependency_work": { "records_examined": 0, "bytes_examined": 0 } } } } } } } }, "400": { "description": "Invalid or duplicate UUIDs, count outside 1–100, unsupported contract version, root bytes above 8 MiB or aggregate dependency work exhausted. No successful entries returned.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryBatchReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "record_ids": [ "018f0000-0000-4000-8000-000000000001" ] } } } } } }, "/api/v1/credentials/{id}/scope-authority": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "setCredentialScopeAuthority", "summary": "Replace exact grants or company integration scope policy", "description": "Requires credential_admin in the same tenant. Replaces only scope authority under an exact revision guard; preserves the key secret, subject, tenant, capabilities and expiry. Every success increments the revision and atomically records previous/current authority. Existing login sessions bound to the changed credential become invalid. Requests already authorized may finish. A lost response is reconciled by inspection; a stale replay returns 409, never an unguarded overwrite. Revoked targets are denied. Empty grants without a policy deny all data scopes. This operation does not register agents or issue child keys.", "tags": [ "Identity" ], "responses": { "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialResponse" } } } }, "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeAuthorityRequest" } } } } } }, "/api/v1/agents": { "get": { "operationId": "listObservedAgents", "summary": "List automatically registered company agents", "description": "Available in the 0.12.0 contract. Requires credential_admin. Company comes from the authenticated principal, never from query parameters. A first successful authorized resource request observes an unchanged external agent ID. New memory commands commit registration, memory and receipt atomically. Other resource operations register after success before returning; a registration failure can follow an already committed operation, requiring reconciliation through its existing contract. Valid empty reads can register agents. This directory starts collecting at feature activation and does not backfill historical IDs. Registration is metadata, never a grant, ownership claim or active-status assertion. Company prefix is selected before traversal; results use UTF-8 byte order with an exclusive after_agent_id cursor. Pages are live, not a snapshot: concurrent insertions before the cursor require a fresh traversal. Default 25, maximum 100 entries.", "tags": [ "Agent registration" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency payload or expected revision conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObservedAgentResponse" } } } } }, "parameters": [ { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after_agent_id", "in": "query", "description": "Exclusive external agent ID from next_after_agent_id. URL-encode it as a query parameter. Omit for a new traversal.", "schema": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." } } ] } }, "/api/v1/company/memory/workspaces": { "get": { "operationId": "listCompanyMemoryWorkspaces", "summary": "Discover company memory workspaces from storage", "description": "Available in the 0.12.0 contract. Requires credential_admin in the authenticated company. Includes all private subjects and retained workspaces even after grants are revoked or all memories become ineligible. The catalog is populated from canonical memory keys at startup and committed with subsequent memory mutations; it does not infer membership from credentials. Selects the company prefix before traversal. Live exclusive continuation by workspace ID, default 25 and maximum 100; restart traversal for concurrent insertions before the cursor. Uses the shared server retrieval admission limit, with 503 retrieval_busy after authorization. No agent registration or temporary credential issuance occurs.", "tags": [ "Company memory administration" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryWorkspaceResponse" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } }, "parameters": [ { "name": "contract_version", "in": "query", "required": true, "schema": { "type": "integer", "const": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after_workspace_id", "in": "query", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Opaque SHA-256 identifier of the unchanged canonical company, scope and private subject address. This identifier grants no authority." } } ] } }, "/api/v1/company/memory/query": { "post": { "operationId": "queryCompanyMemory", "summary": "Inspect retained or currently eligible company memory", "description": "Available in the 0.12.0 contract. Requires credential_admin. The company is derived from authentication; workspace IDs are resolved only within it. No caller-selected company, private owner or authority override is accepted. One workspace and one snapshot per request, including the same eligibility clock and transitive dependency view. Default retained view includes current canonical tombstones and ineligible payloads; it is an administration view, not agent context. Current view suppresses ineligible records. Ordered UUID traversal with explicit continuation after the last examined record, including empty filtered pages. Stop reason identifies record, scan or root-byte budget exhaustion. At most 100 returned records, 10000 examined roots, 8 MiB decoded root bytes; dependency work has the existing 4096-record/16 MiB aggregate bound. Dependency exhaustion fails the whole request; reduce the page/scan limit. Byte counters exclude integrity indexes and the fetched lookahead value and are not an RSS or final response-size cap. Pages are live, not one cross-request snapshot. No ranking or total count is claimed. Authorization precedes the shared retrieval admission limit. No partial success after integrity or dependency-budget failure; capacity returns 503 retrieval_busy. Administrative reads do not register agents, alter reviews or issue delegated credentials.", "tags": [ "Company memory administration" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryInventoryResponse" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No retained workspace or record exists in the authorized company.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryNotFoundError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryQueryRequest" } } } } } }, "/api/v1/company/memory/read": { "post": { "operationId": "inspectCompanyMemory", "summary": "Inspect a retained company record and its eligibility", "description": "Available in the 0.12.0 contract. Requires credential_admin. The company is derived from authentication; workspace IDs are resolved only within it. No caller-selected company, private owner or authority override is accepted. Read the current retained record and eligibility in one snapshot, including deleted markers, expired/rejected payloads and invalidated derivations. Missing workspace or record, including a workspace belonging to another company, returns the same 404 record_not_found. It does not retrieve overwritten historical payload revisions or make the record available to ordinary agent retrieval. Authorization precedes the shared retrieval admission limit. No partial success after integrity or dependency-budget failure; capacity returns 503 retrieval_busy. Administrative reads do not register agents, alter reviews or issue delegated credentials.", "tags": [ "Company memory administration" ], "security": [ { "platformCredential": [] }, { "loginSession": [] } ], "responses": { "400": { "description": "Invalid fields or unsupported contract version", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Successful operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryInspectionResponse" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No retained workspace or record exists in the authorized company.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryNotFoundError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryInspectionRequest" } } } } } }, "/api/v1/memory/graph": { "post": { "operationId": "readMemoryEvidenceGraph", "summary": "Read current scoped evidence ancestry in one snapshot", "description": "Available in the 0.12.0 contract. Requires memory_read for one exact scope before storage access or retrieval admission. Traverse outgoing derived_from ancestry of 1–16 distinct root UUIDs, breadth first, roots in request order and children in UUID order. Tenant and private subject are credential-derived. Every returned record and its complete dependency graph must be eligible at one snapshot and server clock, even when display depth is zero. Nodes are deduplicated; edges pin exact revisions and have both endpoints in nodes. No ranking, entity extraction, incoming-edge search, cross-scope expansion or cursor. Depth/node cuts return 200 with explicit incomplete coverage; unavailable roots disclose no reason, and not_examined roots are distinct. Byte or dependency-budget exhaustion and encountered corruption fail the entire request. complete describes currently eligible ancestry from the requested roots, not the entire corpus or future validity. All responses are no-store.", "tags": [ "Memory" ], "responses": { "200": { "description": "Current evidence graph with explicit root availability and traversal coverage", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryGraphResponse" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "graph": { "traversal_version": "derived_ancestry_v1", "evaluated_at_millis": 1700000000000, "max_depth": 4, "node_limit": 128, "roots": [ { "record_id": "018f0000-0000-4000-8000-000000000001", "status": "unavailable" } ], "nodes": [], "edges": [], "coverage": { "complete": true, "stop_reasons": [], "records_examined": 1, "record_bytes": 0, "dependency_work": { "records_examined": 0, "bytes_examined": 0 } } } } } } }, "400": { "description": "Invalid or duplicate roots, unsupported contract version, depth outside 0–8, node limit outside 1–256, canonical record bytes above 8 MiB, or dependency work above 4096 reads / 16 MiB. No graph is returned on failure.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryGraphRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "query": { "root_record_ids": [ "018f0000-0000-4000-8000-000000000001" ], "max_depth": 4, "node_limit": 128 } } } } } } }, "/api/v1/company/memory/graph": { "post": { "operationId": "readCompanyMemoryEvidenceGraph", "summary": "Read eligible evidence ancestry in a company workspace", "description": "Available in the 0.12.0 contract. Requires credential_admin. Resolve workspace_id only inside the authenticated company, then use the same derived_ancestry_v1 snapshot and eligibility contract as /api/v1/memory/graph. This includes private workspaces of every subject in the company without issuing scoped keys. Missing and other-company workspaces share 404 record_not_found. Unknown or ineligible roots inside an existing workspace have status unavailable. Unlike retained inventory, this graph never returns deleted, expired, rejected or transitively invalid payloads. Depth/node truncation is explicit; byte, dependency and integrity failures return no graph. No caller-selected company or subject and no graph-based ranking. Administrative reads do not register agents or issue credentials.", "tags": [ "Company memory administration" ], "responses": { "200": { "description": "Current evidence graph with explicit root availability and traversal coverage", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryGraphResponse" } } } }, "400": { "description": "Invalid or duplicate roots, unsupported contract version, depth outside 0–8, node limit outside 1–256, canonical record bytes above 8 MiB, or dependency work above 4096 reads / 16 MiB. No graph is returned on failure.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, expired or revoked credential", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Capability, tenant or scope is not granted", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 65,536 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal failure or explicit stored-version inconsistency", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "retrieval_busy: all server retrieval slots are in use. Retry with bounded backoff. No retrieval is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" }, "example": { "contract_version": 1, "error": { "code": "retrieval_busy", "message": "The server has no available retrieval slot; retry with backoff" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No retained workspace exists in the authorized company; foreign workspaces have the same result.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryNotFoundError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryGraphRequest" } } } }, "security": [ { "platformCredential": [] }, { "loginSession": [] } ] } }, "/api/v1/memory/relations/commands": { "post": { "tags": [ "Memory" ], "summary": "Commit a revision-bound typed memory assertion or lifecycle decision", "description": "Unreleased 0.13.0 contract. Requires memory_read and memory_write for assert/retire/restore; review requires memory_read and memory_review. Authorization and retrieval admission precede atomic WAL publication. Idempotency is scoped to authenticated subject and namespace. A replay returns the original receipt, not current eligibility.", "operationId": "memoryRelationCommands", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationCommandRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "idempotency_key": "extract-run-42-relation-1", "operation": { "type": "assert", "relation": { "source": { "record_id": "018f0000-0000-4000-8000-000000000001", "revision": 2 }, "target": { "record_id": "018f0000-0000-4000-8000-000000000002", "revision": 1 }, "kind": "supports", "provenance": { "origin": "model_inference", "method": "support-extraction", "method_revision": "prompt-v3", "evidence_ref": "trace://run-42/relation-1", "model": { "provider": "example-provider", "model": "example-model", "revision": "example-pinned-revision" } }, "valid_from_millis": null, "valid_until_millis": null } } } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationCommandsResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, version, revision, provenance, validity, lifecycle transition or work budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "Relation or revision unavailable in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "409": { "description": "Idempotency content mismatch, expected relation revision conflict, or endpoint revision/eligibility conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationConflictError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/read": { "post": { "tags": [ "Memory" ], "summary": "Read a currently eligible typed memory relation", "description": "Unreleased 0.13.0 contract. Requires memory_read. Returns 404 for absent, retired, rejected, not-yet-valid, expired or endpoint-invalid relations. One snapshot and evaluation clock recheck both exact endpoint revisions and their transitive evidence.", "operationId": "memoryRelationRead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "relation_id": "018f0000-0000-4000-8000-000000000003" } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationReadResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, version, revision, provenance, validity, lifecycle transition or work budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "Relation or revision unavailable in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/inspect": { "post": { "tags": [ "Memory" ], "summary": "Inspect retained typed relation metadata and current eligibility", "description": "Unreleased 0.13.0 contract. Requires memory_read and memory_review. Includes retained states and the first eligibility failure; does not include endpoint payloads or certify the assertion.", "operationId": "memoryRelationInspect", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "relation_id": "018f0000-0000-4000-8000-000000000003" } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationInspectResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, version, revision, provenance, validity, lifecycle transition or work budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "Relation or revision unavailable in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/revision": { "post": { "tags": [ "Memory" ], "summary": "Read an immutable typed relation revision and its original receipt", "description": "Unreleased 0.13.0 contract. Requires memory_read and memory_review. Historical assertions are audit evidence, not current retrieval results; always revalidate before reuse.", "operationId": "memoryRelationRevision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationRevisionRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "relation_id": "018f0000-0000-4000-8000-000000000003", "revision": 1 } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationRevisionResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, version, revision, provenance, validity, lifecycle transition or work budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "Relation or revision unavailable in the authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRelationNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/graph/typed": { "post": { "operationId": "typedMemoryGraph", "summary": "Read a bounded typed memory neighborhood", "description": "Unreleased 0.13.0 contract. Requires memory_read in the exact credential-derived company/private-subject scope. Traversal uses one snapshot and clock, exact eligible endpoint revisions, directed provenance-bearing assertions, explicit work and cuts, and atomic adjacency completeness checks. Filters run within the authorized namespace. No ranking, model inference, relation feed, lease or continuation cursor. Authorization precedes shared retrieval admission; responses are no-store.", "tags": [ "Memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypedMemoryGraphRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "query": { "root_record_ids": [ "018f0000-0000-4000-8000-000000000001" ], "direction": "both", "relation_kinds": [ "supports", "contradicts", "semantic_related" ], "max_depth": 2, "node_limit": 128, "edge_limit": 256, "scan_limit": 1024 } } } } }, "responses": { "200": { "description": "Successful authorized response; inspect coverage, availability or historical eligibility semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypedMemoryGraphResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, unsupported version, bounds or exhausted canonical, relation or dependency byte budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing capability or unauthorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds the 65536-byte body limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Encountered canonical, relation, history, adjacency or completeness-header inconsistency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval slots are occupied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/company/memory/graph/typed": { "post": { "operationId": "companyTypedMemoryGraph", "summary": "Read typed neighbors in a company workspace", "description": "Unreleased 0.13.0 contract. Requires company credential_admin; a workspace ID is not a grant. No delegated credential is created. Traversal uses one snapshot and clock, exact eligible endpoint revisions, directed provenance-bearing assertions, explicit work and cuts, and atomic adjacency completeness checks. Filters run within the authorized namespace. No ranking, model inference, relation feed, lease or continuation cursor. Authorization precedes shared retrieval admission; responses are no-store.", "tags": [ "Administration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyTypedMemoryGraphRequest" }, "example": { "contract_version": 1, "workspace_id": "0000000000000000000000000000000000000000000000000000000000000000", "query": { "root_record_ids": [ "018f0000-0000-4000-8000-000000000001" ], "direction": "both" } } } } }, "responses": { "200": { "description": "Successful authorized response; inspect coverage, availability or historical eligibility semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyTypedMemoryGraphResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, unsupported version, bounds or exhausted canonical, relation or dependency byte budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing capability or unauthorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds the 65536-byte body limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Encountered canonical, relation, history, adjacency or completeness-header inconsistency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval slots are occupied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No retained workspace, relation or historical revision exists in the authorized company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/company/memory/relations/inspect": { "post": { "operationId": "inspectCompanyMemoryRelation", "summary": "Inspect retained relation state in a company workspace", "description": "Unreleased 0.13.0 contract. Requires company credential_admin; a workspace ID is not a grant. No delegated credential is created. Returns retained relation metadata under native company authority, including historical or currently ineligible assertions; no memory payloads are included. Authorization precedes shared retrieval admission; responses are no-store.", "tags": [ "Administration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryRelationInspectRequest" }, "example": { "contract_version": 1, "workspace_id": "0000000000000000000000000000000000000000000000000000000000000000", "relation_id": "018f0000-0000-4000-8000-000000000003" } } } }, "responses": { "200": { "description": "Successful authorized response; inspect coverage, availability or historical eligibility semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryRelationInspectResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, unsupported version, bounds or exhausted canonical, relation or dependency byte budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing capability or unauthorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds the 65536-byte body limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Encountered canonical, relation, history, adjacency or completeness-header inconsistency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval slots are occupied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No retained workspace, relation or historical revision exists in the authorized company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/company/memory/relations/revision": { "post": { "operationId": "readCompanyMemoryRelationRevision", "summary": "Read immutable relation history in a company workspace", "description": "Unreleased 0.13.0 contract. Requires company credential_admin; a workspace ID is not a grant. No delegated credential is created. Returns retained relation metadata under native company authority, including historical or currently ineligible assertions; no memory payloads are included. Authorization precedes shared retrieval admission; responses are no-store.", "tags": [ "Administration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryRelationRevisionRequest" }, "example": { "contract_version": 1, "workspace_id": "0000000000000000000000000000000000000000000000000000000000000000", "relation_id": "018f0000-0000-4000-8000-000000000003", "revision": 1 } } } }, "responses": { "200": { "description": "Successful authorized response; inspect coverage, availability or historical eligibility semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryRelationRevisionResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid fields, unsupported version, bounds or exhausted canonical, relation or dependency byte budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing capability or unauthorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds the 65536-byte body limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Encountered canonical, relation, history, adjacency or completeness-header inconsistency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval slots are occupied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No retained workspace, relation or historical revision exists in the authorized company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMemoryNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/changes": { "post": { "tags": [ "Memory" ], "summary": "Read a fenced suffix of typed relation changes", "description": "Unreleased 0.13.0. Requires memory_read in the exact current scope. Authentication determines company and private subject. Uses shared retrieval admission through serialization and no-store responses. Relation changes are separate from memory feeds; expiry still requires current-state revalidation.", "operationId": "memoryRelationChanges", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangesRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "query": { "after": null, "through": null, "limit": 100 } } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangesResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid contract version, fields, bounds, cursor structure, identity or reconciliation evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "409": { "description": "History mismatch, expected checkpoint conflict, changed idempotency content or prohibited progress regression.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangeConflictError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/changes/activate": { "post": { "tags": [ "Memory" ], "summary": "Activate a relation journal without fabricating historical events", "description": "Unreleased 0.13.0. Requires memory_read and memory_write in the exact current scope. Authentication determines company and private subject. Uses shared retrieval admission through serialization and no-store responses. Relation changes are separate from memory feeds; expiry still requires current-state revalidation.", "operationId": "memoryRelationChangesActivate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangesActivateRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" } } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangesActivateResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid contract version, fields, bounds, cursor structure, identity or reconciliation evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "409": { "description": "History mismatch, expected checkpoint conflict, changed idempotency content or prohibited progress regression.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangeConflictError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/checkpoints": { "post": { "tags": [ "Memory" ], "summary": "Advance or explicitly reconcile subject-owned relation progress", "description": "Unreleased 0.13.0. Requires memory_read and memory_checkpoint in the exact current scope. Authentication determines company and private subject. Uses shared retrieval admission through serialization and no-store responses. Relation changes are separate from memory feeds; expiry still requires current-state revalidation.", "operationId": "memoryRelationCheckpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationCheckpointRequest" }, "example": { "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "command": { "contract_version": 1, "idempotency_key": "relation-cache-initialize-1", "consumer_id": "context-cache", "expected_revision": 0, "expected_checkpoint_digest": null, "operation": { "type": "advance", "cursor": { "version": 1, "stream": "typed_memory_relations", "journal_id": "018f0000-0000-4000-8000-000000000010", "sequence": 1, "prefix_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationCheckpointResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid contract version, fields, bounds, cursor structure, identity or reconciliation evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "409": { "description": "History mismatch, expected checkpoint conflict, changed idempotency content or prohibited progress regression.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangeConflictError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/checkpoints/read": { "post": { "tags": [ "Memory" ], "summary": "Read currently history-compatible relation progress", "description": "Unreleased 0.13.0. Requires memory_read and memory_checkpoint in the exact current scope. Authentication determines company and private subject. Uses shared retrieval admission through serialization and no-store responses. Relation changes are separate from memory feeds; expiry still requires current-state revalidation.", "operationId": "memoryRelationCheckpointRead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationCheckpointReadRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "consumer_id": "context-cache" } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationCheckpointReadResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid contract version, fields, bounds, cursor structure, identity or reconciliation evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "409": { "description": "History mismatch, expected checkpoint conflict, changed idempotency content or prohibited progress regression.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangeConflictError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No subject-owned checkpoint or requested immutable checkpoint revision in this authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/checkpoints/revision": { "post": { "tags": [ "Memory" ], "summary": "Read an immutable subject-owned relation checkpoint receipt", "description": "Unreleased 0.13.0. Requires memory_read and memory_checkpoint in the exact current scope. Authentication determines company and private subject. Uses shared retrieval admission through serialization and no-store responses. Relation changes are separate from memory feeds; expiry still requires current-state revalidation.", "operationId": "memoryRelationCheckpointRevision", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationCheckpointRevisionRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "consumer_id": "context-cache", "revision": 1 } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationCheckpointRevisionResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid contract version, fields, bounds, cursor structure, identity or reconciliation evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "409": { "description": "History mismatch, expected checkpoint conflict, changed idempotency content or prohibited progress regression.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangeConflictError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "404": { "description": "No subject-owned checkpoint or requested immutable checkpoint revision in this authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointNotFoundError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/relations/consumers/diagnose": { "post": { "tags": [ "Memory" ], "summary": "Diagnose relation history, checkpoint and durable witness compatibility", "description": "Unreleased 0.13.0. Requires memory_read and memory_checkpoint in the exact current scope. Authentication determines company and private subject. Uses shared retrieval admission through serialization and no-store responses. Relation changes are separate from memory feeds; expiry still requires current-state revalidation.", "operationId": "memoryRelationConsumerDiagnose", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationConsumerDiagnoseRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "mission_id": null, "agent_id": "agent", "visibility": "private" }, "consumer_id": "context-cache", "witness": { "version": 1, "stream": "typed_memory_relations", "journal_id": "018f0000-0000-4000-8000-000000000010", "sequence": 1, "prefix_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } }, "responses": { "200": { "description": "Successful operation; inspect explicit state, eligibility or receipt semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationConsumerDiagnoseResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid contract version, fields, bounds, cursor structure, identity or reconciliation evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked authority.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing operation capability or authorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Storage or integrity failure; no successful partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval capacity is occupied; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "409": { "description": "History mismatch, expected checkpoint conflict, changed idempotency content or prohibited progress regression.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationChangeConflictError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/search/graph": { "post": { "operationId": "searchMemoryGraph", "summary": "Retrieve memory through experimental versioned typed paths", "description": "Unreleased 0.13.0. Requires memory_read in the exact authorized scope. Selects up to four anchors from up to 100 lexical, external-vector or hybrid candidates, expands revision-bound typed neighbors and combines base/path ranks. One snapshot and clock, filters before expansion, no automatic relation extraction, no provider calls. Inspect coverage and proof paths. Scores are not cosine or probabilities. Hard errors fail the whole response. No continuation cursor, default promotion or measured quality gain. 2 MiB request body and shared retrieval admission. See the graph-assisted retrieval guide for immutable formulas and work accounting.", "tags": [ "Memory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRetrievalRequest" }, "example": { "contract_version": 1, "scope": { "project_id": "project", "agent_id": "agent", "mission_id": null, "visibility": "private" }, "query": { "ranking_version": "typed_path_evidence_v1", "seed": { "mode": "lexical", "text": "cache invalidation" }, "limit": 10 } } } } }, "responses": { "200": { "description": "Successful authorized response; inspect coverage, availability or historical eligibility semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRetrievalResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Qilbee-Retrieval-Micros": { "schema": { "type": "integer", "minimum": 0 }, "description": "Monotonic elapsed microseconds for scoped snapshot retrieval after authorization and admission, including seed selection, traversal, affinities and ranking. Excludes JSON serialization, HTTP transport and external query embedding generation." } } }, "400": { "description": "Invalid contract, fields, bounds, text, vector, dimensions or byte budgets. Operator ceilings use embedding_dimension_limit or retrieval_scan_limit. Hard graph/dependency/affinity exhaustion returns an error, never a partial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing capability or unauthorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "413": { "description": "Request exceeds the 65536-byte body limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Encountered canonical, relation, history, adjacency or completeness-header inconsistency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "503": { "description": "Shared retrieval slots are occupied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalBusyError" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } }, "/api/v1/memory/graph-ranking-profiles": { "get": { "operationId": "graphRankingProfiles", "summary": "List immutable experimental typed-path ranking profiles", "description": "Requires memory_read. Profiles are server-owned; requests cannot supply weights. All current versions share the documented 1/3 maximum combined score.", "tags": [ "Memory" ], "responses": { "200": { "description": "Successful authorized response; inspect coverage, availability or historical eligibility semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRankingProfilesResponse" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "Missing, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "403": { "description": "Missing capability or unauthorized scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "500": { "description": "Encountered canonical, relation, history, adjacency or completeness-header inconsistency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } } } } } }, "components": { "securitySchemes": { "platformCredential": { "type": "http", "scheme": "bearer", "bearerFormat": "qdb1 opaque credential", "description": "Provision through the trusted local bootstrap command and authenticated credential API." }, "globalCredential": { "type": "http", "scheme": "bearer", "bearerFormat": "qdbg1 opaque global credential", "description": "Separate global authority. Tenant keys never authorize installation administration. Bootstrap the master locally; delegate narrow service capabilities." }, "loginSession": { "type": "http", "scheme": "bearer", "description": "A qdbsg1_ global or qdbst1_ tenant login session. The endpoint still enforces its specific authority. Expires within 15 minutes." } }, "schemas": { "RelationChangeCursor": { "type": "object", "properties": { "version": { "type": "integer", "const": 1 }, "stream": { "type": "string", "const": "typed_memory_relations" }, "journal_id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "prefix_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "version", "stream", "journal_id", "sequence", "prefix_digest" ], "additionalProperties": false, "description": "A complete opaque cursor for one authorized relation journal. It is not a memory-feed cursor or authorization. The prefix digest distinguishes divergent histories even after sequence numbers catch up." }, "RelationChange": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "kind": { "type": "string", "enum": [ "asserted", "retired", "restored", "reviewed" ] }, "relation_id": { "type": "string", "format": "uuid" }, "relation_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "source": { "$ref": "#/components/schemas/MemorySourceRef" }, "target": { "$ref": "#/components/schemas/MemorySourceRef" }, "relation_kind": { "$ref": "#/components/schemas/MemoryRelationKind" }, "author": { "$ref": "#/components/schemas/Author" }, "committed_at_millis": { "type": "integer", "format": "int64" }, "relation_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "receipt_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "schema_version", "kind", "relation_id", "relation_revision", "source", "target", "relation_kind", "author", "committed_at_millis", "relation_digest", "receipt_digest" ], "additionalProperties": false, "description": "Committed assertion metadata bound to an exact immutable relation revision and receipt. Contains no memory text, vectors, model output or provenance evidence text. Endpoint mutations and clock-driven expiry do not create events in this stream." }, "RelationChangeDelivery": { "type": "object", "properties": { "cursor": { "$ref": "#/components/schemas/RelationChangeCursor" }, "change": { "$ref": "#/components/schemas/RelationChange" } }, "required": [ "cursor", "change" ], "additionalProperties": false }, "RelationChangesQuery": { "type": "object", "properties": { "after": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] }, "through": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 256 } }, "required": [ "limit" ], "additionalProperties": false }, "RelationChangesPage": { "type": "object", "properties": { "active": { "type": "boolean" }, "baseline": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] }, "changes": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/RelationChangeDelivery" } }, "next_cursor": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] }, "high_watermark": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "active", "baseline", "changes", "next_cursor", "high_watermark", "complete" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "active": { "const": true } }, "required": [ "active" ] }, "then": { "properties": { "baseline": { "$ref": "#/components/schemas/RelationChangeCursor" }, "next_cursor": { "$ref": "#/components/schemas/RelationChangeCursor" }, "high_watermark": { "$ref": "#/components/schemas/RelationChangeCursor" } } }, "else": { "properties": { "baseline": { "type": "null" }, "next_cursor": { "type": "null" }, "high_watermark": { "type": "null" }, "changes": { "maxItems": 0 }, "complete": { "const": true } } } } ] }, "RelationCheckpoint": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1–128 UTF-8 bytes, not blank and without control characters." }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "cursor": { "$ref": "#/components/schemas/RelationChangeCursor" }, "author": { "$ref": "#/components/schemas/Author" }, "updated_at_millis": { "type": "integer", "format": "int64" }, "checkpoint_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "schema_version", "consumer_id", "revision", "cursor", "author", "updated_at_millis", "checkpoint_digest" ], "additionalProperties": false }, "RelationCheckpointOperation": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "advance", "type": "string" }, "cursor": { "$ref": "#/components/schemas/RelationChangeCursor" } }, "required": [ "type", "cursor" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "reconcile", "type": "string" }, "cursor": { "$ref": "#/components/schemas/RelationChangeCursor" }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "1–2048 UTF-8 bytes, not blank and without control characters." } }, "required": [ "type", "cursor", "evidence_ref" ], "additionalProperties": false } ], "description": "advance initializes or moves compatible progress monotonically. reconcile explicitly replaces existing progress after caller-managed reconciliation and preserves the prior checkpoint plus declared evidence." }, "RelationCheckpointCommand": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1–128 UTF-8 bytes, not blank and without control characters." }, "expected_revision": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "expected_checkpoint_digest": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "operation": { "$ref": "#/components/schemas/RelationCheckpointOperation" } }, "required": [ "contract_version", "idempotency_key", "consumer_id", "expected_revision", "operation" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "expected_revision": { "const": 0 } }, "required": [ "expected_revision" ] }, "then": { "properties": { "expected_checkpoint_digest": { "type": "null" }, "operation": { "properties": { "type": { "const": "advance" } } } } }, "else": { "required": [ "expected_checkpoint_digest" ], "properties": { "expected_checkpoint_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } ] }, "RelationCheckpointReceipt": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "previous": { "anyOf": [ { "$ref": "#/components/schemas/RelationCheckpoint" }, { "type": "null" } ] }, "checkpoint": { "$ref": "#/components/schemas/RelationCheckpoint" }, "reconciliation_evidence": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "description": "1–2048 UTF-8 bytes, not blank and without control characters." }, { "type": "null" } ] }, "receipt_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "contract_version", "idempotency_key", "previous", "checkpoint", "reconciliation_evidence", "receipt_digest" ], "additionalProperties": false, "description": "Immutable command receipt. A replay can return an old revision even after progress advances or histories diverge; reread diagnostics before accepting it as current progress." }, "RelationConsumerDiagnostics": { "type": "object", "properties": { "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "active": { "type": "boolean" }, "baseline": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] }, "high_watermark": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] }, "checkpoint": { "anyOf": [ { "$ref": "#/components/schemas/RelationCheckpoint" }, { "type": "null" } ] }, "checkpoint_status": { "type": "string", "enum": [ "missing", "compatible", "history_incompatible" ] }, "pending_positions": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ], "description": "Sequence distance from compatible stored checkpoint to current tip, not an audit or a count of eligible records. Null when missing or history-incompatible." }, "witness_status": { "type": "string", "enum": [ "not_provided", "compatible", "history_incompatible" ] }, "checkpoint_relative_to_witness": { "type": [ "string", "null" ], "enum": [ "before", "equal", "after", null ] } }, "required": [ "consumer_id", "active", "baseline", "high_watermark", "checkpoint", "checkpoint_status", "pending_positions", "witness_status", "checkpoint_relative_to_witness" ], "additionalProperties": false, "description": "One scoped snapshot of relation history, subject-owned progress and an optional durable local witness. Pending positions are sequence distance, not an audit, eligible-edge count or proof of durable external effects.", "allOf": [ { "if": { "properties": { "active": { "const": true } }, "required": [ "active" ] }, "then": { "properties": { "baseline": { "$ref": "#/components/schemas/RelationChangeCursor" }, "high_watermark": { "$ref": "#/components/schemas/RelationChangeCursor" } } }, "else": { "properties": { "baseline": { "type": "null" }, "high_watermark": { "type": "null" } } } }, { "if": { "properties": { "checkpoint_status": { "const": "missing" } }, "required": [ "checkpoint_status" ] }, "then": { "properties": { "checkpoint": { "type": "null" } } }, "else": { "properties": { "checkpoint": { "$ref": "#/components/schemas/RelationCheckpoint" } } } }, { "if": { "properties": { "checkpoint_status": { "const": "compatible" } }, "required": [ "checkpoint_status" ] }, "then": { "properties": { "active": { "const": true }, "pending_positions": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 } } }, "else": { "properties": { "pending_positions": { "type": "null" } } } }, { "if": { "properties": { "witness_status": { "const": "compatible" } }, "required": [ "witness_status" ] }, "then": { "properties": { "active": { "const": true } } }, "else": { "properties": {} } }, { "if": { "properties": { "checkpoint_status": { "const": "compatible" }, "witness_status": { "const": "compatible" } }, "required": [ "checkpoint_status", "witness_status" ] }, "then": { "properties": { "checkpoint_relative_to_witness": { "type": "string", "enum": [ "before", "equal", "after" ] } } }, "else": { "properties": { "checkpoint_relative_to_witness": { "type": "null" } } } } ] }, "RelationChangesRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "query": { "$ref": "#/components/schemas/RelationChangesQuery" } }, "required": [ "contract_version", "scope", "query" ], "additionalProperties": false }, "RelationChangesResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "page": { "$ref": "#/components/schemas/RelationChangesPage" } }, "required": [ "contract_version", "scope", "page" ], "additionalProperties": false }, "RelationChangesActivateRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "contract_version", "scope" ], "additionalProperties": false }, "RelationChangesActivateResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "baseline": { "$ref": "#/components/schemas/RelationChangeCursor" } }, "required": [ "contract_version", "scope", "baseline" ], "additionalProperties": false }, "RelationCheckpointRequest": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "command": { "$ref": "#/components/schemas/RelationCheckpointCommand" } }, "required": [ "scope", "command" ], "additionalProperties": false }, "RelationCheckpointResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/RelationCheckpointReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "RelationCheckpointReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1–128 UTF-8 bytes, not blank and without control characters." } }, "required": [ "contract_version", "scope", "consumer_id" ], "additionalProperties": false }, "RelationCheckpointReadResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "checkpoint": { "$ref": "#/components/schemas/RelationCheckpoint" } }, "required": [ "contract_version", "scope", "checkpoint" ], "additionalProperties": false }, "RelationCheckpointRevisionRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1–128 UTF-8 bytes, not blank and without control characters." }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "contract_version", "scope", "consumer_id", "revision" ], "additionalProperties": false }, "RelationCheckpointRevisionResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "receipt": { "$ref": "#/components/schemas/RelationCheckpointReceipt" } }, "required": [ "contract_version", "scope", "receipt" ], "additionalProperties": false }, "RelationConsumerDiagnoseRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1–128 UTF-8 bytes, not blank and without control characters." }, "witness": { "anyOf": [ { "$ref": "#/components/schemas/RelationChangeCursor" }, { "type": "null" } ] } }, "required": [ "contract_version", "scope", "consumer_id" ], "additionalProperties": false }, "RelationConsumerDiagnoseResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "diagnostics": { "$ref": "#/components/schemas/RelationConsumerDiagnostics" } }, "required": [ "contract_version", "scope", "diagnostics" ], "additionalProperties": false }, "RelationChangeConflictError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "journal_history_conflict", "revision_conflict", "idempotency_conflict", "checkpoint_regression" ] } } } } } ] }, "TypedGraphDirection": { "type": "string", "enum": [ "outgoing", "incoming", "both" ], "description": "Choose index traversal direction; returned assertions preserve their original source-to-target direction." }, "TypedMemoryGraphQuery": { "type": "object", "properties": { "root_record_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 16, "uniqueItems": true }, "direction": { "$ref": "#/components/schemas/TypedGraphDirection", "default": "both" }, "relation_kinds": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRelationKind" }, "minItems": 1, "maxItems": 6, "uniqueItems": true, "default": [ "semantic_related", "same_entity", "temporal_before", "causal_claim", "supports", "contradicts" ] }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 8, "default": 2 }, "node_limit": { "type": "integer", "minimum": 1, "maximum": 256, "default": 128 }, "edge_limit": { "type": "integer", "minimum": 1, "maximum": 1024, "default": 256 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 4096, "default": 1024 } }, "required": [ "root_record_ids" ], "additionalProperties": false }, "TypedGraphCoverage": { "type": "object", "properties": { "complete": { "type": "boolean" }, "stop_reasons": { "type": "array", "items": { "type": "string", "enum": [ "depth_limit", "node_limit", "edge_limit", "scan_limit" ] }, "uniqueItems": true, "maxItems": 4 }, "records_examined": { "type": "integer", "minimum": 0, "maximum": 256 }, "record_bytes": { "type": "integer", "minimum": 0, "maximum": 8388608 }, "adjacency_entries_examined": { "type": "integer", "minimum": 0, "maximum": 4096 }, "relations_examined": { "type": "integer", "minimum": 0, "maximum": 4096 }, "relation_bytes": { "type": "integer", "minimum": 0, "maximum": 4194304 }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "complete", "stop_reasons", "records_examined", "record_bytes", "adjacency_entries_examined", "relations_examined", "relation_bytes", "dependency_work" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "complete": { "const": true } } }, "then": { "properties": { "stop_reasons": { "maxItems": 0 } } }, "else": { "properties": { "stop_reasons": { "minItems": 1 } } } } ], "description": "Coverage of the selected directed typed neighborhood at one snapshot and clock, not a ranking or whole-volume audit. Depth cuts can leave endpoint eligibility unexamined. Physical adjacency work includes filtered, repeated and stale assertions; valid edge limits are separate. Integrity and lookahead bytes are additional." }, "TypedMemoryGraph": { "type": "object", "properties": { "traversal_version": { "type": "string", "const": "typed_relations_v1" }, "evaluated_at_millis": { "type": "integer", "format": "int64" }, "direction": { "$ref": "#/components/schemas/TypedGraphDirection" }, "relation_kinds": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRelationKind" }, "minItems": 1, "maxItems": 6, "uniqueItems": true }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 8 }, "node_limit": { "type": "integer", "minimum": 1, "maximum": 256 }, "edge_limit": { "type": "integer", "minimum": 1, "maximum": 1024 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 4096 }, "roots": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryGraphRoot" }, "minItems": 1, "maxItems": 16 }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryGraphNode" }, "maxItems": 256 }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRelation" }, "maxItems": 1024 }, "coverage": { "$ref": "#/components/schemas/TypedGraphCoverage" } }, "required": [ "traversal_version", "evaluated_at_millis", "direction", "relation_kinds", "max_depth", "node_limit", "edge_limit", "scan_limit", "roots", "nodes", "edges", "coverage" ], "additionalProperties": false }, "TypedMemoryGraphRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "query": { "$ref": "#/components/schemas/TypedMemoryGraphQuery" } }, "required": [ "contract_version", "scope", "query" ], "additionalProperties": false }, "TypedMemoryGraphResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "graph": { "$ref": "#/components/schemas/TypedMemoryGraph" } }, "required": [ "contract_version", "scope", "graph" ], "additionalProperties": false }, "CompanyTypedMemoryGraphRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "workspace_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "query": { "$ref": "#/components/schemas/TypedMemoryGraphQuery" } }, "required": [ "contract_version", "workspace_id", "query" ], "additionalProperties": false }, "CompanyTypedMemoryGraphResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "workspace": { "$ref": "#/components/schemas/CompanyMemoryWorkspace" }, "graph": { "$ref": "#/components/schemas/TypedMemoryGraph" } }, "required": [ "contract_version", "company_id", "workspace", "graph" ], "additionalProperties": false }, "CompanyMemoryRelationInspectRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "workspace_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "relation_id": { "type": "string", "format": "uuid" } }, "required": [ "contract_version", "workspace_id", "relation_id" ], "additionalProperties": false }, "CompanyMemoryRelationRevisionRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "workspace_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "relation_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "contract_version", "workspace_id", "relation_id", "revision" ], "additionalProperties": false }, "CompanyMemoryRelationInspectResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "workspace": { "$ref": "#/components/schemas/CompanyMemoryWorkspace" }, "inspection": { "$ref": "#/components/schemas/MemoryRelationInspection" } }, "required": [ "contract_version", "company_id", "workspace", "inspection" ], "additionalProperties": false }, "CompanyMemoryRelationRevisionResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "workspace": { "$ref": "#/components/schemas/CompanyMemoryWorkspace" }, "history": { "$ref": "#/components/schemas/MemoryRelationRevision" } }, "required": [ "contract_version", "company_id", "workspace", "history" ], "additionalProperties": false }, "MemoryRelationKind": { "type": "string", "enum": [ "semantic_related", "same_entity", "temporal_before", "causal_claim", "supports", "contradicts" ], "description": "Directed source-to-target assertions. Symmetry or causation is not inferred. temporal_before additionally checks strict endpoint event-time order." }, "RelationOrigin": { "type": "string", "enum": [ "model_inference", "tool_observation", "human_statement", "imported_assertion" ], "description": "Reporter-declared origin; this field does not authenticate a human, certify a tool result or establish external truth." }, "RelationModelIdentity": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "model": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "revision": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." } }, "required": [ "provider", "model", "revision" ], "additionalProperties": false }, "RelationProvenance": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/RelationOrigin" }, "method": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "method_revision": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "evidence_ref": { "type": "string", "minLength": 1, "description": "1–2048 UTF-8 bytes, not blank and without control characters." }, "model": { "anyOf": [ { "$ref": "#/components/schemas/RelationModelIdentity" }, { "type": "null" } ] } }, "required": [ "origin", "method", "method_revision", "evidence_ref" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "origin": { "const": "model_inference" } }, "required": [ "origin" ] }, "then": { "properties": { "model": { "$ref": "#/components/schemas/RelationModelIdentity" } }, "required": [ "model" ] } } ] }, "MemoryRelationInput": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/MemorySourceRef" }, "target": { "$ref": "#/components/schemas/MemorySourceRef" }, "kind": { "$ref": "#/components/schemas/MemoryRelationKind" }, "provenance": { "$ref": "#/components/schemas/RelationProvenance" }, "valid_from_millis": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "null" } ] }, "valid_until_millis": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "null" } ] } }, "required": [ "source", "target", "kind", "provenance" ], "additionalProperties": false, "description": "Immutable revision-bound directed assertion. Endpoints must be distinct current eligible records in the same authorized namespace. A configured validity interval is half-open and ordered. No embeddings or provider credentials are accepted." }, "MemoryRelationOperation": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "assert" }, "relation": { "$ref": "#/components/schemas/MemoryRelationInput" } }, "required": [ "type", "relation" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "retire" }, "relation_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "evidence_ref": { "type": "string", "minLength": 1, "description": "1–2048 UTF-8 bytes, not blank and without control characters." } }, "required": [ "type", "relation_id", "expected_revision", "evidence_ref" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "restore" }, "relation_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "evidence_ref": { "type": "string", "minLength": 1, "description": "1–2048 UTF-8 bytes, not blank and without control characters." } }, "required": [ "type", "relation_id", "expected_revision", "evidence_ref" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "review" }, "relation_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "evidence_ref": { "type": "string", "minLength": 1, "description": "1–2048 UTF-8 bytes, not blank and without control characters." }, "disposition": { "$ref": "#/components/schemas/MemoryReviewDisposition" } }, "required": [ "type", "relation_id", "expected_revision", "evidence_ref", "disposition" ], "additionalProperties": false } ], "discriminator": { "propertyName": "type" }, "examples": [ { "type": "assert", "relation": { "source": { "record_id": "018f0000-0000-4000-8000-000000000001", "revision": 2 }, "target": { "record_id": "018f0000-0000-4000-8000-000000000002", "revision": 1 }, "kind": "supports", "provenance": { "origin": "model_inference", "method": "support-extraction", "method_revision": "prompt-v3", "evidence_ref": "trace://run-42/relation-1", "model": { "provider": "example-provider", "model": "example-model", "revision": "example-pinned-revision" } }, "valid_from_millis": null, "valid_until_millis": null } }, { "type": "retire", "relation_id": "018f0000-0000-4000-8000-000000000003", "expected_revision": 1, "evidence_ref": "review://case-42/withdrawal" }, { "type": "restore", "relation_id": "018f0000-0000-4000-8000-000000000003", "expected_revision": 2, "evidence_ref": "review://case-42/withdrawal" }, { "type": "review", "relation_id": "018f0000-0000-4000-8000-000000000003", "expected_revision": 3, "evidence_ref": "review://case-42/withdrawal", "disposition": "approved" } ] }, "MemoryRelationCommandRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "operation": { "$ref": "#/components/schemas/MemoryRelationOperation" } }, "required": [ "contract_version", "scope", "idempotency_key", "operation" ], "additionalProperties": false }, "MemoryRelationReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "relation_id": { "type": "string", "format": "uuid" } }, "required": [ "contract_version", "scope", "relation_id" ], "additionalProperties": false }, "MemoryRelationRevisionRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "relation_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "contract_version", "scope", "relation_id", "revision" ], "additionalProperties": false }, "MemoryRelation": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "relation_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "input": { "$ref": "#/components/schemas/MemoryRelationInput" }, "reported_by": { "$ref": "#/components/schemas/Author" }, "created_at_millis": { "type": "integer", "format": "int64" }, "modified_at_millis": { "type": "integer", "format": "int64" }, "state": { "type": "string", "enum": [ "active", "retired" ] }, "review": { "anyOf": [ { "$ref": "#/components/schemas/MemoryReview" }, { "type": "null" } ] } }, "required": [ "schema_version", "relation_id", "revision", "input", "reported_by", "created_at_millis", "modified_at_millis", "state", "review" ], "additionalProperties": false }, "MemoryRelationReceipt": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "relation_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "action": { "type": "string", "enum": [ "asserted", "retired", "restored", "reviewed" ] }, "author": { "$ref": "#/components/schemas/Author" }, "committed_at_millis": { "type": "integer", "format": "int64" }, "evidence_ref": { "type": "string", "minLength": 1, "description": "1–2048 UTF-8 bytes, not blank and without control characters." }, "relation_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "command_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "receipt_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "contract_version", "idempotency_key", "relation_id", "revision", "action", "author", "committed_at_millis", "evidence_ref", "relation_digest", "command_digest", "receipt_digest" ], "additionalProperties": false }, "RelationEligibility": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "eligible", "retired", "rejected", "not_yet_valid", "expired", "endpoint_unavailable", "endpoint_revision_changed" ] }, "evaluated_at_millis": { "type": "integer", "format": "int64" }, "endpoint": { "anyOf": [ { "$ref": "#/components/schemas/MemorySourceRef" }, { "type": "null" } ] }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "eligible", "reason", "evaluated_at_millis", "endpoint", "dependency_work" ], "additionalProperties": false }, "MemoryRelationInspection": { "type": "object", "properties": { "relation": { "$ref": "#/components/schemas/MemoryRelation" }, "eligibility": { "$ref": "#/components/schemas/RelationEligibility" } }, "required": [ "relation", "eligibility" ], "additionalProperties": false }, "MemoryRelationRevision": { "type": "object", "properties": { "relation": { "$ref": "#/components/schemas/MemoryRelation" }, "receipt": { "$ref": "#/components/schemas/MemoryRelationReceipt" } }, "required": [ "relation", "receipt" ], "additionalProperties": false }, "MemoryRelationCommandsResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/MemoryRelationReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "MemoryRelationReadResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "relation": { "$ref": "#/components/schemas/MemoryRelation" }, "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "contract_version", "relation", "scope" ], "additionalProperties": false }, "MemoryRelationInspectResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "inspection": { "$ref": "#/components/schemas/MemoryRelationInspection" }, "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "contract_version", "inspection", "scope" ], "additionalProperties": false }, "MemoryRelationRevisionResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "history": { "$ref": "#/components/schemas/MemoryRelationRevision" }, "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "contract_version", "history", "scope" ], "additionalProperties": false }, "MemoryRelationNotFoundError": { "description": "No relation or requested historical revision is available under the current authorized read contract.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "const": "record_not_found" } } } } } ] }, "MemoryRelationConflictError": { "description": "Endpoint or relation revisions are no longer admissible, or a different command reuses an already committed idempotency key.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "revision_conflict", "idempotency_conflict" ] } } } } } ] }, "Capability": { "type": "string", "enum": [ "memory_read", "memory_write", "procedure_propose", "procedure_evaluate", "policy_admin", "credential_admin", "tool_read", "tool_develop", "tool_report", "tool_admin", "experience_read", "experience_write", "experience_report", "memory_review", "memory_checkpoint" ] }, "Visibility": { "type": "string", "enum": [ "private", "shared" ] }, "Scope": { "type": "object", "properties": { "project_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "mission_id": { "anyOf": [ { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, { "type": "null" } ] }, "agent_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "visibility": { "$ref": "#/components/schemas/Visibility" } }, "required": [ "project_id", "agent_id", "visibility" ], "additionalProperties": false }, "CredentialSpec": { "type": "object", "properties": { "subject_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" }, "minItems": 1 }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "expires_at_millis": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "null" } ] }, "scope_policy": { "anyOf": [ { "$ref": "#/components/schemas/CompanyScopePolicy" }, { "type": "null" } ], "description": "Omitted or null preserves legacy exact-grant authorization. Never inferred from empty grants. A company policy requires grants=[] and excludes credential_admin." } }, "required": [ "subject_id", "capabilities", "grants" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "scope_policy" ], "properties": { "scope_policy": { "type": "object" } } }, "then": { "properties": { "grants": { "maxItems": 0 }, "capabilities": { "not": { "contains": { "const": "credential_admin" } } } } } } ] }, "CredentialEvent": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "action": { "type": "string", "enum": [ "bootstrapped", "issued", "rotated", "revoked", "tenant_registered_by_global_authority", "admin_issued_by_global_authority", "scope_authority_changed" ] }, "actor_id": { "type": "string", "format": "uuid" }, "at_millis": { "type": "integer", "format": "int64" }, "scope_authority_change": { "$ref": "#/components/schemas/ScopeAuthorityChange" } }, "required": [ "revision", "action", "actor_id", "at_millis" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "action": { "const": "scope_authority_changed" } } }, "then": { "required": [ "scope_authority_change" ] }, "else": { "not": { "required": [ "scope_authority_change" ] } } } ] }, "Credential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "spec": { "$ref": "#/components/schemas/CredentialSpec" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "revoked_at_millis": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialEvent" } } }, "required": [ "id", "tenant_id", "spec", "revision", "revoked_at_millis", "history" ], "additionalProperties": false }, "CredentialResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "credential": { "$ref": "#/components/schemas/Credential" } }, "required": [ "contract_version", "credential" ], "additionalProperties": false }, "IssuedCredential": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "credential": { "$ref": "#/components/schemas/Credential" }, "secret": { "type": "string", "pattern": "^qdb1_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$", "description": "Returned once. Store securely; never log." } }, "required": [ "contract_version", "credential", "secret" ], "additionalProperties": false }, "IssueRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "spec": { "$ref": "#/components/schemas/CredentialSpec" } }, "required": [ "contract_version", "spec" ], "additionalProperties": false, "examples": [ { "contract_version": 1, "spec": { "subject_id": "research-agent-user", "capabilities": [ "memory_read", "memory_write", "procedure_propose" ], "grants": [ { "project_id": "research", "mission_id": "mission-42", "agent_id": "researcher", "visibility": "shared" } ], "expires_at_millis": null } } ] }, "RevisionRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "contract_version", "expected_revision" ], "additionalProperties": false }, "EpisodeType": { "oneOf": [ { "type": "string", "enum": [ "Conversation", "TaskExecution", "Observation", "Decision", "Error" ] }, { "type": "object", "properties": { "Custom": { "type": "string" } }, "required": [ "Custom" ], "additionalProperties": false } ] }, "EpisodeContent": { "type": "object", "properties": { "primary": { "type": "string" }, "secondary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data": {}, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number", "minimum": -3.4028234663852886e+38, "maximum": 3.4028234663852886e+38 } }, { "type": "null" } ] } }, "required": [ "primary" ], "additionalProperties": false }, "RecordInput": { "type": "object", "properties": { "episode_type": { "$ref": "#/components/schemas/EpisodeType" }, "content": { "$ref": "#/components/schemas/EpisodeContent" }, "event_time_millis": { "type": "integer", "format": "int64", "description": "Unix milliseconds in the supported calendar range." }, "valid_until_millis": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "episode_type", "content", "event_time_millis" ], "additionalProperties": false }, "CreateOperation": { "type": "object", "properties": { "type": { "const": "create" }, "record": { "$ref": "#/components/schemas/RecordInput" } }, "required": [ "type", "record" ], "additionalProperties": false }, "UpdateOperation": { "type": "object", "properties": { "type": { "const": "update" }, "record_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "record": { "$ref": "#/components/schemas/RecordInput" } }, "required": [ "type", "record_id", "expected_revision", "record" ], "additionalProperties": false }, "DeleteOperation": { "type": "object", "properties": { "type": { "const": "delete" }, "record_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "type", "record_id", "expected_revision" ], "additionalProperties": false }, "MemoryOperation": { "oneOf": [ { "$ref": "#/components/schemas/CreateOperation" }, { "$ref": "#/components/schemas/UpdateOperation" }, { "$ref": "#/components/schemas/DeleteOperation" }, { "$ref": "#/components/schemas/DeriveOperation" } ], "discriminator": { "propertyName": "type", "mapping": { "create": "#/components/schemas/CreateOperation", "update": "#/components/schemas/UpdateOperation", "delete": "#/components/schemas/DeleteOperation", "derive": "#/components/schemas/DeriveOperation" } } }, "MemoryCommand": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes; not blank; no control characters. Scoped by authenticated tenant, namespace and subject." }, "scope": { "$ref": "#/components/schemas/Scope" }, "operation": { "$ref": "#/components/schemas/MemoryOperation" } }, "required": [ "contract_version", "idempotency_key", "scope", "operation" ], "additionalProperties": false, "examples": [ { "contract_version": 1, "idempotency_key": "session-42-observation-1", "scope": { "project_id": "research", "mission_id": "mission-42", "agent_id": "researcher", "visibility": "shared" }, "operation": { "type": "create", "record": { "episode_type": "Observation", "event_time_millis": 1700000000000, "content": { "primary": "The tool returned three matching documents.", "data": { "document_ids": [ "paper-a", "paper-b", "paper-c" ] } }, "tags": [ "literature" ], "metadata": { "source_request_id": "tool-call-17" } } } } ] }, "Author": { "type": "object", "properties": { "credential_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." } }, "required": [ "credential_id", "subject_id" ], "additionalProperties": false }, "Receipt": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string" }, "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "action": { "type": "string", "enum": [ "created", "updated", "deleted", "derived" ] }, "committed_at_millis": { "type": "integer", "format": "int64" }, "author": { "$ref": "#/components/schemas/Author" } }, "required": [ "contract_version", "idempotency_key", "record_id", "revision", "action", "committed_at_millis", "author" ], "additionalProperties": false }, "ReceiptResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "MemoryRecord": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "created_at_millis": { "type": "integer", "format": "int64" }, "modified_at_millis": { "type": "integer", "format": "int64" }, "author": { "$ref": "#/components/schemas/Author" }, "payload": { "$ref": "#/components/schemas/RecordInput" }, "review": { "anyOf": [ { "$ref": "#/components/schemas/MemoryReview" }, { "type": "null" } ] }, "derivation": { "anyOf": [ { "$ref": "#/components/schemas/MemoryDerivation" }, { "type": "null" } ] } }, "required": [ "schema_version", "record_id", "revision", "created_at_millis", "modified_at_millis", "author", "payload" ], "additionalProperties": false }, "RecordResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "record": { "$ref": "#/components/schemas/MemoryRecord" } }, "required": [ "contract_version", "scope", "record" ], "additionalProperties": false }, "MemoryFilter": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 1000 }, "after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "text_contains": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "episode_type": { "anyOf": [ { "$ref": "#/components/schemas/EpisodeType" }, { "type": "null" } ] }, "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 10000, "description": "Maximum examined candidate records, including unavailable records. Reduce this bound to limit per-page dependency validation work." } }, "required": [ "limit" ], "additionalProperties": false }, "QueryRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "filter": { "$ref": "#/components/schemas/MemoryFilter" } }, "required": [ "contract_version", "scope", "filter" ], "additionalProperties": false, "examples": [ { "contract_version": 1, "scope": { "project_id": "research", "mission_id": "mission-42", "agent_id": "researcher", "visibility": "shared" }, "filter": { "limit": 20, "text_contains": "documents" } } ] }, "QueryPage": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecord" } }, "next_after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "scanned_records": { "type": "integer", "minimum": 0, "maximum": 10000 }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "records", "next_after", "scanned_records" ], "additionalProperties": false }, "QueryResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "page": { "$ref": "#/components/schemas/QueryPage" } }, "required": [ "contract_version", "scope", "page" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "method_not_allowed", "invalid_request", "unsupported_contract_version", "revision_conflict", "record_not_found", "idempotency_conflict", "storage_inconsistency", "internal_error", "journal_history_conflict", "checkpoint_regression", "checkpoint_not_found", "recovery_not_found", "embedding_dimension_limit", "retrieval_scan_limit", "retrieval_busy", "review_not_found", "tenant_not_found", "invalid_login", "login_rate_limited", "login_busy" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "contract_version", "error" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "status": { "type": "string", "const": "healthy" }, "version": { "type": "string" } }, "required": [ "contract_version", "status", "version" ], "additionalProperties": false }, "LearningPolicy": { "type": "object", "additionalProperties": false, "properties": { "qualification_trials": { "type": "integer", "minimum": 2, "maximum": 1000000 }, "confidence_delta": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 0.5 }, "min_improvement": { "type": "number", "minimum": 0, "maximum": 1 }, "min_candidate_utility": { "type": "number", "minimum": 0, "maximum": 1 }, "max_cost_units": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "max_latency_ms": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "max_failure_streak": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "evaluator_id": { "type": "string", "minLength": 1 }, "evaluation_contract": { "type": "string", "minLength": 1 } }, "required": [ "qualification_trials", "confidence_delta", "min_improvement", "min_candidate_utility", "max_cost_units", "max_latency_ms", "max_failure_streak", "evaluator_id", "evaluation_contract" ] }, "PolicyDefinition": { "type": "object", "additionalProperties": false, "properties": { "algorithm": { "type": "string", "enum": [ "fixed_budget_hoeffding_v1" ] }, "parameters": { "$ref": "#/components/schemas/LearningPolicy" } }, "required": [ "algorithm", "parameters" ] }, "EvaluationContext": { "type": "object", "additionalProperties": false, "properties": { "task": { "type": "string", "minLength": 1 }, "baseline_revision": { "type": "string", "minLength": 1 }, "model_provider": { "type": "string", "minLength": 1 }, "model_revision": { "type": "string", "minLength": 1 }, "environment_revision": { "type": "string", "minLength": 1 }, "evaluation_contract": { "type": "string", "minLength": 1 }, "dataset_revision": { "type": "string", "minLength": 1 }, "harness_revision": { "type": "string", "minLength": 1 }, "permissions_revision": { "type": "string", "minLength": 1 }, "tools": { "type": "object", "maxProperties": 128, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": [ "task", "baseline_revision", "model_provider", "model_revision", "environment_revision", "evaluation_contract", "dataset_revision", "harness_revision", "permissions_revision", "tools" ] }, "PolicyEntry": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "payload": { "$ref": "#/components/schemas/PolicyDefinition" }, "payload_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "registered_by": { "type": "string", "minLength": 1 }, "recorded_at_millis": { "type": "integer" } }, "required": [ "schema_version", "tenant", "id", "payload", "payload_digest", "registered_by", "recorded_at_millis" ] }, "ContextEntry": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "payload": { "$ref": "#/components/schemas/EvaluationContext" }, "payload_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "registered_by": { "type": "string", "minLength": 1 }, "recorded_at_millis": { "type": "integer" } }, "required": [ "schema_version", "tenant", "id", "payload", "payload_digest", "registered_by", "recorded_at_millis" ] }, "LearningScope": { "type": "object", "additionalProperties": false, "properties": { "tenant": { "type": "string", "minLength": 1 }, "agent": { "type": "string", "minLength": 1 }, "environment": { "type": "string", "minLength": 1 } }, "required": [ "tenant", "agent", "environment" ] }, "ProcedureState": { "type": "string", "enum": [ "Candidate", "Active", "Rejected", "Suspended" ] }, "EvaluationPhase": { "type": "string", "enum": [ "Qualification", "Monitoring" ] }, "ProcedureProposal": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "task": { "type": "string", "minLength": 1 }, "baseline_revision": { "type": "string", "minLength": 1 }, "instructions": { "type": "string", "minLength": 1 }, "source_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "policy": { "$ref": "#/components/schemas/LearningPolicy" } }, "required": [ "id", "task", "baseline_revision", "instructions", "source_refs", "policy" ] }, "LearningDecision": { "type": "object", "additionalProperties": false, "properties": { "from": { "$ref": "#/components/schemas/ProcedureState" }, "to": { "$ref": "#/components/schemas/ProcedureState" }, "reason": { "type": "string", "minLength": 1 }, "triggering_case": { "type": "string", "minLength": 1 }, "recorded_at_millis": { "type": "integer" } }, "required": [ "from", "to", "reason", "triggering_case", "recorded_at_millis" ] }, "ProcedureRecord": { "type": "object", "additionalProperties": false, "properties": { "scope": { "$ref": "#/components/schemas/LearningScope" }, "proposal": { "$ref": "#/components/schemas/ProcedureProposal" }, "state": { "$ref": "#/components/schemas/ProcedureState" }, "qualification_count": { "type": "integer", "minimum": 0 }, "mean_improvement": { "type": "number" }, "mean_candidate_utility": { "type": "number" }, "budget_violations": { "type": "integer", "minimum": 0 }, "lower_improvement_bound": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monitoring_count": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "failure_streak": { "type": "integer", "minimum": 0 }, "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/LearningDecision" } }, "created_at_millis": { "type": "integer" } }, "required": [ "scope", "proposal", "state", "qualification_count", "mean_improvement", "mean_candidate_utility", "budget_violations", "lower_improvement_bound", "monitoring_count", "failure_streak", "decisions", "created_at_millis" ] }, "RegisteredProposal": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "policy_id": { "type": "string", "minLength": 1 }, "context_id": { "type": "string", "minLength": 1 }, "instructions": { "type": "string", "minLength": 1 }, "source_refs": { "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "string", "minLength": 1 } } }, "required": [ "id", "policy_id", "context_id", "instructions", "source_refs" ] }, "ProposalReceipt": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1 }, "namespace": { "type": "string", "minLength": 1 }, "request": { "$ref": "#/components/schemas/RegisteredProposal" }, "policy_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "context_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "actor": { "type": "string", "minLength": 1 }, "record": { "$ref": "#/components/schemas/ProcedureRecord" } }, "required": [ "schema_version", "tenant", "namespace", "request", "policy_digest", "context_digest", "actor", "record" ] }, "RegisteredProcedure": { "type": "object", "additionalProperties": false, "properties": { "receipt": { "$ref": "#/components/schemas/ProposalReceipt" }, "record": { "$ref": "#/components/schemas/ProcedureRecord" } }, "required": [ "receipt", "record" ] }, "PairedEvaluation": { "type": "object", "additionalProperties": false, "properties": { "case_id": { "type": "string", "minLength": 1 }, "phase": { "$ref": "#/components/schemas/EvaluationPhase" }, "evaluator_id": { "type": "string", "minLength": 1 }, "evaluation_contract": { "type": "string", "minLength": 1 }, "evidence_ref": { "type": "string", "minLength": 1 }, "baseline_utility": { "type": "number", "minimum": 0, "maximum": 1 }, "candidate_utility": { "type": "number", "minimum": 0, "maximum": 1 }, "candidate_cost_units": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "candidate_latency_ms": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 } }, "required": [ "case_id", "phase", "evaluator_id", "evaluation_contract", "evidence_ref", "baseline_utility", "candidate_utility", "candidate_cost_units", "candidate_latency_ms" ] }, "EvaluationReceipt": { "type": "object", "additionalProperties": false, "properties": { "evaluation": { "$ref": "#/components/schemas/PairedEvaluation" }, "state_after": { "$ref": "#/components/schemas/ProcedureState" }, "recorded_at_millis": { "type": "integer" } }, "required": [ "evaluation", "state_after", "recorded_at_millis" ] }, "EvaluationActor": { "type": "object", "additionalProperties": false, "properties": { "subject_id": { "type": "string", "minLength": 1 }, "credential_id": { "type": "string", "minLength": 1 } }, "required": [ "subject_id", "credential_id" ] }, "EvaluationSubmission": { "type": "object", "additionalProperties": false, "properties": { "case_id": { "type": "string", "minLength": 1 }, "phase": { "$ref": "#/components/schemas/EvaluationPhase" }, "policy_id": { "type": "string", "minLength": 1 }, "context_id": { "type": "string", "minLength": 1 }, "baseline_revision": { "type": "string", "minLength": 1 }, "evidence_ref": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "complete", "rejected", "incomplete", "cancelled", "pending_or_unknown" ] }, "baseline_utility": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "candidate_utility": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "candidate_cost_units": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "candidate_latency_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "detail": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "case_id", "phase", "policy_id", "context_id", "baseline_revision", "evidence_ref", "status" ] }, "AdmissionReceipt": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1 }, "namespace": { "type": "string", "minLength": 1 }, "procedure_id": { "type": "string", "minLength": 1 }, "actor": { "$ref": "#/components/schemas/EvaluationActor" }, "submission": { "$ref": "#/components/schemas/EvaluationSubmission" }, "outcome": { "type": "string", "enum": [ "accepted", "rejected", "incomplete", "cancelled", "pending_or_unknown", "unknown_consumption" ] }, "reason": { "type": "string", "minLength": 1 }, "state_after": { "$ref": "#/components/schemas/ProcedureState" }, "evaluation": { "anyOf": [ { "$ref": "#/components/schemas/EvaluationReceipt" }, { "type": "null" } ] }, "recorded_at_millis": { "type": "integer" } }, "required": [ "schema_version", "tenant", "namespace", "procedure_id", "actor", "submission", "outcome", "reason", "state_after", "evaluation", "recorded_at_millis" ] }, "LearningPolicyRequest": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "id": { "type": "string", "minLength": 1 }, "definition": { "$ref": "#/components/schemas/PolicyDefinition" } }, "required": [ "contract_version", "id", "definition" ] }, "LearningContextRequest": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "id": { "type": "string", "minLength": 1 }, "context": { "$ref": "#/components/schemas/EvaluationContext" } }, "required": [ "contract_version", "id", "context" ] }, "LearningProposalRequest": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "proposal": { "$ref": "#/components/schemas/RegisteredProposal" } }, "required": [ "contract_version", "scope", "proposal" ] }, "LearningReadRequest": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "procedure_id": { "type": "string", "minLength": 1 } }, "required": [ "contract_version", "scope", "procedure_id" ] }, "LearningEvaluationRequest": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "procedure_id": { "type": "string", "minLength": 1 }, "submission": { "$ref": "#/components/schemas/EvaluationSubmission" } }, "required": [ "contract_version", "scope", "procedure_id", "submission" ] }, "LearningReceiptRequest": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "procedure_id": { "type": "string", "minLength": 1 }, "case_id": { "type": "string", "minLength": 1 } }, "required": [ "contract_version", "scope", "procedure_id", "case_id" ] }, "LearningSelectRequest": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "policy_id": { "type": "string", "minLength": 1 }, "context_id": { "type": "string", "minLength": 1 }, "max_instruction_bytes": { "type": "integer", "minimum": 0, "maximum": 65536 } }, "required": [ "contract_version", "scope", "policy_id", "context_id", "max_instruction_bytes" ] }, "PolicyEntryResponse": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "entry": { "$ref": "#/components/schemas/PolicyEntry" } }, "required": [ "contract_version", "entry" ] }, "ContextEntryResponse": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "entry": { "$ref": "#/components/schemas/ContextEntry" } }, "required": [ "contract_version", "entry" ] }, "ProposalResponse": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/ProposalReceipt" } }, "required": [ "contract_version", "receipt" ] }, "ProcedureResponse": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "procedure": { "$ref": "#/components/schemas/RegisteredProcedure" } }, "required": [ "contract_version", "procedure" ] }, "AdmissionResponse": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/AdmissionReceipt" } }, "required": [ "contract_version", "receipt" ] }, "LearningSelectionResponse": { "type": "object", "additionalProperties": false, "properties": { "contract_version": { "type": "integer", "const": 1 }, "policy_id": { "type": "string", "minLength": 1 }, "context_id": { "type": "string", "minLength": 1 }, "selection": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "procedure" }, "procedure": { "$ref": "#/components/schemas/RegisteredProcedure" } }, "required": [ "type", "procedure" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "baseline" }, "baseline_revision": { "type": "string", "minLength": 1 }, "reason": { "const": "no_qualified_compatible_procedure" } }, "required": [ "type", "baseline_revision", "reason" ] } ] } }, "required": [ "contract_version", "policy_id", "context_id", "selection" ] }, "ToolActor": { "type": "object", "properties": { "subject_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "credential_id": { "type": "string", "format": "uuid" } }, "required": [ "subject_id", "credential_id" ], "additionalProperties": false }, "ToolArtifactProposal": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "source": { "type": "string", "minLength": 1, "maxLength": 24576, "description": "At most 24576 UTF-8 bytes; byte limits are enforced by the server." }, "dependency_lock": { "type": "string", "minLength": 0, "maxLength": 8192, "description": "At most 8192 UTF-8 bytes; byte limits are enforced by the server." }, "runtime_image_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "entrypoint": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "input_schema": { "type": [ "object", "boolean" ], "description": "Declared schema, at most 8192 serialized bytes; not executed or compiled by this endpoint." }, "output_schema": { "type": [ "object", "boolean" ], "description": "Declared schema, at most 8192 serialized bytes." }, "source_refs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "At most 2048 UTF-8 bytes; byte limits are enforced by the server." }, "minItems": 1, "maxItems": 32 }, "parent_artifact_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, { "type": "null" } ] }, "repair_evidence_ref": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "description": "At most 2048 UTF-8 bytes; byte limits are enforced by the server." }, { "type": "null" } ] } }, "required": [ "id", "source", "dependency_lock", "runtime_image_digest", "entrypoint", "input_schema", "output_schema", "source_refs" ], "additionalProperties": false }, "ToolArtifact": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "namespace": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes; byte limits are enforced by the server." }, "proposal": { "$ref": "#/components/schemas/ToolArtifactProposal" }, "artifact_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "source_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "dependency_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "actor": { "$ref": "#/components/schemas/ToolActor" }, "recorded_at_millis": { "type": "integer", "format": "int64" } }, "required": [ "schema_version", "tenant", "namespace", "proposal", "artifact_digest", "source_digest", "dependency_digest", "actor", "recorded_at_millis" ], "additionalProperties": false }, "ToolExecutorProfile": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "subject_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "runtime_image_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "environment_revision": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "permissions_revision": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "max_cost_units": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "max_latency_ms": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "id", "subject_id", "runtime_image_digest", "environment_revision", "permissions_revision", "max_cost_units", "max_latency_ms" ], "additionalProperties": false }, "ToolExecutor": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "profile": { "$ref": "#/components/schemas/ToolExecutorProfile" }, "profile_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "actor": { "$ref": "#/components/schemas/ToolActor" }, "recorded_at_millis": { "type": "integer", "format": "int64" } }, "required": [ "schema_version", "tenant", "profile", "profile_digest", "actor", "recorded_at_millis" ], "additionalProperties": false }, "ToolDevelopmentRequest": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "executor_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "objective": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "At most 8192 UTF-8 bytes; byte limits are enforced by the server." }, "parent_artifact_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, { "type": "null" } ] }, "repair_evidence_ref": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "description": "At most 2048 UTF-8 bytes; byte limits are enforced by the server." }, { "type": "null" } ] } }, "required": [ "id", "executor_id", "objective" ], "additionalProperties": false }, "ToolDevelopmentReceipt": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "namespace": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes; byte limits are enforced by the server." }, "request": { "$ref": "#/components/schemas/ToolDevelopmentRequest" }, "request_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "executor_profile_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "actor": { "$ref": "#/components/schemas/ToolActor" }, "recorded_at_millis": { "type": "integer", "format": "int64" } }, "required": [ "schema_version", "tenant", "namespace", "request", "request_digest", "executor_profile_digest", "actor", "recorded_at_millis" ], "additionalProperties": false }, "ToolDevelopment": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/ToolDevelopmentReceipt" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "state": { "type": "string", "enum": [ "requested", "pending_or_unknown", "cancellation_requested", "succeeded", "failed", "cancelled" ] }, "reason": { "type": "string" }, "last_event_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, { "type": "null" } ] }, "artifact_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, { "type": "null" } ] }, "artifact_digest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "cost_units": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "latency_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "observed_cost_units": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "observed_latency_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] } }, "required": [ "receipt", "revision", "state", "reason", "last_event_id", "artifact_id", "artifact_digest", "cost_units", "latency_ms", "observed_cost_units", "observed_latency_ms" ], "additionalProperties": false }, "ToolDevelopmentReport": { "type": "object", "properties": { "executor_profile_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "outcome": { "type": "string", "enum": [ "pending_or_unknown", "succeeded", "failed", "cancelled" ] }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "At most 2048 UTF-8 bytes; byte limits are enforced by the server." }, "detail": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "description": "At most 8192 UTF-8 bytes; byte limits are enforced by the server." }, { "type": "null" } ] }, "cost_units": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "latency_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "artifact": { "anyOf": [ { "$ref": "#/components/schemas/ToolArtifactProposal" }, { "type": "null" } ] } }, "required": [ "executor_profile_digest", "outcome", "evidence_ref" ], "additionalProperties": false }, "ToolDevelopmentAction": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "report" }, "report": { "$ref": "#/components/schemas/ToolDevelopmentReport" } }, "required": [ "type", "report" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "request_cancellation" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "At most 2048 UTF-8 bytes; byte limits are enforced by the server." } }, "required": [ "type", "reason" ], "additionalProperties": false } ] }, "ToolDevelopmentCommand": { "type": "object", "properties": { "event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "expected_revision": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "action": { "$ref": "#/components/schemas/ToolDevelopmentAction" } }, "required": [ "event_id", "expected_revision", "action" ], "additionalProperties": false }, "ToolDevelopmentEvent": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "command": { "$ref": "#/components/schemas/ToolDevelopmentCommand" }, "actor": { "$ref": "#/components/schemas/ToolActor" }, "record": { "$ref": "#/components/schemas/ToolDevelopment" }, "recorded_at_millis": { "type": "integer", "format": "int64" } }, "required": [ "schema_version", "command", "actor", "record", "recorded_at_millis" ], "additionalProperties": false }, "ToolArtifactRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "artifact": { "$ref": "#/components/schemas/ToolArtifactProposal" } }, "required": [ "contract_version", "scope", "artifact" ], "additionalProperties": false }, "ToolArtifactRead": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "artifact_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." } }, "required": [ "contract_version", "scope", "artifact_id" ], "additionalProperties": false }, "ToolExecutorRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "profile": { "$ref": "#/components/schemas/ToolExecutorProfile" } }, "required": [ "contract_version", "profile" ], "additionalProperties": false }, "ToolDevelopmentCreate": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "request": { "$ref": "#/components/schemas/ToolDevelopmentRequest" } }, "required": [ "contract_version", "scope", "request" ], "additionalProperties": false }, "ToolDevelopmentRead": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." } }, "required": [ "contract_version", "scope", "request_id" ], "additionalProperties": false }, "ToolCommandRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "command": { "$ref": "#/components/schemas/ToolDevelopmentCommand" } }, "required": [ "contract_version", "scope", "request_id", "command" ], "additionalProperties": false }, "ToolEventRead": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." }, "event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes; byte limits are enforced by the server." } }, "required": [ "contract_version", "scope", "request_id", "event_id" ], "additionalProperties": false }, "ToolArtifactResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "artifact": { "$ref": "#/components/schemas/ToolArtifact" } }, "required": [ "contract_version", "artifact" ], "additionalProperties": false }, "ToolExecutorResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "executor": { "$ref": "#/components/schemas/ToolExecutor" } }, "required": [ "contract_version", "executor" ], "additionalProperties": false }, "ToolDevelopmentReceiptResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/ToolDevelopmentReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "ToolDevelopmentResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "development": { "$ref": "#/components/schemas/ToolDevelopment" } }, "required": [ "contract_version", "development" ], "additionalProperties": false }, "ToolEventResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "event": { "$ref": "#/components/schemas/ToolDevelopmentEvent" } }, "required": [ "contract_version", "event" ], "additionalProperties": false }, "EmbeddingSpace": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, without control characters." }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, without control characters." }, "revision": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, without control characters." }, "dimensions": { "type": "integer", "minimum": 1, "maximum": 32768, "description": "Exact external vector dimensionality. The operator may configure a lower ceiling; discover execution_limits in the ranking catalog." } }, "required": [ "provider", "model", "revision", "dimensions" ], "additionalProperties": false }, "EmbeddingCommandRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, without control characters." }, "record_id": { "type": "string", "format": "uuid" }, "record_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "space": { "$ref": "#/components/schemas/EmbeddingSpace" }, "vector": { "type": "array", "items": { "type": "number", "minimum": -3.4028234663852886e+38, "maximum": 3.4028234663852886e+38 }, "minItems": 1, "maxItems": 32768, "description": "Finite float32 values, exact declared dimensionality, nonzero norm." } }, "required": [ "contract_version", "scope", "idempotency_key", "record_id", "record_revision", "space", "vector" ], "additionalProperties": false }, "EmbeddingReceipt": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, without control characters." }, "record_id": { "type": "string", "format": "uuid" }, "record_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "space": { "$ref": "#/components/schemas/EmbeddingSpace" }, "vector_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "author": { "$ref": "#/components/schemas/Author" }, "committed_at_millis": { "type": "integer", "format": "int64" } }, "required": [ "contract_version", "idempotency_key", "record_id", "record_revision", "space", "vector_digest", "author", "committed_at_millis" ], "additionalProperties": false }, "EmbeddingResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/EmbeddingReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "SemanticQuery": { "type": "object", "properties": { "space": { "$ref": "#/components/schemas/EmbeddingSpace" }, "vector": { "type": "array", "items": { "type": "number", "minimum": -3.4028234663852886e+38, "maximum": 3.4028234663852886e+38 }, "minItems": 1, "maxItems": 32768, "description": "Finite float32 values, exact declared dimensionality, nonzero norm." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "min_score": { "type": "number", "minimum": -1, "maximum": 1, "default": -1 }, "after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 10000, "description": "Maximum current-record candidates in the authorized tag/type partition (default 10000). Deleted and directly rejected records do not consume this budget; expired or transitively ineligible candidates can. Semantic candidates without the selected embedding space also consume this budget." }, "episode_type": { "anyOf": [ { "$ref": "#/components/schemas/EpisodeType" }, { "type": "null" } ] }, "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "space", "vector", "limit" ], "additionalProperties": false }, "SemanticRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "query": { "$ref": "#/components/schemas/SemanticQuery" } }, "required": [ "contract_version", "scope", "query" ], "additionalProperties": false }, "SemanticHit": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/MemoryRecord" }, "score": { "type": "number", "minimum": -1, "maximum": 1, "description": "Cosine similarity, not a probability." }, "embedding": { "$ref": "#/components/schemas/EmbeddingReceipt" } }, "required": [ "record", "score", "embedding" ], "additionalProperties": false }, "SemanticPage": { "type": "object", "properties": { "hits": { "type": "array", "items": { "$ref": "#/components/schemas/SemanticHit" }, "maxItems": 100 }, "next_after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "scanned_embeddings": { "type": "integer", "minimum": 0, "description": "Selected-space bindings decoded for eligible current candidates, including stale bindings. Excludes deleted/rejected records and other tag/type partitions." }, "matched_records": { "type": "integer", "minimum": 0 }, "exhaustive": { "type": "boolean", "description": "True only for a cursorless complete current-candidate scan; does not assert that all memories have a current embedding." }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "hits", "next_after", "scanned_embeddings", "matched_records", "exhaustive" ], "additionalProperties": false }, "SemanticResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "page": { "$ref": "#/components/schemas/SemanticPage" } }, "required": [ "contract_version", "scope", "page" ], "additionalProperties": false }, "LexicalQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 10000, "description": "Maximum current-record candidates in the authorized tag/type partition (default 10000). Deleted and directly rejected records do not consume this budget; expired or transitively ineligible candidates can. Semantic candidates without the selected embedding space also consume this budget." }, "after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "episode_type": { "anyOf": [ { "$ref": "#/components/schemas/EpisodeType" }, { "type": "null" } ] }, "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes and 1–64 distinct lowercase Unicode alphanumeric terms; punctuation-only text is invalid." }, "scan_bytes_limit": { "type": "integer", "minimum": 1, "maximum": 268435456, "default": 8388608, "description": "Serialized source bytes, plus selected-space bindings for hybrid. Excludes indexes, allocator overhead and lookahead; not a process memory cap. The operator ceiling defaults to 67108864 and may be configured up to 268435456; discover the active ceiling in the ranking catalog. Request default remains 8388608." } }, "required": [ "text", "limit" ], "additionalProperties": false }, "HybridQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 10000, "description": "Maximum current-record candidates in the authorized tag/type partition (default 10000). Deleted and directly rejected records do not consume this budget; expired or transitively ineligible candidates can. Semantic candidates without the selected embedding space also consume this budget." }, "after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "episode_type": { "anyOf": [ { "$ref": "#/components/schemas/EpisodeType" }, { "type": "null" } ] }, "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes and 1–64 distinct lowercase Unicode alphanumeric terms; punctuation-only text is invalid." }, "scan_bytes_limit": { "type": "integer", "minimum": 1, "maximum": 268435456, "default": 8388608, "description": "Serialized source bytes, plus selected-space bindings for hybrid. Excludes indexes, allocator overhead and lookahead; not a process memory cap. The operator ceiling defaults to 67108864 and may be configured up to 268435456; discover the active ceiling in the ranking catalog. Request default remains 8388608." }, "space": { "$ref": "#/components/schemas/EmbeddingSpace" }, "vector": { "type": "array", "items": { "type": "number", "minimum": -3.4028234663852886e+38, "maximum": 3.4028234663852886e+38 }, "minItems": 1, "maxItems": 32768, "description": "Finite float32 values, exact declared dimensionality, nonzero norm." }, "min_score": { "type": "number", "minimum": -1, "maximum": 1, "default": -1 }, "ranking_version": { "type": "string", "enum": [ "weighted_rrf_v1", "weighted_rrf_v2" ], "description": "Explicit immutable server profile: weighted_rrf_v1 uses weights 0.5/0.5 and rank constant 60; weighted_rrf_v2 uses 0.25/0.75 and rank constant 2. Both are experimental with 100 candidates per channel. No caller-owned weights." } }, "required": [ "text", "space", "vector", "limit", "ranking_version" ], "additionalProperties": false }, "RankContribution": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 100 }, "score": { "type": "number", "description": "Raw BM25 or cosine, according to the channel. Not a probability." }, "contribution": { "type": "number", "minimum": 0, "maximum": 0.25, "description": "Weighted reciprocal-rank contribution. This generic ceiling covers all accepted channels and profiles; HybridHitV1 and HybridHitV2 apply exact per-channel ceilings." } }, "required": [ "rank", "score", "contribution" ], "additionalProperties": false }, "HybridRankingProfile": { "oneOf": [ { "$ref": "#/components/schemas/HybridRankingProfileV1" }, { "$ref": "#/components/schemas/HybridRankingProfileV2" } ] }, "LexicalHit": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/MemoryRecord" }, "score": { "type": "number", "exclusiveMinimum": 0, "description": "Raw BM25, not a probability." } }, "required": [ "record", "score" ], "additionalProperties": false }, "HybridHit": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/MemoryRecord" }, "score": { "type": "number", "minimum": 0, "maximum": 0.3333333333333333, "description": "Weighted RRF score, neither cosine nor probability. This generic ceiling covers all supported profiles; HybridPage applies the ranking-version-specific ceiling." }, "lexical": { "anyOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "type": "null" } ] }, "semantic": { "anyOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "type": "null" } ] }, "embedding": { "anyOf": [ { "$ref": "#/components/schemas/EmbeddingReceipt" }, { "type": "null" } ] } }, "required": [ "record", "score", "lexical", "semantic", "embedding" ], "additionalProperties": false }, "LexicalPage": { "type": "object", "properties": { "scanned_records": { "type": "integer", "minimum": 0 }, "scanned_bytes": { "type": "integer", "minimum": 0 }, "corpus_records": { "type": "integer", "minimum": 0 }, "next_after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "exhaustive": { "type": "boolean", "description": "True only for a cursorless complete source scan. Independent of candidate truncation and embedding coverage." }, "hits": { "type": "array", "items": { "$ref": "#/components/schemas/LexicalHit" }, "maxItems": 100 }, "matched_records": { "type": "integer", "minimum": 0 }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "scanned_records", "scanned_bytes", "corpus_records", "next_after", "exhaustive", "hits", "matched_records" ], "additionalProperties": false }, "HybridPage": { "type": "object", "properties": { "scanned_records": { "type": "integer", "minimum": 0 }, "scanned_bytes": { "type": "integer", "minimum": 0 }, "corpus_records": { "type": "integer", "minimum": 0 }, "next_after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "exhaustive": { "type": "boolean", "description": "True only for a cursorless complete source scan. Independent of candidate truncation and embedding coverage." }, "embedded_records": { "type": "integer", "minimum": 0 }, "lexical_matches": { "type": "integer", "minimum": 0 }, "semantic_matches": { "type": "integer", "minimum": 0 }, "lexical_candidates": { "type": "integer", "minimum": 0 }, "semantic_candidates": { "type": "integer", "minimum": 0 }, "hits": { "type": "array", "items": { "$ref": "#/components/schemas/HybridHit" }, "maxItems": 100 }, "ranking": { "$ref": "#/components/schemas/HybridRankingProfile" }, "embedding_coverage": { "type": "string", "enum": [ "complete", "partial", "missing", "empty_corpus" ], "description": "Current selected-space bindings among the visible scanned corpus. Missing bindings still allow lexical matches; this is not full dense coverage." }, "candidates_truncated": { "type": "boolean" }, "rank_constant": { "type": "integer", "enum": [ 60, 2 ] }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "scanned_records", "scanned_bytes", "corpus_records", "next_after", "exhaustive", "embedded_records", "lexical_matches", "semantic_matches", "lexical_candidates", "semantic_candidates", "hits", "ranking", "embedding_coverage", "candidates_truncated", "rank_constant" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "ranking": { "properties": { "version": { "const": "weighted_rrf_v1" } } } } }, "then": { "properties": { "rank_constant": { "const": 60 }, "hits": { "items": { "$ref": "#/components/schemas/HybridHitV1" } } } } }, { "if": { "properties": { "ranking": { "properties": { "version": { "const": "weighted_rrf_v2" } } } } }, "then": { "properties": { "rank_constant": { "const": 2 }, "hits": { "items": { "$ref": "#/components/schemas/HybridHitV2" } } } } } ] }, "LexicalRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "mode": { "type": "string", "const": "lexical" }, "query": { "$ref": "#/components/schemas/LexicalQuery" } }, "required": [ "contract_version", "scope", "mode", "query" ], "additionalProperties": false }, "LexicalResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "mode": { "type": "string", "const": "lexical" }, "ranking_version": { "type": "string", "const": "bm25_v1" }, "page": { "$ref": "#/components/schemas/LexicalPage" }, "timing": { "$ref": "#/components/schemas/RetrievalTiming" } }, "required": [ "contract_version", "scope", "mode", "ranking_version", "page", "timing" ], "additionalProperties": false }, "HybridRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "mode": { "type": "string", "const": "hybrid" }, "query": { "$ref": "#/components/schemas/HybridQuery" } }, "required": [ "contract_version", "scope", "mode", "query" ], "additionalProperties": false }, "HybridResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "mode": { "type": "string", "const": "hybrid" }, "ranking_version": { "type": "string", "enum": [ "weighted_rrf_v1", "weighted_rrf_v2" ] }, "page": { "$ref": "#/components/schemas/HybridPage" }, "timing": { "$ref": "#/components/schemas/RetrievalTiming" } }, "required": [ "contract_version", "scope", "mode", "ranking_version", "page", "timing" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "ranking_version": { "const": "weighted_rrf_v1" } } }, "then": { "properties": { "page": { "properties": { "ranking": { "properties": { "version": { "const": "weighted_rrf_v1" } } } } } } } }, { "if": { "properties": { "ranking_version": { "const": "weighted_rrf_v2" } } }, "then": { "properties": { "page": { "properties": { "ranking": { "properties": { "version": { "const": "weighted_rrf_v2" } } } } } } } } ] }, "RetrievalTiming": { "type": "object", "properties": { "retrieval_micros": { "type": "integer", "minimum": 0, "description": "Server retrieval wall time in microseconds. Excludes authentication, blocking-pool queueing, JSON serialization, transport and external embedding generation." } }, "required": [ "retrieval_micros" ], "additionalProperties": false }, "RankingCatalog": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "component_versions": { "type": "object", "properties": { "lexical": { "type": "string", "const": "bm25_v1" }, "semantic": { "type": "string", "const": "cosine_exact_v1" } }, "required": [ "lexical", "semantic" ], "additionalProperties": false }, "hybrid_profiles": { "type": "array", "items": { "$ref": "#/components/schemas/HybridRankingProfile" }, "minItems": 1, "uniqueItems": true }, "execution_limits": { "$ref": "#/components/schemas/RetrievalExecutionLimits" } }, "required": [ "contract_version", "component_versions", "hybrid_profiles", "execution_limits" ], "additionalProperties": false }, "RetrievalExecutionLimits": { "type": "object", "additionalProperties": false, "required": [ "scope", "max_embedding_dimensions", "max_scan_bytes", "default_scan_bytes", "max_concurrent_retrievals", "vector_request_body_bytes" ], "properties": { "scope": { "type": "string", "const": "server_instance" }, "max_embedding_dimensions": { "type": "integer", "minimum": 1, "maximum": 32768 }, "max_scan_bytes": { "type": "integer", "minimum": 8388608, "maximum": 268435456 }, "default_scan_bytes": { "type": "integer", "const": 8388608 }, "max_concurrent_retrievals": { "type": "integer", "minimum": 1, "maximum": 64 }, "vector_request_body_bytes": { "type": "integer", "const": 2097152 } } }, "HybridRankingProfileV1": { "type": "object", "properties": { "version": { "type": "string", "const": "weighted_rrf_v1" }, "method": { "type": "string", "const": "weighted_rrf" }, "lexical_version": { "type": "string", "const": "bm25_v1" }, "semantic_version": { "type": "string", "const": "cosine_exact_v1" }, "candidate_limit": { "type": "integer", "const": 100 }, "lexical_weight": { "type": "number", "const": 0.5 }, "semantic_weight": { "type": "number", "const": 0.5 }, "rank_constant": { "type": "integer", "const": 60 }, "experimental": { "type": "boolean", "const": true } }, "required": [ "version", "method", "lexical_version", "semantic_version", "candidate_limit", "lexical_weight", "semantic_weight", "rank_constant", "experimental" ], "additionalProperties": false }, "HybridRankingProfileV2": { "type": "object", "properties": { "version": { "type": "string", "const": "weighted_rrf_v2" }, "method": { "type": "string", "const": "weighted_rrf" }, "lexical_version": { "type": "string", "const": "bm25_v1" }, "semantic_version": { "type": "string", "const": "cosine_exact_v1" }, "candidate_limit": { "type": "integer", "const": 100 }, "lexical_weight": { "type": "number", "const": 0.25 }, "semantic_weight": { "type": "number", "const": 0.75 }, "rank_constant": { "type": "integer", "const": 2 }, "experimental": { "type": "boolean", "const": true } }, "required": [ "version", "method", "lexical_version", "semantic_version", "candidate_limit", "lexical_weight", "semantic_weight", "rank_constant", "experimental" ], "additionalProperties": false }, "ExperienceActor": { "type": "object", "properties": { "subject_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "At most 256 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "credential_id": { "type": "string", "format": "uuid" } }, "required": [ "subject_id", "credential_id" ], "additionalProperties": false }, "ExperienceEvidence": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "At most 2048 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "reference", "sha256" ], "additionalProperties": false, "description": "Caller-declared content address. The server records but does not fetch or validate the external content." }, "ExperienceParent": { "type": "object", "properties": { "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." } }, "required": [ "attempt_id", "event_id" ], "additionalProperties": false, "description": "An existing immutable event in the same authorized namespace; cannot refer to the new attempt itself." }, "ExperienceRequest": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "context_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "reporter_subject_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "1–256 UTF-8 bytes, nonblank and without control characters." }, "accounting_unit": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "input": { "$ref": "#/components/schemas/ExperienceEvidence" }, "parent": { "anyOf": [ { "$ref": "#/components/schemas/ExperienceParent" }, { "type": "null" } ] } }, "required": [ "id", "context_id", "reporter_subject_id", "accounting_unit", "input" ], "additionalProperties": false }, "ExperienceReceipt": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "namespace": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "request": { "$ref": "#/components/schemas/ExperienceRequest" }, "context_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "parent_event_digest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "actor": { "$ref": "#/components/schemas/ExperienceActor" }, "recorded_at_millis": { "type": "integer", "format": "int64" }, "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "schema_version", "tenant", "namespace", "request", "context_digest", "parent_event_digest", "actor", "recorded_at_millis", "receipt_digest" ], "additionalProperties": false }, "ExperienceOutcome": { "type": "string", "enum": [ "unknown", "succeeded", "failed", "cancelled" ], "description": "An authenticated reporter assertion, not independently verified execution or qualification evidence." }, "ExperienceRecord": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/ExperienceReceipt" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/ExperienceOutcome" }, { "type": "null" } ] }, "last_event_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, { "type": "null" } ] }, "reported_cost_units": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "reported_latency_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "observed_cost_units": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "observed_latency_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] } }, "required": [ "receipt", "revision", "outcome", "last_event_id", "reported_cost_units", "reported_latency_ms", "observed_cost_units", "observed_latency_ms" ], "additionalProperties": false, "description": "Null outcome means no report. Reported usage is from the latest observation; observed usage retains cumulative lower bounds across unknown reports. A terminal outcome may only receive further observations with the same outcome." }, "ExperienceCommand": { "type": "object", "properties": { "event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551614 }, "context_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "outcome": { "$ref": "#/components/schemas/ExperienceOutcome" }, "evidence": { "$ref": "#/components/schemas/ExperienceEvidence" }, "cost_units": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "latency_ms": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ] } }, "required": [ "event_id", "expected_revision", "context_digest", "outcome", "evidence" ], "additionalProperties": false }, "ExperienceEvent": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "command": { "$ref": "#/components/schemas/ExperienceCommand" }, "actor": { "$ref": "#/components/schemas/ExperienceActor" }, "record": { "$ref": "#/components/schemas/ExperienceRecord" }, "recorded_at_millis": { "type": "integer", "format": "int64" }, "event_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "schema_version", "command", "actor", "record", "recorded_at_millis", "event_digest" ], "additionalProperties": false }, "ExperienceCreateRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "request": { "$ref": "#/components/schemas/ExperienceRequest" } }, "required": [ "contract_version", "scope", "request" ], "additionalProperties": false }, "ExperienceReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." } }, "required": [ "contract_version", "scope", "attempt_id" ], "additionalProperties": false }, "ExperienceObserveRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "command": { "$ref": "#/components/schemas/ExperienceCommand" } }, "required": [ "contract_version", "scope", "attempt_id", "command" ], "additionalProperties": false }, "ExperienceEventReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." } }, "required": [ "contract_version", "scope", "attempt_id", "event_id" ], "additionalProperties": false }, "ExperienceReceiptResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/ExperienceReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "ExperienceResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "experience": { "$ref": "#/components/schemas/ExperienceRecord" } }, "required": [ "contract_version", "experience" ], "additionalProperties": false }, "ExperienceEventResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "event": { "$ref": "#/components/schemas/ExperienceEvent" } }, "required": [ "contract_version", "event" ], "additionalProperties": false }, "ExperienceHistoryCursor": { "type": "object", "properties": { "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "through_event_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, { "type": "null" } ] }, "after_event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." } }, "required": [ "receipt_digest", "through_event_id", "after_event_id" ], "additionalProperties": false }, "ExperienceHistoryQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 64 }, "cursor": { "anyOf": [ { "$ref": "#/components/schemas/ExperienceHistoryCursor" }, { "type": "null" } ] } }, "required": [ "limit" ], "additionalProperties": false }, "ExperienceHistoryRequest": { "type": "object", "properties": { "contract_version": { "const": 1, "type": "integer" }, "scope": { "$ref": "#/components/schemas/Scope" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "query": { "$ref": "#/components/schemas/ExperienceHistoryQuery" } }, "required": [ "contract_version", "scope", "attempt_id", "query" ], "additionalProperties": false }, "ExperienceHistoryPage": { "type": "object", "properties": { "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "through_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceEvent" }, "maxItems": 64 }, "scanned_events": { "type": "integer", "minimum": 0, "maximum": 64 }, "next_cursor": { "anyOf": [ { "$ref": "#/components/schemas/ExperienceHistoryCursor" }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "receipt_digest", "through_revision", "events", "scanned_events", "next_cursor", "complete" ], "additionalProperties": false }, "ExperienceHistoryResponse": { "type": "object", "properties": { "contract_version": { "const": 1, "type": "integer" }, "page": { "$ref": "#/components/schemas/ExperienceHistoryPage" } }, "required": [ "contract_version", "page" ], "additionalProperties": false }, "ExperienceArtifactRequest": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "artifact_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "artifact_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "role": { "type": "string", "enum": [ "baseline", "candidate", "output" ] } }, "required": [ "id", "event_id", "artifact_id", "artifact_digest", "role" ], "additionalProperties": false }, "ExperienceArtifactBinding": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "request": { "$ref": "#/components/schemas/ExperienceArtifactRequest" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "event_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "source_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "dependency_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "actor": { "$ref": "#/components/schemas/ExperienceActor" }, "recorded_at_millis": { "type": "integer", "format": "int64" }, "binding_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "schema_version", "request", "attempt_id", "receipt_digest", "event_digest", "source_digest", "dependency_digest", "actor", "recorded_at_millis", "binding_digest" ], "additionalProperties": false }, "ExperienceArtifactBindRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "binding": { "$ref": "#/components/schemas/ExperienceArtifactRequest" } }, "required": [ "contract_version", "scope", "attempt_id", "binding" ], "additionalProperties": false }, "ExperienceArtifactReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "binding_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." } }, "required": [ "contract_version", "scope", "attempt_id", "binding_id" ], "additionalProperties": false }, "ExperienceArtifactResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "binding": { "$ref": "#/components/schemas/ExperienceArtifactBinding" } }, "required": [ "contract_version", "binding" ], "additionalProperties": false }, "ExperienceLineage": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/ExperienceReceipt" }, "ancestors": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceEvent" }, "maxItems": 64 }, "next_parent": { "anyOf": [ { "$ref": "#/components/schemas/ExperienceParent" }, { "type": "null" } ] }, "next_parent_digest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "origin", "ancestors", "next_parent", "next_parent_digest", "complete" ], "additionalProperties": false }, "ExperienceLineageRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "max_depth": { "type": "integer", "minimum": 1, "maximum": 64 } }, "required": [ "contract_version", "scope", "attempt_id", "max_depth" ], "additionalProperties": false }, "ExperienceLineageResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "lineage": { "$ref": "#/components/schemas/ExperienceLineage" } }, "required": [ "contract_version", "lineage" ], "additionalProperties": false }, "ExperienceExportRef": { "type": "object", "properties": { "attempt_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "event_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "event_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "attempt_id", "event_id", "event_digest" ], "additionalProperties": false }, "ExperienceExportSelection": { "type": "object", "properties": { "context_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "accounting_unit": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceExportRef" }, "minItems": 1, "maxItems": 64 } }, "required": [ "context_digest", "accounting_unit", "events" ], "additionalProperties": false }, "ExperienceAccountingSummary": { "type": "object", "properties": { "known_reports": { "type": "integer", "minimum": 0, "maximum": 64 }, "unknown_reports": { "type": "integer", "minimum": 0, "maximum": 64 }, "reported_total": { "anyOf": [ { "type": "string", "pattern": "^[0-9]+$", "description": "Exact unsigned decimal sum; a string avoids floating-point rounding and u64 overflow." }, { "type": "null" } ] }, "observed_lower_bound": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact unsigned decimal sum; a string avoids floating-point rounding and u64 overflow." } }, "required": [ "known_reports", "unknown_reports", "reported_total", "observed_lower_bound" ], "additionalProperties": false }, "ExperienceExportSummary": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 1, "maximum": 64 }, "succeeded": { "type": "integer", "minimum": 0, "maximum": 64 }, "failed": { "type": "integer", "minimum": 0, "maximum": 64 }, "cancelled": { "type": "integer", "minimum": 0, "maximum": 64 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 64 }, "cost_units": { "$ref": "#/components/schemas/ExperienceAccountingSummary" }, "latency_ms": { "$ref": "#/components/schemas/ExperienceAccountingSummary" } }, "required": [ "attempts", "succeeded", "failed", "cancelled", "unknown", "cost_units", "latency_ms" ], "additionalProperties": false }, "ExperienceExport": { "type": "object", "properties": { "method_version": { "type": "string", "const": "qilbee.experience-export.v1" }, "coverage": { "type": "string", "const": "explicit_event_set" }, "context_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "accounting_unit": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "events": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/components/schemas/ExperienceEvent" } }, "summary": { "$ref": "#/components/schemas/ExperienceExportSummary" }, "export_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "method_version", "coverage", "context_digest", "accounting_unit", "events", "summary", "export_digest" ], "additionalProperties": false }, "ExperienceExportRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "selection": { "$ref": "#/components/schemas/ExperienceExportSelection" } }, "required": [ "contract_version", "scope", "selection" ], "additionalProperties": false }, "ExperienceExportResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "export": { "$ref": "#/components/schemas/ExperienceExport" } }, "required": [ "contract_version", "export" ], "additionalProperties": false }, "MemoryChangeCursor": { "type": "object", "properties": { "journal_id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 } }, "required": [ "journal_id", "sequence" ], "additionalProperties": false }, "MemoryChangeKind": { "type": "string", "enum": [ "created", "updated", "deleted", "embedding_attached", "reviewed", "derived" ] }, "MemoryChange": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "cursor": { "$ref": "#/components/schemas/MemoryChangeCursor" }, "kind": { "$ref": "#/components/schemas/MemoryChangeKind" }, "record_id": { "type": "string", "format": "uuid" }, "record_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "author": { "$ref": "#/components/schemas/Author" }, "committed_at_millis": { "type": "integer", "format": "int64" }, "change_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "schema_version", "cursor", "kind", "record_id", "record_revision", "author", "committed_at_millis", "change_digest" ], "additionalProperties": false }, "MemoryChangesQuery": { "type": "object", "properties": { "after": { "anyOf": [ { "$ref": "#/components/schemas/MemoryChangeCursor" }, { "type": "null" } ] }, "through": { "anyOf": [ { "$ref": "#/components/schemas/MemoryChangeCursor" }, { "type": "null" } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 256 } }, "required": [ "limit" ], "additionalProperties": false }, "MemoryChangesPage": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryChange" }, "maxItems": 256 }, "next_cursor": { "anyOf": [ { "$ref": "#/components/schemas/MemoryChangeCursor" }, { "type": "null" } ] }, "high_watermark": { "anyOf": [ { "$ref": "#/components/schemas/MemoryChangeCursor" }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "changes", "next_cursor", "high_watermark", "complete" ], "additionalProperties": false }, "MemoryChangesRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "query": { "$ref": "#/components/schemas/MemoryChangesQuery" } }, "required": [ "contract_version", "scope", "query" ], "additionalProperties": false }, "MemoryChangesResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "page": { "$ref": "#/components/schemas/MemoryChangesPage" } }, "required": [ "contract_version", "scope", "page" ], "additionalProperties": false }, "MemoryReviewDisposition": { "type": "string", "enum": [ "approved", "rejected", "unreviewed" ] }, "MemoryReview": { "type": "object", "properties": { "disposition": { "$ref": "#/components/schemas/MemoryReviewDisposition" }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048 }, "author": { "$ref": "#/components/schemas/Author" }, "reviewed_at_millis": { "type": "integer", "format": "int64" } }, "required": [ "disposition", "evidence_ref", "author", "reviewed_at_millis" ], "additionalProperties": false }, "MemoryReviewCommand": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes; not blank; no control characters. Scoped by authenticated tenant, namespace and subject." }, "record_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "disposition": { "$ref": "#/components/schemas/MemoryReviewDisposition" }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "contract_version", "idempotency_key", "record_id", "expected_revision", "disposition", "evidence_ref" ], "additionalProperties": false }, "MemoryReviewReceipt": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes; not blank; no control characters. Scoped by authenticated tenant, namespace and subject." }, "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "review": { "$ref": "#/components/schemas/MemoryReview" }, "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "contract_version", "idempotency_key", "record_id", "revision", "review", "receipt_digest" ], "additionalProperties": false }, "MemoryReviewRequest": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "command": { "$ref": "#/components/schemas/MemoryReviewCommand" } }, "required": [ "scope", "command" ], "additionalProperties": false }, "MemoryReviewResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/MemoryReviewReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "MemoryReviewState": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "review": { "anyOf": [ { "$ref": "#/components/schemas/MemoryReview" }, { "type": "null" } ] }, "deleted": { "type": "boolean" }, "expired": { "type": "boolean" } }, "required": [ "record_id", "revision", "review", "deleted", "expired" ], "additionalProperties": false }, "MemoryReviewStateRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "record_id": { "type": "string", "format": "uuid" } }, "required": [ "contract_version", "scope", "record_id" ], "additionalProperties": false }, "MemoryReviewStateResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "state": { "$ref": "#/components/schemas/MemoryReviewState" } }, "required": [ "contract_version", "scope", "state" ], "additionalProperties": false }, "MemoryReviewReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "contract_version", "scope", "record_id", "revision" ], "additionalProperties": false }, "MemorySourceRef": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "record_id", "revision" ], "additionalProperties": false }, "MemoryDerivation": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/MemorySourceRef" }, "minItems": 1, "maxItems": 16 }, "method": { "type": "string", "minLength": 1, "maxLength": 256 }, "method_revision": { "type": "string", "minLength": 1, "maxLength": 256 }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "sources", "method", "method_revision", "evidence_ref" ], "additionalProperties": false }, "DeriveOperation": { "type": "object", "properties": { "type": { "type": "string", "const": "derive" }, "record": { "$ref": "#/components/schemas/RecordInput" }, "derivation": { "$ref": "#/components/schemas/MemoryDerivation" } }, "required": [ "type", "record", "derivation" ], "additionalProperties": false }, "DependencyWork": { "type": "object", "properties": { "records_examined": { "type": "integer", "minimum": 0, "maximum": 4096 }, "bytes_examined": { "type": "integer", "minimum": 0, "maximum": 16777216 } }, "required": [ "records_examined", "bytes_examined" ], "additionalProperties": false }, "MemoryEligibilityReason": { "type": "string", "enum": [ "eligible", "deleted", "expired", "rejected", "source_missing", "source_revision_changed", "dependency_cycle", "depth_limit", "node_limit" ] }, "MemoryEligibilityFailure": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid" }, "expected_revision": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "actual_revision": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, { "type": "null" } ] }, "reason": { "$ref": "#/components/schemas/MemoryEligibilityReason" } }, "required": [ "record_id", "expected_revision", "actual_revision", "reason" ], "additionalProperties": false }, "MemoryEligibility": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "eligible": { "type": "boolean" }, "evaluated_at_millis": { "type": "integer", "format": "int64" }, "first_failure": { "anyOf": [ { "$ref": "#/components/schemas/MemoryEligibilityFailure" }, { "type": "null" } ] }, "dependencies_checked": { "type": "integer", "minimum": 0, "maximum": 64 }, "max_depth_examined": { "type": "integer", "minimum": 0 }, "all_dependencies_checked": { "type": "boolean" }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "record_id", "revision", "eligible", "evaluated_at_millis", "first_failure", "dependencies_checked", "max_depth_examined", "all_dependencies_checked", "dependency_work" ], "additionalProperties": false }, "MemoryEligibilityResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "eligibility": { "$ref": "#/components/schemas/MemoryEligibility" } }, "required": [ "contract_version", "scope", "eligibility" ], "additionalProperties": false }, "MemoryCheckpoint": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "cursor": { "$ref": "#/components/schemas/MemoryChangeCursor" }, "author": { "$ref": "#/components/schemas/Author" }, "updated_at_millis": { "type": "integer", "format": "int64" }, "checkpoint_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "schema_version", "consumer_id", "revision", "cursor", "author", "updated_at_millis", "checkpoint_digest" ], "additionalProperties": false }, "MemoryCheckpointCommand": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes; not blank; no control characters. Scoped by authenticated tenant, namespace and subject." }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "expected_revision": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "cursor": { "$ref": "#/components/schemas/MemoryChangeCursor" } }, "required": [ "contract_version", "idempotency_key", "consumer_id", "expected_revision", "cursor" ], "additionalProperties": false }, "MemoryCheckpointReceipt": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes; not blank; no control characters. Scoped by authenticated tenant, namespace and subject." }, "checkpoint": { "$ref": "#/components/schemas/MemoryCheckpoint" }, "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "contract_version", "idempotency_key", "checkpoint", "receipt_digest" ], "additionalProperties": false }, "MemoryCheckpointRequest": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "command": { "$ref": "#/components/schemas/MemoryCheckpointCommand" } }, "required": [ "scope", "command" ], "additionalProperties": false }, "MemoryCheckpointResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/MemoryCheckpointReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "MemoryCheckpointReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "contract_version", "scope", "consumer_id" ], "additionalProperties": false }, "MemoryCheckpointReadResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "checkpoint": { "$ref": "#/components/schemas/MemoryCheckpoint" } }, "required": [ "contract_version", "scope", "checkpoint" ], "additionalProperties": false }, "VerifiedMemoryCursor": { "type": "object", "properties": { "version": { "const": 2 }, "journal_id": { "type": "string", "format": "uuid" }, "generation": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "prefix_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "version", "journal_id", "generation", "sequence", "prefix_digest" ], "additionalProperties": false }, "VerifiedMemoryChangesQuery": { "type": "object", "properties": { "after": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "through": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 256 } }, "required": [ "limit" ], "additionalProperties": false }, "VerifiedMemoryChange": { "type": "object", "properties": { "cursor": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "change": { "$ref": "#/components/schemas/MemoryChange" } }, "required": [ "cursor", "change" ], "additionalProperties": false }, "VerifiedMemoryChangesPage": { "type": "object", "properties": { "active": { "type": "boolean" }, "baseline": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "changes": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/VerifiedMemoryChange" } }, "next_cursor": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "high_watermark": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "active", "baseline", "changes", "next_cursor", "high_watermark", "complete" ], "additionalProperties": false }, "VerifiedMemoryChangesRequest": { "type": "object", "properties": { "contract_version": { "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "query": { "$ref": "#/components/schemas/VerifiedMemoryChangesQuery" } }, "required": [ "contract_version", "scope", "query" ], "additionalProperties": false }, "VerifiedMemoryChangesResponse": { "type": "object", "properties": { "contract_version": { "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "page": { "$ref": "#/components/schemas/VerifiedMemoryChangesPage" } }, "required": [ "contract_version", "scope", "page" ], "additionalProperties": false }, "VerifiedJournalActivationRequest": { "type": "object", "properties": { "contract_version": { "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" } }, "required": [ "contract_version", "scope" ], "additionalProperties": false }, "VerifiedJournalActivationResponse": { "type": "object", "properties": { "contract_version": { "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "baseline": { "$ref": "#/components/schemas/VerifiedMemoryCursor" } }, "required": [ "contract_version", "scope", "baseline" ], "additionalProperties": false }, "VerifiedMemoryCheckpoint": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 2 }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "cursor": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "author": { "$ref": "#/components/schemas/Author" }, "updated_at_millis": { "type": "integer", "format": "int64" }, "checkpoint_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "schema_version", "consumer_id", "revision", "cursor", "author", "updated_at_millis", "checkpoint_digest" ], "additionalProperties": false }, "VerifiedMemoryCheckpointCommand": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 2 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes; not blank; no control characters. Scoped by authenticated tenant, namespace and subject." }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "expected_revision": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, "cursor": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "expected_checkpoint_digest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] } }, "required": [ "contract_version", "idempotency_key", "consumer_id", "expected_revision", "cursor" ], "additionalProperties": false }, "VerifiedMemoryCheckpointReceipt": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 2 }, "idempotency_key": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes; not blank; no control characters. Scoped by authenticated tenant, namespace and subject." }, "checkpoint": { "$ref": "#/components/schemas/VerifiedMemoryCheckpoint" }, "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "contract_version", "idempotency_key", "checkpoint", "receipt_digest" ], "additionalProperties": false }, "VerifiedMemoryCheckpointRequest": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "command": { "$ref": "#/components/schemas/VerifiedMemoryCheckpointCommand" } }, "required": [ "scope", "command" ], "additionalProperties": false }, "VerifiedMemoryCheckpointResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 2 }, "receipt": { "$ref": "#/components/schemas/VerifiedMemoryCheckpointReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "VerifiedMemoryCheckpointReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "contract_version", "scope", "consumer_id" ], "additionalProperties": false }, "VerifiedMemoryCheckpointReadResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "checkpoint": { "$ref": "#/components/schemas/VerifiedMemoryCheckpoint" } }, "required": [ "contract_version", "scope", "checkpoint" ], "additionalProperties": false }, "VerifiedCheckpointRecoveryCommand": { "type": "object", "properties": { "contract_version": { "const": 2 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256 }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "expected_checkpoint_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "cursor": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "contract_version", "idempotency_key", "consumer_id", "expected_revision", "expected_checkpoint_digest", "cursor", "evidence_ref" ], "additionalProperties": false }, "VerifiedCheckpointRecoveryReceipt": { "type": "object", "properties": { "contract_version": { "const": 2 }, "idempotency_key": { "type": "string" }, "previous": { "$ref": "#/components/schemas/VerifiedMemoryCheckpoint" }, "checkpoint": { "$ref": "#/components/schemas/VerifiedMemoryCheckpoint" }, "evidence_ref": { "type": "string" }, "receipt_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "contract_version", "idempotency_key", "previous", "checkpoint", "evidence_ref", "receipt_digest" ], "additionalProperties": false }, "VerifiedCheckpointRecoveryRequest": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "command": { "$ref": "#/components/schemas/VerifiedCheckpointRecoveryCommand" } }, "required": [ "scope", "command" ], "additionalProperties": false }, "VerifiedCheckpointRecoveryResponse": { "type": "object", "properties": { "contract_version": { "const": 2 }, "receipt": { "$ref": "#/components/schemas/VerifiedCheckpointRecoveryReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "VerifiedCheckpointRecoveryReadRequest": { "type": "object", "properties": { "contract_version": { "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "contract_version", "scope", "consumer_id", "revision" ], "additionalProperties": false }, "HybridHitV1": { "description": "A hit using the immutable weighted_rrf_v1 profile. Ranks are one-based; missing channels contribute zero.", "allOf": [ { "$ref": "#/components/schemas/HybridHit" }, { "properties": { "score": { "maximum": 0.01639344262295082 }, "lexical": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "properties": { "contribution": { "maximum": 0.00819672131147541 } } } ] }, { "type": "null" } ] }, "semantic": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "properties": { "contribution": { "maximum": 0.00819672131147541 } } } ] }, { "type": "null" } ] } } } ] }, "HybridHitV2": { "description": "A hit using the immutable weighted_rrf_v2 profile. Ranks are one-based; missing channels contribute zero.", "allOf": [ { "$ref": "#/components/schemas/HybridHit" }, { "properties": { "score": { "maximum": 0.3333333333333333 }, "lexical": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "properties": { "contribution": { "maximum": 0.08333333333333333 } } } ] }, { "type": "null" } ] }, "semantic": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "properties": { "contribution": { "maximum": 0.25 } } } ] }, { "type": "null" } ] } } } ] }, "MemoryJournalAudit": { "type": "object", "properties": { "active": { "type": "boolean" }, "baseline": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "checked_after": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "checked_through": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "high_watermark": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "links_checked": { "type": "integer", "minimum": 0, "maximum": 256 }, "complete": { "type": "boolean" } }, "required": [ "active", "baseline", "checked_after", "checked_through", "high_watermark", "links_checked", "complete" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "active": { "const": false } }, "required": [ "active" ] }, "then": { "properties": { "baseline": { "const": null }, "checked_after": { "const": null }, "checked_through": { "const": null }, "high_watermark": { "const": null }, "links_checked": { "const": 0 }, "complete": { "const": true } } }, "else": { "properties": { "baseline": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "checked_after": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "checked_through": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "high_watermark": { "$ref": "#/components/schemas/VerifiedMemoryCursor" } } } } ] }, "MemoryJournalAuditResponse": { "type": "object", "properties": { "contract_version": { "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "audit": { "$ref": "#/components/schemas/MemoryJournalAudit" } }, "required": [ "contract_version", "scope", "audit" ], "additionalProperties": false }, "VerifiedJournalConflictError": { "description": "A well-formed client cursor does not match the authorized verified history. No journal, generation, boundary or digest is disclosed.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "journal_history_conflict" ] } } } } } ] }, "VerifiedCheckpointConflictError": { "description": "Verified checkpoint failures have distinct codes for history mismatch, backward progress, stale comparison and changed retries.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "journal_history_conflict", "checkpoint_regression", "revision_conflict", "idempotency_conflict" ] } } } } } ] }, "VerifiedRecoveryConflictError": { "description": "Explicit recovery permits backward progress but still requires valid history, an existing current checkpoint and an unchanged retry body.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "journal_history_conflict", "revision_conflict", "idempotency_conflict" ] } } } } } ] }, "CheckpointNotFoundError": { "description": "No checkpoint exists for the authenticated subject and exact authorized scope.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "checkpoint_not_found" ] } } } } } ] }, "RecoveryNotFoundError": { "description": "No recovery receipt exists for the authenticated subject, consumer and resulting revision.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "error": { "properties": { "code": { "enum": [ "recovery_not_found" ] } } } } } ] }, "StrategyExtractor": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." }, "model": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." }, "model_revision": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." }, "prompt_revision": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." }, "evidence_ref": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Nonblank, at most 2048 UTF-8 bytes; server limits bytes, not Unicode code points." } }, "required": [ "provider", "model", "model_revision", "prompt_revision", "evidence_ref" ], "additionalProperties": false }, "StrategyObservationSelection": { "type": "object", "properties": { "context_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "accounting_unit": { "type": "string", "minLength": 1, "maxLength": 512, "description": "At most 512 UTF-8 bytes, nonblank; byte limits are enforced by the server." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceExportRef" }, "minItems": 1, "maxItems": 16 } }, "required": [ "context_digest", "accounting_unit", "events" ], "additionalProperties": false }, "StrategyCandidate": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." }, "policy_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." }, "context_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." }, "instructions": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Nonblank, at most 16384 UTF-8 bytes; server limits bytes, not Unicode code points." }, "preconditions": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Nonblank, at most 1024 UTF-8 bytes; server limits bytes, not Unicode code points." } }, "counterexamples": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Nonblank, at most 1024 UTF-8 bytes; server limits bytes, not Unicode code points." } }, "extractor": { "$ref": "#/components/schemas/StrategyExtractor" }, "selection": { "$ref": "#/components/schemas/StrategyObservationSelection" } }, "required": [ "id", "policy_id", "context_id", "instructions", "preconditions", "counterexamples", "extractor", "selection" ], "additionalProperties": false }, "StrategyCandidateReceipt": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "method_version": { "type": "string", "const": "qilbee.experience-strategy.v1" }, "request": { "$ref": "#/components/schemas/StrategyCandidate" }, "export_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "summary": { "$ref": "#/components/schemas/ExperienceExportSummary" }, "proposal": { "$ref": "#/components/schemas/ProposalReceipt" }, "strategy_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "schema_version", "method_version", "request", "export_digest", "summary", "proposal", "strategy_digest" ], "additionalProperties": false }, "StrategyCandidateRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "strategy": { "$ref": "#/components/schemas/StrategyCandidate" } }, "required": [ "contract_version", "scope", "strategy" ], "additionalProperties": false }, "StrategyCandidateReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "strategy_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Nonblank, at most 512 UTF-8 bytes; server limits bytes, not Unicode code points." } }, "required": [ "contract_version", "scope", "strategy_id" ], "additionalProperties": false }, "StrategyCandidateResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "receipt": { "$ref": "#/components/schemas/StrategyCandidateReceipt" } }, "required": [ "contract_version", "receipt" ], "additionalProperties": false }, "RetrievalBusyError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "const": "retrieval_busy" } } } } } ] }, "ReviewNotFoundError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "const": "review_not_found" } } } } } ] }, "MemoryConsumerDiagnosticsRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1–128 UTF-8 bytes, nonblank and without control characters; owned by the authenticated subject." }, "witness": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] } }, "required": [ "contract_version", "scope", "consumer_id" ], "additionalProperties": false }, "MemoryConsumerDiagnostics": { "type": "object", "properties": { "consumer_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "active": { "type": "boolean" }, "baseline": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "high_watermark": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, { "type": "null" } ] }, "checkpoint": { "anyOf": [ { "$ref": "#/components/schemas/VerifiedMemoryCheckpoint" }, { "type": "null" } ] }, "checkpoint_status": { "type": "string", "enum": [ "missing", "compatible", "history_incompatible" ] }, "pending_positions": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 }, { "type": "null" } ], "description": "Sequence distance from compatible stored checkpoint to current tip, not an audit or a count of eligible records. Null when missing or history-incompatible." }, "witness_status": { "type": "string", "enum": [ "not_provided", "compatible", "history_incompatible" ] }, "checkpoint_relative_to_witness": { "type": [ "string", "null" ], "enum": [ "before", "equal", "after", null ] } }, "required": [ "consumer_id", "active", "baseline", "high_watermark", "checkpoint", "checkpoint_status", "pending_positions", "witness_status", "checkpoint_relative_to_witness" ], "additionalProperties": false, "description": "One snapshot, exact subject-owned consumer, bounded boundary checks and no writes. A well-formed incompatible witness is an observed status rather than an HTTP conflict. Encountered corruption still fails the whole request.", "allOf": [ { "if": { "properties": { "active": { "const": true } }, "required": [ "active" ] }, "then": { "properties": { "baseline": { "$ref": "#/components/schemas/VerifiedMemoryCursor" }, "high_watermark": { "$ref": "#/components/schemas/VerifiedMemoryCursor" } } }, "else": { "properties": { "baseline": { "type": "null" }, "high_watermark": { "type": "null" } } } }, { "if": { "properties": { "checkpoint_status": { "const": "missing" } }, "required": [ "checkpoint_status" ] }, "then": { "properties": { "checkpoint": { "type": "null" } } }, "else": { "properties": { "checkpoint": { "$ref": "#/components/schemas/VerifiedMemoryCheckpoint" } } } }, { "if": { "properties": { "checkpoint_status": { "const": "compatible" } }, "required": [ "checkpoint_status" ] }, "then": { "properties": { "active": { "const": true }, "pending_positions": { "type": "integer", "minimum": 0, "maximum": 18446744073709551615 } } }, "else": { "properties": { "pending_positions": { "type": "null" } } } }, { "if": { "properties": { "witness_status": { "const": "compatible" } }, "required": [ "witness_status" ] }, "then": { "properties": { "active": { "const": true } } }, "else": { "properties": {} } }, { "if": { "properties": { "checkpoint_status": { "const": "compatible" }, "witness_status": { "const": "compatible" } }, "required": [ "checkpoint_status", "witness_status" ] }, "then": { "properties": { "checkpoint_relative_to_witness": { "type": "string", "enum": [ "before", "equal", "after" ] } } }, "else": { "properties": { "checkpoint_relative_to_witness": { "type": "null" } } } } ] }, "MemoryConsumerDiagnosticsResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 2 }, "scope": { "$ref": "#/components/schemas/Scope" }, "diagnostics": { "$ref": "#/components/schemas/MemoryConsumerDiagnostics" } }, "required": [ "contract_version", "scope", "diagnostics" ], "additionalProperties": false }, "GlobalCapability": { "type": "string", "enum": [ "tenant_create", "tenant_inspect", "tenant_admin", "global_credential_admin" ] }, "GlobalCredentialSpec": { "type": "object", "properties": { "subject_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalCapability" }, "minItems": 1 }, "expires_at_millis": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "null" } ] } }, "required": [ "subject_id", "capabilities" ], "additionalProperties": false }, "GlobalCredential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "spec": { "$ref": "#/components/schemas/GlobalCredentialSpec" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "revoked_at_millis": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalCredentialEvent" } }, "is_master": { "type": "boolean" } }, "required": [ "id", "spec", "revision", "revoked_at_millis", "history", "is_master" ], "additionalProperties": false }, "GlobalCredentialResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "credential": { "$ref": "#/components/schemas/GlobalCredential" } }, "required": [ "contract_version", "credential" ], "additionalProperties": false }, "IssuedGlobalCredential": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "credential": { "$ref": "#/components/schemas/GlobalCredential" }, "secret": { "type": "string", "pattern": "^qdbg1_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$", "description": "Returned once; keep in a backend secret manager." } }, "required": [ "contract_version", "credential", "secret" ], "additionalProperties": false }, "GlobalIssueRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "spec": { "$ref": "#/components/schemas/GlobalCredentialSpec" } }, "required": [ "contract_version", "spec" ], "additionalProperties": false }, "RegisterTenantRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "tenant_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, nonblank and without control characters; immutable identity, not a display name." }, "subject_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "display_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256, "description": "Human-readable company name; 1..256 UTF-8 bytes and no control characters." } }, "required": [ "contract_version", "tenant_id", "subject_id" ], "additionalProperties": false }, "TenantAdminRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "subject_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." } }, "required": [ "contract_version", "subject_id" ], "additionalProperties": false }, "TenantRegistration": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "tenant_id": { "type": "string" }, "created_at_millis": { "type": "integer", "format": "int64" }, "created_by": { "type": "string", "format": "uuid" }, "initial_admin_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable company name; 1..256 UTF-8 bytes and no control characters." } }, "required": [ "schema_version", "tenant_id", "created_at_millis", "created_by", "initial_admin_id" ], "additionalProperties": false }, "RegisteredTenant": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "tenant": { "$ref": "#/components/schemas/TenantRegistration" }, "credential": { "$ref": "#/components/schemas/Credential" }, "secret": { "type": "string", "pattern": "^qdb1_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$", "description": "Returned once. Store securely; never log." } }, "required": [ "contract_version", "tenant", "credential", "secret" ], "additionalProperties": false }, "TenantInspection": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "tenant_id": { "type": "string" }, "registration": { "anyOf": [ { "$ref": "#/components/schemas/TenantRegistration" }, { "type": "null" } ], "description": "Null for a tenant created by the local bootstrap command, which has no global registration receipt." } }, "required": [ "contract_version", "tenant_id", "registration" ], "additionalProperties": false }, "GlobalCredentialEvent": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "action": { "type": "string", "enum": [ "bootstrapped", "issued", "rotated", "revoked", "recovered_by_local_operator" ] }, "actor_id": { "type": "string", "format": "uuid" }, "at_millis": { "type": "integer", "format": "int64" } }, "required": [ "revision", "action", "actor_id", "at_millis" ], "additionalProperties": false }, "LoginAuthority": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "global", "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "tenant", "type": "string" }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact, case-sensitive identifier, 1..256 UTF-8 bytes; no control characters." } }, "required": [ "kind", "tenant_id" ], "additionalProperties": false } ] }, "LoginAccountEvent": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "action": { "type": "string", "enum": [ "login_account_created", "login_password_changed", "login_account_disabled" ] }, "actor_id": { "type": "string", "format": "uuid" }, "at_millis": { "type": "integer", "format": "int64" } }, "required": [ "revision", "action", "actor_id", "at_millis" ], "additionalProperties": false }, "LoginAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "username": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact, case-sensitive identifier, 1..256 UTF-8 bytes; no control characters." }, "authority": { "$ref": "#/components/schemas/LoginAuthority" }, "credential_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "disabled_at_millis": { "type": [ "integer", "null" ], "format": "int64" }, "history": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LoginAccountEvent" } } }, "required": [ "id", "username", "authority", "credential_id", "revision", "disabled_at_millis", "history" ], "additionalProperties": false }, "LoginAccountResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "account": { "$ref": "#/components/schemas/LoginAccount" } }, "required": [ "contract_version", "account" ], "additionalProperties": false }, "LoginAccountCreate": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "username": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact, case-sensitive identifier, 1..256 UTF-8 bytes; no control characters." }, "password": { "type": "string", "minLength": 8, "maxLength": 1024, "writeOnly": true, "description": "8..1024 UTF-8 bytes. Never logged or returned." }, "credential_id": { "type": "string", "format": "uuid" } }, "required": [ "contract_version", "username", "password", "credential_id" ], "additionalProperties": false }, "LoginPasswordChange": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "password": { "type": "string", "minLength": 8, "maxLength": 1024, "writeOnly": true, "description": "8..1024 UTF-8 bytes. Never logged or returned." } }, "required": [ "contract_version", "expected_revision", "password" ], "additionalProperties": false }, "LoginAccountDisable": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 } }, "required": [ "contract_version", "expected_revision" ], "additionalProperties": false }, "TenantLoginRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "tenant_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact, case-sensitive identifier, 1..256 UTF-8 bytes; no control characters." }, "username": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact, case-sensitive identifier, 1..256 UTF-8 bytes; no control characters." }, "password": { "type": "string", "minLength": 0, "maxLength": 1024, "writeOnly": true, "description": "8..1024 UTF-8 bytes. Never logged or returned." } }, "required": [ "contract_version", "tenant_id", "username", "password" ], "additionalProperties": false }, "GlobalLoginRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "username": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Exact, case-sensitive identifier, 1..256 UTF-8 bytes; no control characters." }, "password": { "type": "string", "minLength": 0, "maxLength": 1024, "writeOnly": true, "description": "8..1024 UTF-8 bytes. Never logged or returned." } }, "required": [ "contract_version", "username", "password" ], "additionalProperties": false }, "LoginSessionResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "session": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^qdbs[gt]1_[0-9a-f]{32}_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$", "description": "One-time delivery of a 15-minute bearer session. Store securely; never log." }, "token_type": { "const": "Bearer", "type": "string" }, "expires_at_millis": { "type": "integer", "format": "int64" }, "account": { "$ref": "#/components/schemas/LoginAccount" } }, "required": [ "token", "token_type", "expires_at_millis", "account" ], "additionalProperties": false } }, "required": [ "contract_version", "session" ], "additionalProperties": false }, "LogoutResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "logged_out": { "const": true, "type": "boolean" } }, "required": [ "contract_version", "logged_out" ], "additionalProperties": false }, "TenantDirectoryEntry": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "registration": { "oneOf": [ { "$ref": "#/components/schemas/TenantRegistration" }, { "type": "null" } ] } }, "required": [ "tenant_id", "registration" ], "additionalProperties": false }, "DirectoryTenantsResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "page": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/TenantDirectoryEntry" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 8192, "description": "Opaque, exclusive last-key position inside the authorized directory. Not a snapshot or authorization claim." } }, "required": [ "items", "next_cursor" ], "additionalProperties": false } }, "required": [ "contract_version", "page" ], "additionalProperties": false }, "DirectoryGlobalCredentialsResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "page": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/GlobalCredential" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 8192, "description": "Opaque, exclusive last-key position inside the authorized directory. Not a snapshot or authorization claim." } }, "required": [ "items", "next_cursor" ], "additionalProperties": false } }, "required": [ "contract_version", "page" ], "additionalProperties": false }, "DirectoryTenantCredentialsResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "page": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Credential" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 8192, "description": "Opaque, exclusive last-key position inside the authorized directory. Not a snapshot or authorization claim." } }, "required": [ "items", "next_cursor" ], "additionalProperties": false } }, "required": [ "contract_version", "page" ], "additionalProperties": false }, "DirectoryGlobalLoginAccountsResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "page": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/LoginAccount" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 8192, "description": "Opaque, exclusive last-key position inside the authorized directory. Not a snapshot or authorization claim." } }, "required": [ "items", "next_cursor" ], "additionalProperties": false } }, "required": [ "contract_version", "page" ], "additionalProperties": false }, "DirectoryTenantLoginAccountsResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "page": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/LoginAccount" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 8192, "description": "Opaque, exclusive last-key position inside the authorized directory. Not a snapshot or authorization claim." } }, "required": [ "items", "next_cursor" ], "additionalProperties": false } }, "required": [ "contract_version", "page" ], "additionalProperties": false }, "MemoryBatchReadRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "record_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "format": "uuid" }, "description": "Distinct record UUIDs, in desired response order. No enumeration or cross-scope lookup." } }, "required": [ "contract_version", "scope", "record_ids" ], "additionalProperties": false }, "MemoryReadEntry": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid" }, "record": { "oneOf": [ { "$ref": "#/components/schemas/MemoryRecord" }, { "type": "null" } ], "description": "Current eligible record, or null for absent/deleted/expired/rejected/ineligible records. The non-null record_id equals the requested record_id; no unavailability reason is disclosed." } }, "required": [ "record_id", "record" ], "additionalProperties": false }, "MemoryReadBatch": { "type": "object", "properties": { "evaluated_at_millis": { "type": "integer", "format": "int64", "description": "One server clock for all roots and dependencies in this storage snapshot. Not a cursor, lease, or future validity guarantee." }, "entries": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/MemoryReadEntry" }, "description": "Exactly one entry per requested UUID, preserving request order." }, "record_bytes": { "type": "integer", "minimum": 0, "maximum": 8388608, "description": "Serialized root-record bytes examined, including unavailable roots; excludes index bytes, dependency reads and temporary allocations." }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "evaluated_at_millis", "entries", "record_bytes", "dependency_work" ], "additionalProperties": false }, "MemoryBatchReadResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "batch": { "$ref": "#/components/schemas/MemoryReadBatch" } }, "required": [ "contract_version", "scope", "batch" ], "additionalProperties": false }, "ExternalIdSelector": { "description": "Explicit selection. all permits dynamically supplied IDs; only uses exact IDs. An empty only list permits no IDs. Selectors do not register projects, agents or missions.", "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "all" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "only" }, "ids": { "type": "array", "items": { "type": "string", "minLength": 1, "description": "An opaque external identifier: 1–256 UTF-8 bytes, not blank, without control characters. Matching is exact." }, "maxItems": 256, "uniqueItems": true } }, "required": [ "mode", "ids" ], "additionalProperties": false } ] }, "CompanyScopePolicy": { "type": "object", "description": "Versioned, explicit company integration authority. Tenant and private subject are derived from the credential, never supplied by this policy. Resource selectors are intersected and do not replace capability checks.", "properties": { "version": { "type": "string", "const": "company_scopes_v1" }, "projects": { "$ref": "#/components/schemas/ExternalIdSelector" }, "agents": { "$ref": "#/components/schemas/ExternalIdSelector" }, "missions": { "$ref": "#/components/schemas/ExternalIdSelector" }, "allow_unassigned_mission": { "type": "boolean", "description": "Whether mission_id=null or omitted is permitted, independently of assigned mission IDs." }, "visibilities": { "type": "array", "items": { "$ref": "#/components/schemas/Visibility" }, "minItems": 1, "maxItems": 2, "uniqueItems": true } }, "required": [ "version", "projects", "agents", "missions", "allow_unassigned_mission", "visibilities" ], "additionalProperties": false, "examples": [ { "version": "company_scopes_v1", "projects": { "mode": "all" }, "agents": { "mode": "all" }, "missions": { "mode": "all" }, "allow_unassigned_mission": true, "visibilities": [ "shared", "private" ] } ] }, "ScopeAuthority": { "type": "object", "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "scope_policy": { "anyOf": [ { "$ref": "#/components/schemas/CompanyScopePolicy" }, { "type": "null" } ], "description": "Omitted or null preserves legacy exact-grant authorization. Never inferred from empty grants. A company policy requires grants=[] and excludes credential_admin." } }, "required": [ "grants" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "scope_policy" ], "properties": { "scope_policy": { "type": "object" } } }, "then": { "properties": { "grants": { "maxItems": 0 } } } } ] }, "ScopeAuthorityChange": { "type": "object", "properties": { "previous": { "$ref": "#/components/schemas/ScopeAuthority" }, "current": { "$ref": "#/components/schemas/ScopeAuthority" } }, "required": [ "previous", "current" ], "additionalProperties": false }, "ScopeAuthorityRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "authority": { "$ref": "#/components/schemas/ScopeAuthority" } }, "required": [ "contract_version", "expected_revision", "authority" ], "additionalProperties": false, "examples": [ { "contract_version": 1, "expected_revision": 1, "authority": { "grants": [], "scope_policy": { "version": "company_scopes_v1", "projects": { "mode": "all" }, "agents": { "mode": "all" }, "missions": { "mode": "all" }, "allow_unassigned_mission": true, "visibilities": [ "shared", "private" ] } } } ] }, "AgentRegistrationTrigger": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "successful_resource_request", "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "memory_command", "type": "string" }, "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "action": { "type": "string", "enum": [ "created", "updated", "deleted", "derived" ] } }, "required": [ "kind", "record_id", "revision", "action" ], "additionalProperties": false } ] }, "ObservedAgent": { "type": "object", "properties": { "agent_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "registered_at_millis": { "type": "integer", "format": "int64" }, "registered_by": { "$ref": "#/components/schemas/Author" }, "first_scope": { "$ref": "#/components/schemas/Scope" }, "private_subject_id": { "anyOf": [ { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, { "type": "null" } ] }, "trigger": { "$ref": "#/components/schemas/AgentRegistrationTrigger" } }, "required": [ "agent_id", "registered_at_millis", "registered_by", "first_scope", "private_subject_id", "trigger" ], "additionalProperties": false }, "ObservedAgentPage": { "type": "object", "properties": { "agents": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ObservedAgent" } }, "next_after_agent_id": { "anyOf": [ { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, { "type": "null" } ] } }, "required": [ "agents", "next_after_agent_id" ], "additionalProperties": false }, "ObservedAgentResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "page": { "$ref": "#/components/schemas/ObservedAgentPage" } }, "required": [ "contract_version", "company_id", "page" ], "additionalProperties": false }, "CompanyMemoryWorkspace": { "type": "object", "properties": { "workspace_id": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Opaque SHA-256 identifier of the unchanged canonical company, scope and private subject address. This identifier grants no authority." }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "scope": { "$ref": "#/components/schemas/Scope" }, "private_subject_id": { "anyOf": [ { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, { "type": "null" } ] } }, "required": [ "workspace_id", "company_id", "scope", "private_subject_id" ], "additionalProperties": false }, "CompanyMemoryWorkspacePage": { "type": "object", "properties": { "workspaces": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CompanyMemoryWorkspace" } }, "next_after_workspace_id": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Opaque SHA-256 identifier of the unchanged canonical company, scope and private subject address. This identifier grants no authority." }, { "type": "null" } ] } }, "required": [ "workspaces", "next_after_workspace_id" ], "additionalProperties": false }, "CompanyMemoryWorkspaceResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "page": { "$ref": "#/components/schemas/CompanyMemoryWorkspacePage" } }, "required": [ "contract_version", "company_id", "page" ], "additionalProperties": false }, "CompanyMemoryQuery": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 500 }, "after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "view": { "type": "string", "enum": [ "current", "retained" ], "default": "retained" }, "text_contains": { "anyOf": [ { "type": "string", "maxLength": 4096, "description": "At most 4096 UTF-8 bytes. Case-insensitive substring match across primary, secondary and context text; not semantic retrieval." }, { "type": "null" } ] }, "tag": { "anyOf": [ { "type": "string", "maxLength": 256, "description": "Exact tag filter, at most 256 UTF-8 bytes." }, { "type": "null" } ] }, "episode_type": { "anyOf": [ { "$ref": "#/components/schemas/EpisodeType" }, { "type": "null" } ] } }, "required": [], "additionalProperties": false }, "CompanyMemoryQueryRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "workspace_id": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Opaque SHA-256 identifier of the unchanged canonical company, scope and private subject address. This identifier grants no authority." }, "filter": { "$ref": "#/components/schemas/CompanyMemoryQuery" } }, "required": [ "contract_version", "workspace_id", "filter" ], "additionalProperties": false }, "CompanyMemoryInspectionRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "workspace_id": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Opaque SHA-256 identifier of the unchanged canonical company, scope and private subject address. This identifier grants no authority." }, "record_id": { "type": "string", "format": "uuid" } }, "required": [ "contract_version", "workspace_id", "record_id" ], "additionalProperties": false }, "CompanyMemoryEntry": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/CompanyRetainedMemoryRecord" }, "eligibility": { "$ref": "#/components/schemas/MemoryEligibility" } }, "required": [ "record", "eligibility" ], "additionalProperties": false, "description": "Current retained revision and its eligibility in one snapshot. In retained view, payloads may be expired, rejected or invalid for agent reuse. Deleted records have null payloads. Entry dependency_work counts incremental reads for that entry; the page reports aggregate work. Administrative visibility does not make a record eligible." }, "CompanyMemoryInventoryPage": { "type": "object", "properties": { "entries": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CompanyMemoryEntry" } }, "next_after": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "stop_reason": { "type": "string", "enum": [ "exhausted", "record_limit", "scan_limit", "byte_limit" ] }, "evaluated_at_millis": { "type": "integer", "format": "int64" }, "scanned_records": { "type": "integer", "minimum": 0, "maximum": 10000 }, "record_bytes": { "type": "integer", "minimum": 0, "maximum": 8388608 }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "entries", "next_after", "stop_reason", "evaluated_at_millis", "scanned_records", "record_bytes", "dependency_work" ], "additionalProperties": false }, "CompanyMemoryInventoryResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "workspace": { "$ref": "#/components/schemas/CompanyMemoryWorkspace" }, "page": { "$ref": "#/components/schemas/CompanyMemoryInventoryPage" } }, "required": [ "contract_version", "company_id", "workspace", "page" ], "additionalProperties": false }, "CompanyMemoryInspectionResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "workspace": { "$ref": "#/components/schemas/CompanyMemoryWorkspace" }, "entry": { "$ref": "#/components/schemas/CompanyMemoryEntry" }, "record_bytes": { "type": "integer", "minimum": 0, "maximum": 8388608 } }, "required": [ "contract_version", "company_id", "workspace", "entry", "record_bytes" ], "additionalProperties": false }, "CompanyMemoryNotFoundError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "const": "record_not_found" } } } } } ] }, "CompanyRetainedMemoryRecord": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1 }, "record_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "created_at_millis": { "type": "integer", "format": "int64" }, "modified_at_millis": { "type": "integer", "format": "int64" }, "author": { "$ref": "#/components/schemas/Author" }, "payload": { "anyOf": [ { "$ref": "#/components/schemas/RecordInput" }, { "type": "null" } ] }, "review": { "anyOf": [ { "$ref": "#/components/schemas/MemoryReview" }, { "type": "null" } ] }, "derivation": { "anyOf": [ { "$ref": "#/components/schemas/MemoryDerivation" }, { "type": "null" } ] } }, "required": [ "schema_version", "record_id", "revision", "created_at_millis", "modified_at_millis", "author", "payload" ], "additionalProperties": false, "description": "Retained current canonical revision for company administration. Deleted records preserve audit metadata with a null payload; this is not a historical body archive." }, "MemoryGraphQuery": { "type": "object", "properties": { "root_record_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 16, "uniqueItems": true }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 8, "default": 4 }, "node_limit": { "type": "integer", "minimum": 1, "maximum": 256, "default": 128 } }, "required": [ "root_record_ids" ], "additionalProperties": false }, "MemoryGraphRoot": { "type": "object", "properties": { "record_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "included", "unavailable", "not_examined" ] } }, "required": [ "record_id", "status" ], "additionalProperties": false }, "MemoryGraphNode": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/MemoryRecord" }, "depth": { "type": "integer", "minimum": 0, "maximum": 8 } }, "required": [ "record", "depth" ], "additionalProperties": false }, "MemoryGraphEdge": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/MemorySourceRef" }, "target": { "$ref": "#/components/schemas/MemorySourceRef" }, "relation": { "type": "string", "const": "derived_from" } }, "required": [ "source", "target", "relation" ], "additionalProperties": false }, "MemoryGraphCoverage": { "type": "object", "properties": { "complete": { "type": "boolean" }, "stop_reasons": { "type": "array", "items": { "type": "string", "enum": [ "depth_limit", "node_limit" ] }, "minItems": 0, "maxItems": 2, "uniqueItems": true }, "records_examined": { "type": "integer", "minimum": 0, "maximum": 256 }, "record_bytes": { "type": "integer", "minimum": 0, "maximum": 8388608 }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "complete", "stop_reasons", "records_examined", "record_bytes", "dependency_work" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "complete": { "const": true } } }, "then": { "properties": { "stop_reasons": { "maxItems": 0 } } }, "else": { "properties": { "stop_reasons": { "minItems": 1 } } } } ] }, "MemoryEvidenceGraph": { "type": "object", "properties": { "traversal_version": { "type": "string", "const": "derived_ancestry_v1" }, "evaluated_at_millis": { "type": "integer", "format": "int64" }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 8 }, "node_limit": { "type": "integer", "minimum": 1, "maximum": 256 }, "roots": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryGraphRoot" }, "minItems": 1, "maxItems": 16 }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryGraphNode" }, "minItems": 0, "maxItems": 256 }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryGraphEdge" }, "minItems": 0, "maxItems": 4096 }, "coverage": { "$ref": "#/components/schemas/MemoryGraphCoverage" } }, "required": [ "traversal_version", "evaluated_at_millis", "max_depth", "node_limit", "roots", "nodes", "edges", "coverage" ], "additionalProperties": false }, "MemoryGraphRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "query": { "$ref": "#/components/schemas/MemoryGraphQuery" } }, "required": [ "contract_version", "scope", "query" ], "additionalProperties": false }, "MemoryGraphResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "graph": { "$ref": "#/components/schemas/MemoryEvidenceGraph" } }, "required": [ "contract_version", "scope", "graph" ], "additionalProperties": false }, "CompanyMemoryGraphRequest": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "workspace_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "query": { "$ref": "#/components/schemas/MemoryGraphQuery" } }, "required": [ "contract_version", "workspace_id", "query" ], "additionalProperties": false }, "CompanyMemoryGraphResponse": { "type": "object", "properties": { "contract_version": { "type": "integer", "const": 1 }, "company_id": { "type": "string", "minLength": 1, "description": "1–256 UTF-8 bytes, not blank and without control characters." }, "workspace": { "$ref": "#/components/schemas/CompanyMemoryWorkspace" }, "graph": { "$ref": "#/components/schemas/MemoryEvidenceGraph" } }, "required": [ "contract_version", "company_id", "workspace", "graph" ], "additionalProperties": false }, "GraphRankingVersion": { "type": "string", "enum": [ "typed_path_balanced_v1", "typed_path_entity_v1", "typed_path_temporal_v1", "typed_path_evidence_v1" ] }, "GraphRankingProfileBalancedV1": { "type": "object", "properties": { "version": { "const": "typed_path_balanced_v1" }, "method": { "const": "strongest_typed_path_rrf" }, "experimental": { "const": true }, "traversal_version": { "const": "typed_relations_v1" }, "base_candidate_limit": { "const": 100 }, "anchor_limit": { "const": 4 }, "rank_constant": { "const": 2 }, "base_weight": { "const": 0.25 }, "graph_weight": { "const": 0.75 }, "hop_decay": { "const": 0.5 }, "cosine_affinity_floor": { "const": 0.5 }, "cosine_affinity_weight": { "const": 0.5 }, "missing_embedding_affinity": { "const": 0.5 }, "maximum_score": { "const": 0.3333333333333333 }, "relation_weights": { "type": "array", "minItems": 6, "maxItems": 6, "prefixItems": [ { "type": "object", "properties": { "kind": { "const": "semantic_related" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "same_entity" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "temporal_before" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "causal_claim" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "supports" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "contradicts" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false } ], "items": false } }, "required": [ "version", "method", "experimental", "traversal_version", "base_candidate_limit", "anchor_limit", "rank_constant", "base_weight", "graph_weight", "hop_decay", "cosine_affinity_floor", "cosine_affinity_weight", "missing_embedding_affinity", "maximum_score", "relation_weights" ], "additionalProperties": false }, "GraphRankingProfileEntityV1": { "type": "object", "properties": { "version": { "const": "typed_path_entity_v1" }, "method": { "const": "strongest_typed_path_rrf" }, "experimental": { "const": true }, "traversal_version": { "const": "typed_relations_v1" }, "base_candidate_limit": { "const": 100 }, "anchor_limit": { "const": 4 }, "rank_constant": { "const": 2 }, "base_weight": { "const": 0.25 }, "graph_weight": { "const": 0.75 }, "hop_decay": { "const": 0.5 }, "cosine_affinity_floor": { "const": 0.5 }, "cosine_affinity_weight": { "const": 0.5 }, "missing_embedding_affinity": { "const": 0.5 }, "maximum_score": { "const": 0.3333333333333333 }, "relation_weights": { "type": "array", "minItems": 6, "maxItems": 6, "prefixItems": [ { "type": "object", "properties": { "kind": { "const": "semantic_related" }, "weight": { "const": 0.5 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "same_entity" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "temporal_before" }, "weight": { "const": 0 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "causal_claim" }, "weight": { "const": 0 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "supports" }, "weight": { "const": 0 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "contradicts" }, "weight": { "const": 0 } }, "required": [ "kind", "weight" ], "additionalProperties": false } ], "items": false } }, "required": [ "version", "method", "experimental", "traversal_version", "base_candidate_limit", "anchor_limit", "rank_constant", "base_weight", "graph_weight", "hop_decay", "cosine_affinity_floor", "cosine_affinity_weight", "missing_embedding_affinity", "maximum_score", "relation_weights" ], "additionalProperties": false }, "GraphRankingProfileTemporalV1": { "type": "object", "properties": { "version": { "const": "typed_path_temporal_v1" }, "method": { "const": "strongest_typed_path_rrf" }, "experimental": { "const": true }, "traversal_version": { "const": "typed_relations_v1" }, "base_candidate_limit": { "const": 100 }, "anchor_limit": { "const": 4 }, "rank_constant": { "const": 2 }, "base_weight": { "const": 0.25 }, "graph_weight": { "const": 0.75 }, "hop_decay": { "const": 0.5 }, "cosine_affinity_floor": { "const": 0.5 }, "cosine_affinity_weight": { "const": 0.5 }, "missing_embedding_affinity": { "const": 0.5 }, "maximum_score": { "const": 0.3333333333333333 }, "relation_weights": { "type": "array", "minItems": 6, "maxItems": 6, "prefixItems": [ { "type": "object", "properties": { "kind": { "const": "semantic_related" }, "weight": { "const": 0.25 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "same_entity" }, "weight": { "const": 0.5 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "temporal_before" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "causal_claim" }, "weight": { "const": 0 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "supports" }, "weight": { "const": 0 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "contradicts" }, "weight": { "const": 0 } }, "required": [ "kind", "weight" ], "additionalProperties": false } ], "items": false } }, "required": [ "version", "method", "experimental", "traversal_version", "base_candidate_limit", "anchor_limit", "rank_constant", "base_weight", "graph_weight", "hop_decay", "cosine_affinity_floor", "cosine_affinity_weight", "missing_embedding_affinity", "maximum_score", "relation_weights" ], "additionalProperties": false }, "GraphRankingProfileEvidenceV1": { "type": "object", "properties": { "version": { "const": "typed_path_evidence_v1" }, "method": { "const": "strongest_typed_path_rrf" }, "experimental": { "const": true }, "traversal_version": { "const": "typed_relations_v1" }, "base_candidate_limit": { "const": 100 }, "anchor_limit": { "const": 4 }, "rank_constant": { "const": 2 }, "base_weight": { "const": 0.25 }, "graph_weight": { "const": 0.75 }, "hop_decay": { "const": 0.5 }, "cosine_affinity_floor": { "const": 0.5 }, "cosine_affinity_weight": { "const": 0.5 }, "missing_embedding_affinity": { "const": 0.5 }, "maximum_score": { "const": 0.3333333333333333 }, "relation_weights": { "type": "array", "minItems": 6, "maxItems": 6, "prefixItems": [ { "type": "object", "properties": { "kind": { "const": "semantic_related" }, "weight": { "const": 0.25 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "same_entity" }, "weight": { "const": 0.5 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "temporal_before" }, "weight": { "const": 0.25 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "causal_claim" }, "weight": { "const": 0.75 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "supports" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "contradicts" }, "weight": { "const": 1 } }, "required": [ "kind", "weight" ], "additionalProperties": false } ], "items": false } }, "required": [ "version", "method", "experimental", "traversal_version", "base_candidate_limit", "anchor_limit", "rank_constant", "base_weight", "graph_weight", "hop_decay", "cosine_affinity_floor", "cosine_affinity_weight", "missing_embedding_affinity", "maximum_score", "relation_weights" ], "additionalProperties": false }, "GraphRankingProfile": { "oneOf": [ { "$ref": "#/components/schemas/GraphRankingProfileBalancedV1" }, { "$ref": "#/components/schemas/GraphRankingProfileEntityV1" }, { "$ref": "#/components/schemas/GraphRankingProfileTemporalV1" }, { "$ref": "#/components/schemas/GraphRankingProfileEvidenceV1" } ] }, "GraphSeedQueryLexical": { "type": "object", "properties": { "mode": { "const": "lexical" }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes and 1-64 distinct alphanumeric terms; maxLength is an additional character bound." } }, "required": [ "mode", "text" ], "additionalProperties": false }, "GraphSeedQuerySemantic": { "type": "object", "properties": { "mode": { "const": "semantic" }, "space": { "$ref": "#/components/schemas/EmbeddingSpace" }, "vector": { "type": "array", "items": { "type": "number" }, "maxItems": 32768, "minItems": 1 }, "min_score": { "type": "number", "minimum": -1, "maximum": 1, "default": -1 } }, "required": [ "mode", "space", "vector" ], "additionalProperties": false }, "GraphSeedQueryHybrid": { "type": "object", "properties": { "mode": { "const": "hybrid" }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most 4096 UTF-8 bytes and 1-64 distinct alphanumeric terms; maxLength is an additional character bound." }, "space": { "$ref": "#/components/schemas/EmbeddingSpace" }, "vector": { "type": "array", "items": { "type": "number" }, "maxItems": 32768, "minItems": 1 }, "min_score": { "type": "number", "minimum": -1, "maximum": 1, "default": -1 }, "ranking_version": { "type": "string", "enum": [ "weighted_rrf_v1", "weighted_rrf_v2" ] } }, "required": [ "mode", "text", "space", "vector", "ranking_version" ], "additionalProperties": false }, "GraphSeedQuery": { "oneOf": [ { "$ref": "#/components/schemas/GraphSeedQueryLexical" }, { "$ref": "#/components/schemas/GraphSeedQuerySemantic" }, { "$ref": "#/components/schemas/GraphSeedQueryHybrid" } ] }, "GraphExpansionLimits": { "type": "object", "properties": { "direction": { "$ref": "#/components/schemas/TypedGraphDirection" }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 8 }, "node_limit": { "type": "integer", "minimum": 1, "maximum": 256 }, "edge_limit": { "type": "integer", "minimum": 1, "maximum": 1024 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 4096 }, "embedding_bytes_limit": { "type": "integer", "minimum": 1, "maximum": 8388608 } }, "required": [ "direction", "max_depth", "node_limit", "edge_limit", "scan_limit", "embedding_bytes_limit" ], "additionalProperties": false }, "GraphRetrievalQuery": { "type": "object", "properties": { "ranking_version": { "$ref": "#/components/schemas/GraphRankingVersion" }, "seed": { "$ref": "#/components/schemas/GraphSeedQuery" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 10000 }, "scan_bytes_limit": { "type": "integer", "minimum": 1, "maximum": 268435456, "default": 8388608 }, "expansion": { "$ref": "#/components/schemas/GraphExpansionLimits" }, "episode_type": { "anyOf": [ { "$ref": "#/components/schemas/EpisodeType" }, { "type": "null" } ] }, "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "ranking_version", "seed", "limit" ], "additionalProperties": false }, "GraphRetrievalRequest": { "type": "object", "properties": { "contract_version": { "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "query": { "$ref": "#/components/schemas/GraphRetrievalQuery" } }, "required": [ "contract_version", "scope", "query" ], "additionalProperties": false }, "GraphSeedScoreLexical": { "type": "object", "properties": { "mode": { "const": "lexical" }, "score": { "type": "number", "minimum": 0 } }, "required": [ "mode", "score" ], "additionalProperties": false }, "GraphSeedScoreSemantic": { "type": "object", "properties": { "mode": { "const": "semantic" }, "score": { "type": "number", "minimum": -1, "maximum": 1 }, "embedding": { "$ref": "#/components/schemas/EmbeddingReceipt" } }, "required": [ "mode", "score", "embedding" ], "additionalProperties": false }, "GraphSeedScoreHybrid": { "type": "object", "properties": { "mode": { "const": "hybrid" }, "score": { "type": "number", "minimum": 0, "maximum": 0.3333333333333333 }, "lexical": { "anyOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "type": "null" } ] }, "semantic": { "anyOf": [ { "$ref": "#/components/schemas/RankContribution" }, { "type": "null" } ] }, "embedding": { "anyOf": [ { "$ref": "#/components/schemas/EmbeddingReceipt" }, { "type": "null" } ] } }, "required": [ "mode", "score", "lexical", "semantic", "embedding" ], "additionalProperties": false }, "GraphSeedScore": { "oneOf": [ { "$ref": "#/components/schemas/GraphSeedScoreLexical" }, { "$ref": "#/components/schemas/GraphSeedScoreSemantic" }, { "$ref": "#/components/schemas/GraphSeedScoreHybrid" } ] }, "GraphSeedMetadata": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "lexical", "semantic", "hybrid" ] }, "ranking_version": { "type": "string", "enum": [ "bm25_v1", "cosine_exact_v1", "weighted_rrf_v1", "weighted_rrf_v2" ] }, "hybrid_profile": { "anyOf": [ { "$ref": "#/components/schemas/HybridRankingProfile" }, { "type": "null" } ] }, "embedding_space": { "anyOf": [ { "$ref": "#/components/schemas/EmbeddingSpace" }, { "type": "null" } ] }, "embedding_coverage": { "anyOf": [ { "type": "string", "enum": [ "complete", "partial", "missing", "empty_corpus" ], "description": "Current selected-space bindings among the visible scanned corpus. Missing bindings still allow lexical matches; this is not full dense coverage." }, { "type": "null" } ] }, "selected_anchors": { "type": "array", "items": { "$ref": "#/components/schemas/MemorySourceRef" }, "maxItems": 4 }, "candidate_selection_version": { "const": "current_records_v1" }, "scanned_records": { "type": "integer", "minimum": 0, "maximum": 10000 }, "scanned_bytes": { "type": "integer", "minimum": 0, "maximum": 268435456 }, "candidate_index_bytes": { "type": "integer", "minimum": 0 }, "corpus_records": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "lexical_matches": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "semantic_matches": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "base_candidates": { "type": "integer", "minimum": 0, "maximum": 100 }, "base_candidates_truncated": { "type": "boolean" }, "channel_candidates_truncated": { "type": "boolean" }, "scan_complete": { "type": "boolean" }, "dependency_work": { "$ref": "#/components/schemas/DependencyWork" } }, "required": [ "mode", "ranking_version", "hybrid_profile", "embedding_space", "embedding_coverage", "selected_anchors", "candidate_selection_version", "scanned_records", "scanned_bytes", "candidate_index_bytes", "corpus_records", "lexical_matches", "semantic_matches", "base_candidates", "base_candidates_truncated", "channel_candidates_truncated", "scan_complete", "dependency_work" ], "additionalProperties": false }, "GraphBaseContribution": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 100 }, "retrieval": { "$ref": "#/components/schemas/GraphSeedScore" }, "contribution": { "type": "number", "minimum": 0, "maximum": 0.08333333333333333 } }, "required": [ "rank", "retrieval", "contribution" ], "additionalProperties": false }, "GraphAffinity": { "type": "object", "properties": { "cosine": { "type": "number", "minimum": -1, "maximum": 1 }, "embedding": { "$ref": "#/components/schemas/EmbeddingReceipt" } }, "required": [ "cosine", "embedding" ], "additionalProperties": false }, "GraphPathStep": { "type": "object", "properties": { "relation_id": { "type": "string", "format": "uuid" }, "relation_revision": { "type": "integer", "minimum": 1, "maximum": 18446744073709551615 }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ] }, "from": { "$ref": "#/components/schemas/MemorySourceRef" }, "to": { "$ref": "#/components/schemas/MemorySourceRef" } }, "required": [ "relation_id", "relation_revision", "direction", "from", "to" ], "additionalProperties": false }, "GraphPathContribution": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 256 }, "strength": { "type": "number", "minimum": 0, "maximum": 0.3333333333333333, "description": "Maximum bounded path strength; repeated assertions are not summed." }, "contribution": { "type": "number", "minimum": 0, "maximum": 0.25 }, "anchor": { "$ref": "#/components/schemas/MemorySourceRef" }, "anchor_rank": { "type": "integer", "minimum": 1, "maximum": 4 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/GraphPathStep" }, "maxItems": 8 }, "missing_affinity": { "type": "array", "items": { "$ref": "#/components/schemas/MemorySourceRef" }, "maxItems": 8 } }, "required": [ "rank", "strength", "contribution", "anchor", "anchor_rank", "steps", "missing_affinity" ], "additionalProperties": false }, "GraphAffinityWork": { "type": "object", "properties": { "requested": { "type": "boolean" }, "reused_scores": { "type": "integer", "minimum": 0, "maximum": 256 }, "lookups": { "type": "integer", "minimum": 0, "maximum": 256 }, "current_bindings": { "type": "integer", "minimum": 0, "maximum": 256 }, "missing_bindings": { "type": "integer", "minimum": 0, "maximum": 256 }, "stale_bindings": { "type": "integer", "minimum": 0, "maximum": 256 }, "bytes_read": { "type": "integer", "minimum": 0, "maximum": 8388608 }, "byte_limit": { "type": "integer", "minimum": 1, "maximum": 8388608 } }, "required": [ "requested", "reused_scores", "lookups", "current_bindings", "missing_bindings", "stale_bindings", "bytes_read", "byte_limit" ], "additionalProperties": false }, "GraphRetrievalHit": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/MemoryRecord" }, "score": { "type": "number", "minimum": 0, "maximum": 0.3333333333333333, "description": "Versioned base/graph reciprocal rank fusion, not cosine or probability." }, "base": { "anyOf": [ { "$ref": "#/components/schemas/GraphBaseContribution" }, { "type": "null" } ] }, "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPathContribution" }, { "type": "null" } ] }, "affinity": { "anyOf": [ { "$ref": "#/components/schemas/GraphAffinity" }, { "type": "null" } ] } }, "required": [ "record", "score", "base", "graph", "affinity" ], "additionalProperties": false }, "GraphRetrievalCoverage": { "type": "object", "properties": { "complete": { "type": "boolean" }, "source_complete": { "type": "boolean" }, "candidates_complete": { "type": "boolean" }, "graph_complete": { "type": "boolean" }, "embeddings_complete": { "type": "boolean" } }, "required": [ "complete", "source_complete", "candidates_complete", "graph_complete", "embeddings_complete" ], "additionalProperties": false, "description": "Completeness within the selected immutable four-anchor profile and requested filters, not a graph-wide or relevance guarantee. True only when every constituent flag is true.", "allOf": [ { "if": { "properties": { "complete": { "const": true } } }, "then": { "properties": { "source_complete": { "const": true }, "candidates_complete": { "const": true }, "graph_complete": { "const": true }, "embeddings_complete": { "const": true } } } } ] }, "GraphRetrievalPage": { "type": "object", "properties": { "ranking": { "$ref": "#/components/schemas/GraphRankingProfile" }, "evaluated_at_millis": { "type": "integer", "format": "int64" }, "seed": { "$ref": "#/components/schemas/GraphSeedMetadata" }, "expansion": { "$ref": "#/components/schemas/GraphExpansionLimits" }, "graph_roots": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryGraphRoot" }, "maxItems": 4 }, "graph_coverage": { "$ref": "#/components/schemas/TypedGraphCoverage" }, "affinity_work": { "$ref": "#/components/schemas/GraphAffinityWork" }, "graph_candidates": { "type": "integer", "minimum": 0, "maximum": 256 }, "candidates_ranked": { "type": "integer", "minimum": 0, "maximum": 356 }, "coverage": { "$ref": "#/components/schemas/GraphRetrievalCoverage" }, "hits": { "type": "array", "items": { "$ref": "#/components/schemas/GraphRetrievalHit" }, "maxItems": 100 }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRelation" }, "maxItems": 800 } }, "required": [ "ranking", "evaluated_at_millis", "seed", "expansion", "graph_roots", "graph_coverage", "affinity_work", "graph_candidates", "candidates_ranked", "coverage", "hits", "relations" ], "additionalProperties": false }, "GraphRetrievalResponse": { "type": "object", "properties": { "contract_version": { "const": 1 }, "scope": { "$ref": "#/components/schemas/Scope" }, "page": { "$ref": "#/components/schemas/GraphRetrievalPage" } }, "required": [ "contract_version", "scope", "page" ], "additionalProperties": false }, "GraphRankingProfilesResponse": { "type": "object", "properties": { "contract_version": { "const": 1 }, "graph_profiles": { "type": "array", "items": { "$ref": "#/components/schemas/GraphRankingProfile" }, "maxItems": 4, "minItems": 4 }, "execution_limits": { "$ref": "#/components/schemas/RetrievalExecutionLimits" } }, "required": [ "contract_version", "graph_profiles", "execution_limits" ], "additionalProperties": false } } } }