helm.openapi.yaml

openapi: "3.1.0"
info:
  title: HELM Kernel API
  version: 0.5.1
  description: |
    Deterministic execution kernel for AI tool calls.
    Drop-in OpenAI proxy + cryptographic receipts + offline-verifiable evidence packs.
  license:
    name: Apache-2.0
    url: https://github.com/Mindburn-Labs/helm-ai-kernel/blob/main/LICENSE
  contact:
    name: Mindburn Labs
    url: https://mindburn.org

servers:
  - url: http://localhost:8080
    description: Local development (Docker Compose)
  - url: http://localhost:9090
    description: Standalone proxy mode

tags:
  - name: proxy
    description: OpenAI-compatible proxy endpoints
  - name: approval
    description: RFC-005 approval ceremonies
  - name: mcp
    description: Modern MCP transport (streamable HTTP / JSON-RPC)
  - name: proofgraph
    description: ProofGraph DAG access
  - name: evidence
    description: EvidencePack export and verification
  - name: conformance
    description: Conformance testing
  - name: boundary
    description: Proof-bearing execution-boundary records and checkpoints
  - name: sandbox
    description: Sandbox grant inspection and execution-boundary authority records
  - name: identity
    description: Agent identity, authorization snapshots, approvals, and budgets
  - name: telemetry
    description: Non-authoritative telemetry and coexistence manifests
  - name: system
    description: Health and version
  - name: console
    description: HELM AI Kernel Console platform state
  - name: agent
    description: Self-hosted AG-UI runtime for the HELM AI Kernel Console assistant
  - name: demo
    description: Public HELM AI Kernel sandbox proof scenario

x-helm-reason-codes:
  description: Deterministic reason codes returned by the kernel
  enum:
    - ALLOW
    - DENY_TOOL_NOT_FOUND
    - DENY_SCHEMA_MISMATCH
    - DENY_OUTPUT_DRIFT
    - DENY_BUDGET_EXCEEDED
    - DENY_APPROVAL_REQUIRED
    - DENY_APPROVAL_TIMEOUT
    - DENY_SANDBOX_TRAP
    - DENY_GAS_EXHAUSTION
    - DENY_TIME_LIMIT
    - DENY_MEMORY_LIMIT
    - DENY_POLICY_VIOLATION
    - DENY_TRUST_KEY_REVOKED
    - DENY_IDEMPOTENCY_DUPLICATE
    - ERROR_INTERNAL

paths:
  # -- Public HELM AI Kernel proof demo ---------------------------
  /api/health:
    get:
      operationId: getPublicDemoHealth
      tags: [demo, system]
      summary: Read public HELM AI Kernel demo health
      description: |
        Public health endpoint for the self-hostable HELM AI Kernel proof console.
        Includes build and version metadata used by deployment smoke tests.
      responses:
        '200':
          description: Public demo service health
          content:
            application/json:
              schema:
                type: object
                required: [version, commit, helm_ai_kernel_version, status, build_time, git_sha, deployment_id]
                properties:
                  version: { type: string }
                  commit: { type: string }
                  helm_ai_kernel_version: { type: string }
                  status: { type: string }
                  build_time: { type: string }
                  git_sha: { type: string }
                  deployment_id: { type: string }

  /api/demo/run:
    post:
      operationId: runPublicDemo
      tags: [demo]
      summary: Run the Agent Tool Call Boundary sandbox scenario
      description: |
        Evaluates a sample action through the HELM AI Kernel guardian path and emits
        a signed receipt. The scenario is sandboxed and dispatches no external
        side effects.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action_id]
              properties:
                action_id:
                  type: string
                  enum:
                    - read_ticket
                    - draft_reply
                    - small_refund
                    - large_refund
                    - dangerous_shell
                    - export_customer_list
                    - modify_policy
                policy_id:
                  type: string
                  default: agent_tool_call_boundary
                args:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: HELM AI Kernel sandbox verdict and receipt
          content:
            application/json:
              schema:
                type: object
                required: [verdict, reason_code, receipt, proof_refs, verification_hint, sandbox_label, helm_ai_kernel_version]
                properties:
                  verdict: { type: string, enum: [ALLOW, DENY, ESCALATE] }
                  reason_code: { type: string }
                  receipt:
                    $ref: '#/components/schemas/Receipt'
                  proof_refs:
                    type: object
                    required: [decision_id, receipt_id, receipt_hash]
                    properties:
                      decision_id: { type: string }
                      receipt_id: { type: string }
                      receipt_hash: { type: string }
                  verification_hint: { type: string }
                  sandbox_label: { type: string }
                  helm_ai_kernel_version: { type: string }
        '400':
          $ref: '#/components/responses/HelmError'
        '500':
          $ref: '#/components/responses/HelmError'

  /api/demo/verify:
    post:
      operationId: verifyPublicDemoReceipt
      tags: [demo]
      summary: Verify a HELM AI Kernel demo receipt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [receipt, expected_receipt_hash]
              properties:
                receipt:
                  $ref: '#/components/schemas/Receipt'
                expected_receipt_hash:
                  type: string
                  description: Receipt hash returned in /api/demo/run proof_refs.receipt_hash.
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                type: object
                required: [valid, signature_valid, hash_matches, reason, verified_fields, receipt_hash, expected_receipt_hash]
                properties:
                  valid: { type: boolean }
                  signature_valid: { type: boolean }
                  hash_matches: { type: boolean }
                  reason: { type: string }
                  verified_fields:
                    type: array
                    items: { type: string }
                  receipt_hash: { type: string }
                  expected_receipt_hash: { type: string }
        '400':
          $ref: '#/components/responses/HelmError'

  /api/demo/tamper:
    post:
      operationId: tamperPublicDemoReceipt
      tags: [demo]
      summary: Tamper with a demo receipt and verify that validation fails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [receipt, expected_receipt_hash]
              properties:
                receipt:
                  $ref: '#/components/schemas/Receipt'
                expected_receipt_hash:
                  type: string
                  description: Receipt hash returned in /api/demo/run proof_refs.receipt_hash.
                mutation:
                  type: string
                  default: flip_verdict
      responses:
        '200':
          description: Tamper result
          content:
            application/json:
              schema:
                type: object
                required: [valid, signature_valid, hash_matches, reason, receipt_hash, expected_receipt_hash, original_hash, tampered_hash]
                properties:
                  valid: { type: boolean, const: false }
                  signature_valid: { type: boolean }
                  hash_matches: { type: boolean }
                  reason: { type: string }
                  receipt_hash: { type: string }
                  expected_receipt_hash: { type: string }
                  original_hash: { type: string }
                  tampered_hash: { type: string }
        '400':
          $ref: '#/components/responses/HelmError'

  # ── OpenAI Proxy ────────────────────────────────────
  /v1/chat/completions:
    post:
      operationId: chatCompletions
      tags: [proxy]
      summary: OpenAI-compatible chat completions
      description: |
        Drop-in replacement for OpenAI /v1/chat/completions.
        Tool calls are intercepted, schema-validated, and receipted.
        Response includes X-Helm-Receipt-ID, X-Helm-Output-Hash, X-Helm-Lamport-Clock headers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: gpt-4
              messages:
                - role: user
                  content: "List files in /tmp"
              tools:
                - type: function
                  function:
                    name: file_read
                    parameters:
                      type: object
                      properties:
                        path:
                          type: string
      responses:
        '200':
          description: Chat completion with optional tool calls
          headers:
            X-Helm-Receipt-ID:
              schema: { type: string }
              description: Unique receipt ID for this execution
            X-Helm-Output-Hash:
              schema: { type: string }
              description: SHA-256 of the response body
            X-Helm-Lamport-Clock:
              schema: { type: integer }
              description: Causal ordering clock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '400':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '500':
          $ref: '#/components/responses/HelmError'

  # ── Kernel Approval ─────────────────────────────────
  /api/v1/kernel/approve:
    post:
      operationId: approveIntent
      tags: [approval]
      summary: Submit an approval for a pending intent
      description: |
        RFC-005 approval ceremony endpoint.
        Requires intent_hash, Ed25519 signature, and public key.
        Returns an approval receipt with causal chain linkage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalRequest'
            example:
              intent_hash: "sha256:abc123..."
              signature_b64: "base64-encoded-ed25519-signature"
              public_key_b64: "base64-encoded-public-key"
      responses:
        '200':
          description: Approval receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
              example:
                receipt_id: "rec_a1b2c3"
                status: "APPROVED"
                reason_code: "ALLOW"
                lamport_clock: 42
                output_hash: "sha256:7f83b1..."
        '400':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/evaluate:
    post:
      operationId: evaluateDecision
      tags: [console]
      summary: Evaluate a governed intent and emit a receipt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
      responses:
        '200':
          description: Guardian decision record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionRecord'
        '400':
          $ref: '#/components/responses/HelmError'
        '500':
          $ref: '#/components/responses/HelmError'

  /api/v1/receipts:
    get:
      operationId: listReceipts
      tags: [console]
      summary: List durable receipts
      security:
        - AdminBearerAuth: []
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
        - name: since
          in: query
          schema: { type: string }
        - name: agent
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Receipt list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptListResponse'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '503':
          $ref: '#/components/responses/HelmError'

  /api/v1/receipts/tail:
    get:
      operationId: tailReceipts
      tags: [console]
      summary: Tail durable receipts as server-sent events
      security:
        - AdminBearerAuth: []
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 100, maximum: 1000 }
        - name: since
          in: query
          schema: { type: string }
        - name: agent
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Server-sent receipt events
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '503':
          $ref: '#/components/responses/HelmError'

  /api/v1/receipts/{receipt_id}:
    get:
      operationId: getConsoleReceipt
      tags: [console]
      summary: Get a receipt by ID
      security:
        - AdminBearerAuth: []
      parameters:
        - name: receipt_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Receipt detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        '404':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/console/bootstrap:
    get:
      operationId: getConsoleBootstrap
      tags: [console]
      summary: Read HELM AI Kernel Console bootstrap state
      security:
        - AdminBearerAuth: []
      description: |
        Consolidated read-only platform state used by the HELM AI Kernel Console shell.
        Values are derived from kernel services and local configuration.
      responses:
        '200':
          description: Console bootstrap state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsoleBootstrap'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/console/surfaces:
    get:
      operationId: listConsoleSurfaces
      tags: [console]
      summary: List Console surfaces and their backing source contracts
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Console surface catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  surfaces:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsoleSurfaceRef'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/console/surfaces/{surface_id}:
    get:
      operationId: getConsoleSurface
      tags: [console]
      summary: Read a wired Console surface state
      security:
        - AdminBearerAuth: []
      parameters:
        - name: surface_id
          in: path
          required: true
          schema:
            type: string
            enum: [overview, agents, actions, approvals, policies, replay, audit, developer, settings]
      responses:
        '200':
          description: Console surface state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsoleSurfaceState'
        '404':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/agent-ui/info:
    get:
      operationId: getAgentUIRuntimeInfo
      tags: [agent, console]
      summary: Read OSS Agent UI runtime capabilities
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: AG-UI runtime metadata and read-only tool catalog
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                required: [runtime, protocol, transport, tools]
                properties:
                  runtime: { type: string }
                  protocol: { type: string, const: ag-ui }
                  transport: { type: string, const: sse }
                  tools:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/agent-ui/run:
    post:
      operationId: runAgentUIRuntime
      tags: [agent, console]
      summary: Run the OSS read-only Agent UI assistant
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                threadId: { type: string }
                runId: { type: string }
                workspaceId: { type: string }
                currentSurface: { type: string }
                state:
                  type: object
                  additionalProperties: true
                messages:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                    properties:
                      id: { type: string }
                      role: { type: string }
                      content: { type: string }
      responses:
        '200':
          description: Server-sent AG-UI lifecycle event stream
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/ag-ui/info:
    get:
      operationId: getAGUIRuntimeInfoCompat
      tags: [agent, console]
      summary: Read OSS AG-UI runtime capabilities compatibility route
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: AG-UI runtime metadata and read-only tool catalog
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                required: [runtime, protocol, transport, tools]
                properties:
                  runtime: { type: string }
                  protocol: { type: string, const: ag-ui }
                  transport: { type: string, const: sse }
                  tools:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/HelmError'

  /api/ag-ui/run:
    post:
      operationId: runAGUIRuntimeCompat
      tags: [agent, console]
      summary: Run the OSS read-only AG-UI assistant compatibility route
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                threadId: { type: string }
                runId: { type: string }
                workspaceId: { type: string }
                currentSurface: { type: string }
                state:
                  type: object
                  additionalProperties: true
                messages:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                    properties:
                      id: { type: string }
                      role: { type: string }
                      content: { type: string }
      responses:
        '200':
          description: Server-sent AG-UI lifecycle event stream
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/trust/keys/add:
    post:
      operationId: addTrustKey
      tags: [system]
      summary: Add a trusted signing key
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTrustKeyRequest'
      responses:
        '200':
          description: Trust key added
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  tenant_id: { type: string }
                  key_id: { type: string }
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/trust/keys/revoke:
    post:
      operationId: revokeTrustKey
      tags: [system]
      summary: Revoke a trusted signing key
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeTrustKeyRequest'
      responses:
        '200':
          description: Trust key revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  tenant_id: { type: string }
                  key_id: { type: string }
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  # ── MCP Remote Transport ───────────────────────────
  /mcp:
    get:
      operationId: getMCPTransport
      tags: [mcp]
      summary: Open the MCP transport endpoint
      description: |
        Returns JSON discovery metadata by default.
        When `Accept: text/event-stream` is used, responds with an SSE primer event.
      responses:
        '200':
          description: MCP discovery metadata or SSE primer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPRemoteDiscovery'
            text/event-stream:
              schema:
                type: string
    post:
      operationId: postMCPJSONRPC
      tags: [mcp]
      summary: Send a JSON-RPC request to the MCP transport endpoint
      description: |
        Supports `initialize`, `notifications/initialized`, `ping`, `tools/list`, and `tools/call`.
        Protocol negotiation happens on `initialize`; later requests SHOULD include `MCP-Protocol-Version`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPJSONRPCRequest'
      responses:
        '200':
          description: JSON-RPC response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPJSONRPCResponse'
        '400':
          description: Invalid JSON-RPC body or unsupported protocol version
          content:
            text/plain:
              schema:
                type: string

  /.well-known/oauth-protected-resource/mcp:
    get:
      operationId: getMCPProtectedResourceMetadata
      tags: [mcp]
      summary: Read protected-resource metadata for the MCP endpoint
      responses:
        '200':
          description: OAuth protected-resource metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPProtectedResourceMetadata'
        '404':
          description: OAuth mode is not enabled

  /.well-known/agent-card.json:
    get:
      operationId: getA2AAgentCard
      tags: [a2a]
      summary: Read the public A2A agent card for HELM discovery
      responses:
        '200':
          description: A2A agent discovery card
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/A2AAgentCard'
        '503':
          description: Agent card is not configured

  # ── Execution Boundary ─────────────────────────────
  /api/v1/boundary/status:
    get:
      operationId: getBoundaryStatus
      tags: [boundary]
      summary: Read execution-boundary health and authority status
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Boundary status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoundaryStatus'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/boundary/capabilities:
    get:
      operationId: listBoundaryCapabilities
      tags: [boundary]
      summary: List proof-bearing boundary capabilities
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Capability summaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BoundaryCapabilitySummary'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/boundary/records:
    get:
      operationId: listBoundaryRecords
      tags: [boundary]
      summary: Search execution-boundary records
      security:
        - AdminBearerAuth: []
      parameters:
        - { name: verdict, in: query, schema: { type: string } }
        - { name: reason_code, in: query, schema: { type: string } }
        - { name: tool_name, in: query, schema: { type: string } }
        - { name: mcp_server_id, in: query, schema: { type: string } }
        - { name: policy_epoch, in: query, schema: { type: string } }
        - { name: receipt_id, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 50, maximum: 1000 } }
      responses:
        '200':
          description: Boundary record list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExecutionBoundaryRecord'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/boundary/records/{record_id}:
    get:
      operationId: getBoundaryRecord
      tags: [boundary]
      summary: Get an execution-boundary record
      security:
        - AdminBearerAuth: []
      parameters:
        - name: record_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Boundary record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionBoundaryRecord'
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/boundary/records/{record_id}/verify:
    post:
      operationId: verifyBoundaryRecord
      tags: [boundary]
      summary: Verify a boundary record hash and receipt linkage
      security:
        - AdminBearerAuth: []
      parameters:
        - name: record_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Boundary record verification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoundaryRecordVerification'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/boundary/checkpoints:
    get:
      operationId: listBoundaryCheckpoints
      tags: [boundary]
      summary: List tamper-evident boundary checkpoints
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Boundary checkpoints
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BoundaryCheckpoint'
        '401':
          $ref: '#/components/responses/HelmError'
    post:
      operationId: createBoundaryCheckpoint
      tags: [boundary]
      summary: Create a new boundary checkpoint
      security:
        - AdminBearerAuth: []
      responses:
        '201':
          description: Boundary checkpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoundaryCheckpoint'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/boundary/checkpoints/{checkpoint_id}/verify:
    post:
      operationId: verifyBoundaryCheckpoint
      tags: [boundary]
      summary: Verify a boundary checkpoint and inclusion proof
      security:
        - AdminBearerAuth: []
      parameters:
        - name: checkpoint_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Boundary checkpoint verification
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  # ── ProofGraph ──────────────────────────────────────
  /api/v1/proofgraph/sessions:
    get:
      operationId: listSessions
      tags: [proofgraph]
      summary: List ProofGraph sessions
      security:
        - AdminBearerAuth: []
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 50 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        '200':
          description: List of sessions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/proofgraph/sessions/{session_id}/receipts:
    get:
      operationId: getSessionReceipts
      tags: [proofgraph]
      summary: Get receipts for a specific session
      security:
        - AdminBearerAuth: []
      parameters:
        - name: session_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: List of receipts in session
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Receipt'
        '404':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/proofgraph/receipts/{receipt_hash}:
    get:
      operationId: getReceipt
      tags: [proofgraph]
      summary: Get a single receipt by hash
      security:
        - AdminBearerAuth: []
      parameters:
        - name: receipt_hash
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Receipt details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
        '404':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  # ── EvidencePack ────────────────────────────────────
  /api/v1/evidence/export:
    post:
      operationId: exportEvidence
      tags: [evidence]
      summary: Export an EvidencePack
      security:
        - AdminBearerAuth: []
      description: |
        Exports a deterministic .tar.gz containing all receipts, ProofGraph nodes, and metadata.
        Same content always produces same SHA-256.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportRequest'
            example:
              session_id: "sess_abc123"
              format: "tar.gz"
      responses:
        '200':
          description: EvidencePack binary
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/evidence/verify:
    post:
      operationId: verifyEvidence
      tags: [evidence]
      summary: Verify an EvidencePack
      description: |
        Verifies signatures, causal chain, and policy compliance.
        Works offline — no network calls made during verification.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                bundle:
                  type: string
                  format: binary
                  description: EvidencePack .tar.gz file
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
              example:
                verdict: "PASS"
                checks:
                  signatures: "PASS"
                  causal_chain: "PASS"
                  policy_compliance: "PASS"
                errors: []
        '400':
          $ref: '#/components/responses/HelmError'

  /api/v1/evidence/envelopes:
    get:
      operationId: listEvidenceEnvelopeManifests
      tags: [evidence]
      summary: List evidence envelope manifests
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Evidence envelope manifests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EvidenceEnvelopeManifest'
        '401':
          $ref: '#/components/responses/HelmError'
    post:
      operationId: createEvidenceEnvelopeManifest
      tags: [evidence]
      summary: Build a non-authoritative evidence export envelope manifest
      security:
        - AdminBearerAuth: []
      description: |
        Creates a HELM-native manifest for optional DSSE, JWS, in-toto, SLSA,
        Sigstore, SCITT, or COSE export wrappers. Native EvidencePack roots
        remain the authority; export envelopes are compatibility wrappers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvidenceEnvelopeExportRequest'
            example:
              manifest_id: "env_abc123"
              envelope: "dsse"
              native_evidence_hash: "sha256:7f83b1..."
              subject: "session:sess_abc123"
      responses:
        '200':
          description: Evidence envelope export manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceEnvelopeManifest'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/evidence/envelopes/{manifest_id}:
    get:
      operationId: getEvidenceEnvelopeManifest
      tags: [evidence]
      summary: Get an evidence envelope manifest
      security:
        - AdminBearerAuth: []
      parameters:
        - name: manifest_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Evidence envelope manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceEnvelopeManifest'
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/evidence/envelopes/{manifest_id}/payload:
    get:
      operationId: getEvidenceEnvelopePayload
      tags: [evidence]
      summary: Get the concrete non-authoritative evidence envelope payload
      security:
        - AdminBearerAuth: []
      parameters:
        - name: manifest_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Evidence envelope payload
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/evidence/envelopes/{manifest_id}/verify:
    post:
      operationId: verifyEvidenceEnvelopeManifest
      tags: [evidence]
      summary: Verify an evidence envelope manifest against its HELM root
      security:
        - AdminBearerAuth: []
      parameters:
        - name: manifest_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Evidence envelope verification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceEnvelopeVerification'
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/replay/verify:
    post:
      operationId: replayVerify
      tags: [evidence]
      summary: Replay and verify execution from tapes
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                bundle:
                  type: string
                  format: binary
      responses:
        '200':
          description: Replay verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '400':
          $ref: '#/components/responses/HelmError'

  # ── Conformance ─────────────────────────────────────
  /api/v1/conformance/run:
    post:
      operationId: runConformance
      tags: [conformance]
      summary: Run conformance tests
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConformanceRequest'
            example:
              level: "L2"
              profile: "full"
      responses:
        '200':
          description: Conformance result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConformanceResult'
              example:
                report_id: "conf_abc123"
                level: "L2"
                verdict: "PASS"
                gates: 12
                failed: 0
                details:
                  jcs_canonicalization: "PASS"
                  pep_boundary: "PASS"
                  wasi_sandbox: "PASS"
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/conformance/reports/{report_id}:
    get:
      operationId: getConformanceReport
      tags: [conformance]
      summary: Get a conformance report by ID
      security:
        - AdminBearerAuth: []
      parameters:
        - name: report_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Conformance report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConformanceResult'
        '404':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/conformance/reports:
    get:
      operationId: listConformanceReports
      tags: [conformance]
      summary: List conformance reports
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Conformance reports
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConformanceResult'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/conformance/vectors:
    get:
      operationId: listConformanceVectors
      tags: [conformance]
      summary: List conformance vectors across all public levels
      responses:
        '200':
          description: Conformance vector list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NegativeBoundaryVector'

  /api/v1/conformance/negative:
    get:
      operationId: listNegativeConformanceVectors
      tags: [conformance]
      summary: List fail-closed negative conformance vectors
      description: |
        Returns the clean-room negative execution-boundary gates used to verify
        policy-not-ready, stale policy, PDP outage, direct bypass, schema drift,
        malformed arguments, missing credentials, sandbox overgrant, blocked
        egress, and deny receipt emission behavior.
      responses:
        '200':
          description: Negative conformance vector list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NegativeBoundaryVector'

  # ── MCP Gateway ────────────────────────────────────
  /api/v1/mcp/registry:
    get:
      operationId: listMcpRegistry
      tags: [mcp]
      summary: List quarantined and approved MCP servers
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: MCP server quarantine records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MCPQuarantineRecord'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
    post:
      operationId: discoverMcpServer
      tags: [mcp]
      summary: Register a newly discovered MCP server as quarantined
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPRegistryDiscoverRequest'
            example:
              server_id: "mcp-local-files"
              name: "local files"
              transport: "stdio"
              endpoint: "stdio://local-files"
              tool_names: ["read_file", "write_file"]
              risk: "high"
              reason: "new tool bundle requires approval"
      responses:
        '202':
          description: Quarantined MCP server record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPQuarantineRecord'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/registry/approve:
    post:
      operationId: approveMcpServer
      tags: [mcp]
      summary: Approve a quarantined MCP server using an approval receipt
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPRegistryApprovalRequest'
            example:
              server_id: "mcp-local-files"
              approver_id: "user:security-admin"
              approval_receipt_id: "rcpt_approval_123"
              reason: "reviewed tool bundle and schema pins"
      responses:
        '200':
          description: Approved MCP server record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPQuarantineRecord'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/registry/{server_id}:
    get:
      operationId: getMcpRegistryRecord
      tags: [mcp]
      summary: Get an MCP server quarantine record
      security:
        - AdminBearerAuth: []
      parameters:
        - name: server_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: MCP server quarantine record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPQuarantineRecord'
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/registry/{server_id}/approve:
    post:
      operationId: approveMcpRegistryRecord
      tags: [mcp]
      summary: Approve an MCP server by path id
      security:
        - AdminBearerAuth: []
      parameters:
        - name: server_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPRegistryApprovalRequest'
      responses:
        '200':
          description: Approved MCP server record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPQuarantineRecord'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/registry/{server_id}/revoke:
    post:
      operationId: revokeMcpRegistryRecord
      tags: [mcp]
      summary: Revoke an MCP server approval
      security:
        - AdminBearerAuth: []
      parameters:
        - name: server_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason: { type: string }
      responses:
        '200':
          description: Revoked MCP server record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPQuarantineRecord'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/scan:
    post:
      operationId: scanMcpServer
      tags: [mcp]
      summary: Scan and quarantine an MCP server or tool bundle
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPScanRequest'
      responses:
        '202':
          description: MCP scan result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPScanResult'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/auth-profiles:
    get:
      operationId: listMcpAuthProfiles
      tags: [mcp]
      summary: List MCP OAuth authorization profiles
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: MCP authorization profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MCPAuthorizationProfile'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/auth-profiles/{profile_id}:
    put:
      operationId: putMcpAuthProfile
      tags: [mcp]
      summary: Create or replace an MCP OAuth authorization profile
      security:
        - AdminBearerAuth: []
      parameters:
        - name: profile_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPAuthorizationProfile'
      responses:
        '200':
          description: MCP authorization profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPAuthorizationProfile'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/mcp/authorize-call:
    post:
      operationId: authorizeMcpCall
      tags: [mcp]
      summary: Authorize an MCP tools/call before upstream dispatch
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPAuthorizeCallRequest'
      responses:
        '200':
          description: Allowed boundary record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionBoundaryRecord'
        '403':
          description: Denied boundary record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionBoundaryRecord'
        '401':
          $ref: '#/components/responses/HelmError'

  /mcp/v1/capabilities:
    get:
      operationId: listMCPCapabilities
      tags: [proxy]
      summary: List governed MCP tools
      responses:
        '200':
          description: MCP capability manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPCapabilityManifest'

  /mcp/v1/execute:
    post:
      operationId: executeMCPTool
      tags: [proxy]
      summary: Execute a governed MCP tool call
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPToolCallRequest'
            example:
              method: file_read
              params:
                path: /tmp/test.txt
      responses:
        '200':
          description: Governed tool result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPToolCallResponse'
        '400':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  # ── Sandbox Grants ─────────────────────────────────
  /api/v1/sandbox/profiles:
    get:
      operationId: listSandboxProfiles
      tags: [sandbox]
      summary: List built-in sandbox backend profiles
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Sandbox backend profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SandboxBackendProfile'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/sandbox/grants:
    get:
      operationId: listSandboxGrants
      tags: [sandbox]
      summary: List sealed sandbox grants
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Sandbox grants
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SandboxGrant'
        '401':
          $ref: '#/components/responses/HelmError'
    post:
      operationId: createSandboxGrant
      tags: [sandbox]
      summary: Create a sealed sandbox grant
      security:
        - AdminBearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                runtime: { type: string }
                profile: { type: string }
                image_digest: { type: string }
                policy_epoch: { type: string }
      responses:
        '201':
          description: Sandbox grant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGrant'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/sandbox/grants/{grant_id}:
    get:
      operationId: getSandboxGrant
      tags: [sandbox]
      summary: Get a sealed sandbox grant
      security:
        - AdminBearerAuth: []
      parameters:
        - name: grant_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Sandbox grant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGrant'
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/sandbox/grants/{grant_id}/verify:
    post:
      operationId: verifySandboxGrant
      tags: [sandbox]
      summary: Verify a sealed sandbox grant before execution
      security:
        - AdminBearerAuth: []
      parameters:
        - name: grant_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Sandbox preflight result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxPreflightResult'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/sandbox/preflight:
    post:
      operationId: preflightSandboxGrant
      tags: [sandbox]
      summary: Preflight a sandbox grant and deny overgrant before execution
      security:
        - AdminBearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxPreflightRequest'
      responses:
        '200':
          description: Sandbox preflight result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxPreflightResult'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/sandbox/grants/inspect:
    get:
      operationId: inspectSandboxGrants
      tags: [sandbox]
      summary: Inspect sandbox backend profiles or a sealed sandbox grant
      security:
        - AdminBearerAuth: []
      parameters:
        - name: runtime
          in: query
          schema: { type: string }
          description: Runtime name. Omit to list built-in backend profiles.
        - name: profile
          in: query
          schema: { type: string }
          description: Optional sandbox profile identifier.
        - name: policy_epoch
          in: query
          schema: { type: string }
          description: Policy epoch to bind into the generated grant.
      responses:
        '200':
          description: Backend profile list or sealed sandbox grant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGrantInspection'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  # ── Identity, Authorization, Approvals ─────────────
  /api/v1/identity/agents:
    get:
      operationId: listAgentIdentities
      tags: [identity]
      summary: List non-human identity profiles known to the boundary
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Agent identity profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentIdentityProfile'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/authz/health:
    get:
      operationId: getAuthzHealth
      tags: [identity]
      summary: Read ReBAC/PDP health
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Authorization health
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthzHealth'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/authz/check:
    post:
      operationId: checkAuthz
      tags: [identity]
      summary: Evaluate authorization and seal a relationship snapshot
      security:
        - AdminBearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Authorization snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthzSnapshot'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/authz/snapshots:
    get:
      operationId: listAuthzSnapshots
      tags: [identity]
      summary: List sealed authorization snapshots
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Authorization snapshots
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthzSnapshot'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/authz/snapshots/{snapshot_id}:
    get:
      operationId: getAuthzSnapshot
      tags: [identity]
      summary: Get a sealed authorization snapshot
      security:
        - AdminBearerAuth: []
      parameters:
        - name: snapshot_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Authorization snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthzSnapshot'
        '401':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/approvals:
    get:
      operationId: listApprovalCeremonies
      tags: [identity]
      summary: List approval ceremonies
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Approval ceremonies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApprovalCeremony'
        '401':
          $ref: '#/components/responses/HelmError'
    post:
      operationId: createApprovalCeremony
      tags: [identity]
      summary: Create an approval ceremony
      security:
        - AdminBearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalCeremony'
      responses:
        '201':
          description: Approval ceremony
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalCeremony'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/approvals/{approval_id}/webauthn/challenge:
    post:
      operationId: createApprovalWebAuthnChallenge
      tags: [identity]
      summary: Create a passkey/WebAuthn approval challenge
      security:
        - AdminBearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                method: { type: string, default: passkey }
                ttl_ms: { type: integer }
      responses:
        '201':
          description: Approval WebAuthn challenge
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/approvals/{approval_id}/webauthn/assert:
    post:
      operationId: assertApprovalWebAuthnChallenge
      tags: [identity]
      summary: Assert a passkey/WebAuthn approval challenge
      security:
        - AdminBearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [challenge_id, actor, assertion]
              properties:
                challenge_id: { type: string }
                actor: { type: string }
                assertion: { type: string }
                receipt_id: { type: string }
                reason: { type: string }
      responses:
        '200':
          description: Approval ceremony
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalCeremony'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/approvals/{approval_id}/{action}:
    post:
      operationId: transitionApprovalCeremony
      tags: [identity]
      summary: Approve, deny, or revoke an approval ceremony
      security:
        - AdminBearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema: { type: string }
        - name: action
          in: path
          required: true
          schema:
            type: string
            enum: [approve, deny, revoke]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                actor: { type: string }
                receipt_id: { type: string }
                reason: { type: string }
      responses:
        '200':
          description: Approval ceremony
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalCeremony'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/budgets:
    get:
      operationId: listBudgetCeilings
      tags: [identity]
      summary: List budget and velocity ceilings
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Budget ceilings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BudgetCeiling'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/budgets/{budget_id}:
    put:
      operationId: putBudgetCeiling
      tags: [identity]
      summary: Create or replace a budget ceiling
      security:
        - AdminBearerAuth: []
      parameters:
        - name: budget_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetCeiling'
      responses:
        '200':
          description: Budget ceiling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetCeiling'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  # ── Telemetry and Coexistence ──────────────────────
  /api/v1/coexistence/capabilities:
    get:
      operationId: getCoexistenceCapabilities
      tags: [telemetry]
      summary: Read scanner/gateway coexistence capability manifest
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: Coexistence capability manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoexistenceCapabilityManifest'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/telemetry/otel/config:
    get:
      operationId: getTelemetryOTelConfig
      tags: [telemetry]
      summary: Read non-authoritative OTel GenAI export configuration
      security:
        - AdminBearerAuth: []
      responses:
        '200':
          description: OTel export configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryOTelConfig'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/telemetry/export:
    post:
      operationId: exportTelemetry
      tags: [telemetry]
      summary: Export a non-authoritative telemetry event
      security:
        - AdminBearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryExportRequest'
      responses:
        '202':
          description: Telemetry export result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryExportResult'
        '401':
          $ref: '#/components/responses/HelmError'

  # ── System ──────────────────────────────────────────
  /healthz:
    get:
      operationId: healthCheck
      tags: [system]
      summary: Health check
      responses:
        '200':
          description: Healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: "ok" }
                  version: { type: string, example: "0.1.0" }

  /version:
    get:
      operationId: getVersion
      tags: [system]
      summary: Version information
      responses:
        '200':
          description: Version details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionInfo'
              example:
                version: "0.1.0"
                commit: "abc123"
                build_time: "2026-02-15T00:00:00Z"
                go_version: "go1.24.0"

components:
  securitySchemes:
    AdminBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: HELM_ADMIN_API_KEY
      description: |
        Self-hosted OSS admin bearer key. Set HELM_ADMIN_API_KEY on the server
        and send Authorization: Bearer <key> for protected runtime APIs.

  # ── Schemas ─────────────────────────────────────────
  schemas:
    HelmError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [message, type, code, reason_code]
          properties:
            message:
              type: string
              description: Human-readable error message
            type:
              type: string
              enum: [invalid_request, authentication_error, permission_denied, not_found, internal_error]
            code:
              type: string
              description: Machine-readable error code
            reason_code:
              type: string
              description: HELM-specific reason code
              enum:
                - DENY_TOOL_NOT_FOUND
                - DENY_SCHEMA_MISMATCH
                - DENY_OUTPUT_DRIFT
                - DENY_BUDGET_EXCEEDED
                - DENY_APPROVAL_REQUIRED
                - DENY_APPROVAL_TIMEOUT
                - DENY_SANDBOX_TRAP
                - DENY_GAS_EXHAUSTION
                - DENY_TIME_LIMIT
                - DENY_MEMORY_LIMIT
                - DENY_POLICY_VIOLATION
                - DENY_TRUST_KEY_REVOKED
                - DENY_IDEMPOTENCY_DUPLICATE
                - ERROR_INTERNAL
            details:
              type: object
              description: Additional error context
              additionalProperties: true

    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            type: object
            required: [role, content]
            properties:
              role:
                type: string
                enum: [system, user, assistant, tool]
              content:
                type: string
              tool_call_id:
                type: string
        tools:
          type: array
          items:
            type: object
            properties:
              type: { type: string, enum: [function] }
              function:
                type: object
                properties:
                  name: { type: string }
                  description: { type: string }
                  parameters: { type: object }
        temperature:
          type: number
        max_tokens:
          type: integer
        stream:
          type: boolean
          default: false

    ChatCompletionResponse:
      type: object
      properties:
        id: { type: string }
        object: { type: string, default: "chat.completion" }
        created: { type: integer }
        model: { type: string }
        choices:
          type: array
          items:
            type: object
            properties:
              index: { type: integer }
              message:
                type: object
                properties:
                  role: { type: string }
                  content:
                    type: ['string', 'null']
                  tool_calls:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        type: { type: string }
                        function:
                          type: object
                          properties:
                            name: { type: string }
                            arguments: { type: string }
              finish_reason: { type: string }
        usage:
          type: object
          properties:
            prompt_tokens: { type: integer }
            completion_tokens: { type: integer }
            total_tokens: { type: integer }

    ApprovalRequest:
      type: object
      required: [intent_hash, signature_b64, public_key_b64]
      properties:
        intent_hash:
          type: string
          description: SHA-256 hash of the intent to approve
        signature_b64:
          type: string
          description: Base64-encoded Ed25519 signature
        public_key_b64:
          type: string
          description: Base64-encoded Ed25519 public key
        challenge_response:
          type: string
          description: Optional challenge/response for ceremony

    AddTrustKeyRequest:
      type: object
      required: [tenant_id, key_id, public_key]
      properties:
        tenant_id: { type: string }
        key_id: { type: string }
        public_key:
          type: string
          description: Hex-encoded Ed25519 public key

    RevokeTrustKeyRequest:
      type: object
      required: [tenant_id, key_id]
      properties:
        tenant_id: { type: string }
        key_id: { type: string }

    Receipt:
      type: object
      properties:
        receipt_id: { type: string }
        decision_id: { type: string }
        effect_id: { type: string }
        status: { type: string }
        reason_code: { type: string }
        output_hash: { type: string }
        blob_hash: { type: string }
        prev_hash: { type: string }
        lamport_clock: { type: integer }
        signature: { type: string }
        timestamp: { type: string, format: date-time }
        principal: { type: string }
        executor_id: { type: string }
        args_hash: { type: string }
        metadata:
          type: object
          additionalProperties: true

    ReceiptListResponse:
      type: object
      properties:
        receipts:
          type: array
          items:
            $ref: '#/components/schemas/Receipt'
        count: { type: integer }
        next_cursor: { type: string }
        has_more: { type: boolean }

    DecisionRequest:
      type: object
      required: [action, resource]
      properties:
        principal: { type: string }
        action: { type: string }
        resource: { type: string }
        context:
          type: object
          additionalProperties: true

    DecisionRecord:
      type: object
      properties:
        id: { type: string }
        action: { type: string }
        resource: { type: string }
        verdict: { type: string }
        reason: { type: string }
        policy_version: { type: string }
        policy_decision_hash: { type: string }
        signature: { type: string }

    ConsoleBootstrap:
      type: object
      required: [version, workspace, health, counts, receipts, conformance, mcp]
      properties:
        version:
          $ref: '#/components/schemas/VersionInfo'
        workspace:
          type: object
          required: [organization, project, environment, mode]
          properties:
            organization: { type: string }
            project: { type: string }
            environment: { type: string }
            mode: { type: string }
        health:
          type: object
          required: [kernel, policy, store, conformance]
          properties:
            kernel: { type: string }
            policy: { type: string }
            store: { type: string }
            conformance: { type: string }
        counts:
          type: object
          required: [receipts, pending_approvals, open_incidents, mcp_tools]
          properties:
            receipts: { type: integer }
            pending_approvals: { type: integer }
            open_incidents: { type: integer }
            mcp_tools: { type: integer }
        receipts:
          type: array
          items:
            $ref: '#/components/schemas/Receipt'
        conformance:
          type: object
          required: [level, status]
          properties:
            level: { type: string }
            status: { type: string }
            report_id: { type: string }
        mcp:
          type: object
          required: [authorization, scopes]
          properties:
            authorization: { type: string }
            scopes:
              type: array
              items: { type: string }

    ConsoleSurfaceRef:
      type: object
      required: [id, source]
      properties:
        id: { type: string }
        source: { type: string }

    ConsoleSurfaceState:
      type: object
      required: [id, status, source, generated_at]
      properties:
        id: { type: string }
        status: { type: string }
        source: { type: string }
        generated_at: { type: string, format: date-time }
        summary:
          type: object
          additionalProperties: true
        records:
          type: array
          items:
            type: object
            additionalProperties: true

    Session:
      type: object
      properties:
        session_id: { type: string }
        created_at: { type: string, format: date-time }
        receipt_count: { type: integer }
        last_lamport_clock: { type: integer }

    MCPRemoteDiscovery:
      type: object
      properties:
        server_name: { type: string }
        version: { type: string }
        capabilities_url: { type: string }
        execute_url: { type: string }
        mcp_endpoint: { type: string }
        supported_protocol_versions:
          type: array
          items: { type: string }
        auth_mode: { type: string }
        governance: { type: string }

    MCPJSONRPCRequest:
      type: object
      required: [jsonrpc, method]
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        id:
          description: Request identifier. Omit for notifications.
          oneOf:
            - type: string
            - type: integer
        method: { type: string }
        params:
          type: object
          additionalProperties: true

    MCPJSONRPCError:
      type: object
      properties:
        code: { type: integer }
        message: { type: string }

    MCPJSONRPCResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        id:
          oneOf:
            - type: string
            - type: integer
        result:
          type: object
          additionalProperties: true
        error:
          $ref: '#/components/schemas/MCPJSONRPCError'

    MCPProtectedResourceMetadata:
      type: object
      properties:
        resource: { type: string }
        authorization_servers:
          type: array
          items: { type: string }
        scopes_supported:
          type: array
          items: { type: string }
        bearer_methods_supported:
          type: array
          items: { type: string }
        resource_documentation: { type: string }

    A2AAgentCard:
      type: object
      required: [agent_id, name, endpoint, supported_versions, skills, created_at, updated_at]
      properties:
        agent_id: { type: string }
        name: { type: string }
        description: { type: string }
        endpoint: { type: string }
        provider:
          type: object
          properties:
            organization: { type: string }
            url: { type: string }
        supported_versions:
          type: array
          items: { type: string }
        skills:
          type: array
          items:
            type: object
            required: [id, name]
            properties:
              id: { type: string }
              name: { type: string }
              description: { type: string }
              examples:
                type: array
                items: { type: string }
              input_modes:
                type: array
                items: { type: string }
              output_modes:
                type: array
                items: { type: string }
        auth_methods:
          type: array
          items: { type: string }
        features:
          type: array
          items: { type: string }
        defaultInputModes:
          type: array
          items: { type: string }
        defaultOutputModes:
          type: array
          items: { type: string }
        capabilities:
          type: object
          properties:
            streaming: { type: boolean }
            pushNotifications: { type: boolean }
            stateTransitionHistory: { type: boolean }
        signature: { type: string }
        content_hash: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    MCPRegistryDiscoverRequest:
      type: object
      required: [server_id]
      properties:
        server_id: { type: string }
        name: { type: string }
        transport: { type: string }
        endpoint: { type: string }
        tool_names:
          type: array
          items: { type: string }
        risk:
          type: string
          enum: [unknown, low, medium, high, critical]
          default: unknown
        reason: { type: string }

    MCPRegistryApprovalRequest:
      type: object
      required: [server_id, approver_id, approval_receipt_id]
      properties:
        server_id: { type: string }
        approver_id: { type: string }
        approval_receipt_id: { type: string }
        reason: { type: string }

    MCPQuarantineRecord:
      type: object
      required: [server_id, risk, state, discovered_at]
      properties:
        server_id: { type: string }
        name: { type: string }
        transport: { type: string }
        endpoint: { type: string }
        tool_names:
          type: array
          items: { type: string }
        risk:
          type: string
          enum: [unknown, low, medium, high, critical]
        state:
          type: string
          enum: [discovered, quarantined, approved, revoked, expired]
        discovered_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time }
        approved_by: { type: string }
        approval_receipt_id: { type: string }
        revoked_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        reason: { type: string }

    ExportRequest:
      type: object
      properties:
        session_id:
          type: string
          description: Session to export (omit for all)
        format:
          type: string
          enum: [tar.gz]
          default: tar.gz

    VerificationResult:
      type: object
      properties:
        verdict:
          type: string
          enum: [PASS, FAIL]
        checks:
          type: object
          properties:
            signatures: { type: string, enum: [PASS, FAIL] }
            causal_chain: { type: string, enum: [PASS, FAIL] }
            policy_compliance: { type: string, enum: [PASS, FAIL] }
        roots:
          type: object
          properties:
            manifest_root_hash: { type: string }
            merkle_root: { type: string }
            entry_count: { type: integer }
        errors:
          type: array
          items: { type: string }

    EvidenceEnvelopeExportRequest:
      type: object
      required: [manifest_id, envelope, native_evidence_hash]
      properties:
        manifest_id:
          type: string
        envelope:
          type: string
          enum: [dsse, jws, in-toto, slsa, sigstore, scitt, cose]
        native_evidence_hash:
          type: string
          description: HELM-native EvidencePack root hash.
        subject:
          type: string
        experimental:
          type: boolean
          default: false
          description: Must be true for experimental SCITT or COSE exports.

    EvidenceEnvelopeManifest:
      type: object
      required: [manifest_id, envelope, native_evidence_hash, native_authority, created_at]
      properties:
        manifest_id: { type: string }
        envelope:
          type: string
          enum: [dsse, jws, in-toto, slsa, sigstore, scitt, cose]
        native_evidence_hash: { type: string }
        native_authority:
          type: boolean
          const: true
        subject: { type: string }
        statement_hash: { type: string }
        experimental: { type: boolean }
        created_at: { type: string, format: date-time }
        manifest_hash: { type: string }

    ConformanceRequest:
      type: object
      required: [level]
      properties:
        level:
          type: string
          enum: [L1, L2]
        profile:
          type: string
          default: full

    ConformanceResult:
      type: object
      properties:
        report_id: { type: string }
        level: { type: string }
        verdict: { type: string, enum: [PASS, FAIL] }
        gates: { type: integer }
        failed: { type: integer }
        details:
          type: object
          additionalProperties: { type: string }

    NegativeBoundaryVector:
      type: object
      required: [id, category, trigger, expected_verdict, expected_reason_code, must_emit_receipt, must_not_dispatch]
      properties:
        id: { type: string }
        category: { type: string }
        trigger: { type: string }
        expected_verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        expected_reason_code: { type: string }
        must_emit_receipt: { type: boolean }
        must_not_dispatch: { type: boolean }
        must_bind_evidence:
          type: array
          items: { type: string }

    VersionInfo:
      type: object
      properties:
        version: { type: string }
        commit: { type: string }
        build_time: { type: string }
        go_version: { type: string }

    MCPToolRef:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        server_id: { type: string }
        schema:
          type: object
          additionalProperties: true

    MCPCapabilityManifest:
      type: object
      properties:
        server_name: { type: string }
        version: { type: string }
        governance: { type: string }
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPToolRef'

    MCPToolCallRequest:
      type: object
      required: [method]
      properties:
        method: { type: string }
        params:
          type: object
          additionalProperties: true

    MCPToolCallResponse:
      type: object
      properties:
        result:
          description: Tool output payload
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        error: { type: string }
        reason_code: { type: string }
        args_hash: { type: string }
        proofgraph_node: { type: string }
        receipt_id: { type: string }

    SandboxBackendProfile:
      type: object
      required: [name, kind, runtime, hosted, deny_network_by_default, native_isolation]
      properties:
        name: { type: string }
        kind:
          type: string
          enum: [wasi-wazero, wasi-wasmtime, native-nsjail, native-gvisor, native-firecracker, hosted-adapter]
        runtime: { type: string }
        hosted: { type: boolean }
        deny_network_by_default: { type: boolean }
        native_isolation: { type: boolean }
        experimental: { type: boolean }

    SandboxBackendProfileList:
      type: array
      items:
        $ref: '#/components/schemas/SandboxBackendProfile'

    SandboxGrantInspection:
      oneOf:
        - $ref: '#/components/schemas/SandboxBackendProfileList'
        - $ref: '#/components/schemas/SandboxGrant'

    FilesystemPreopen:
      type: object
      required: [path, mode]
      properties:
        path: { type: string }
        mode:
          type: string
          enum: [ro, rw]
        content_hash: { type: string }

    EnvExposurePolicy:
      type: object
      required: [mode]
      properties:
        mode:
          type: string
          enum: [deny-all, allowlist, redacted]
        names:
          type: array
          items: { type: string }
        names_hash: { type: string }
        redacted: { type: boolean }

    NetworkGrant:
      type: object
      required: [mode]
      properties:
        mode:
          type: string
          enum: [deny-all, allowlist]
        destinations:
          type: array
          items: { type: string }
        cidrs:
          type: array
          items: { type: string }

    SandboxGrantLimits:
      type: object
      properties:
        memory_bytes: { type: integer, format: int64 }
        cpu_time:
          type: integer
          format: int64
          description: Go duration in nanoseconds.
        output_bytes: { type: integer, format: int64 }
        open_files: { type: integer }

    SandboxGrant:
      type: object
      required: [grant_id, runtime, profile, env, network, declared_at]
      properties:
        grant_id: { type: string }
        runtime: { type: string }
        runtime_version: { type: string }
        profile: { type: string }
        image_digest: { type: string }
        template_digest: { type: string }
        filesystem_preopens:
          type: array
          items:
            $ref: '#/components/schemas/FilesystemPreopen'
        env:
          $ref: '#/components/schemas/EnvExposurePolicy'
        network:
          $ref: '#/components/schemas/NetworkGrant'
        limits:
          $ref: '#/components/schemas/SandboxGrantLimits'
        declared_at: { type: string, format: date-time }
        policy_epoch: { type: string }
        grant_hash: { type: string }

    BoundaryStatus:
      type: object
      properties:
        version: { type: string }
        status: { type: string }
        receipt_store_ready: { type: boolean }
        signer_ready: { type: boolean }
        open_approvals: { type: integer }
        quarantined_mcp_servers: { type: integer }
        last_checkpoint_id: { type: string }
        checked_at: { type: string, format: date-time }

    BoundaryCapabilitySummary:
      type: object
      properties:
        capability_id: { type: string }
        category: { type: string }
        status: { type: string }
        authority: { type: string }
        public_routes:
          type: array
          items: { type: string }
        cli_commands:
          type: array
          items: { type: string }
        receipt_bindings:
          type: array
          items: { type: string }
        conformance_level: { type: string }

    ExecutionBoundaryRecord:
      type: object
      properties:
        record_id: { type: string }
        verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        reason_code: { type: string }
        tool_name: { type: string }
        args_hash: { type: string }
        policy_epoch: { type: string }
        mcp_server_id: { type: string }
        oauth_resource: { type: string }
        oauth_scopes:
          type: array
          items: { type: string }
        sandbox_grant_hash: { type: string }
        authz_snapshot_hash: { type: string }
        approval_receipt_id: { type: string }
        receipt_id: { type: string }
        record_hash: { type: string }
        created_at: { type: string, format: date-time }

    BoundaryRecordVerification:
      type: object
      properties:
        record_id: { type: string }
        record_hash: { type: string }
        receipt_id: { type: string }
        verified: { type: boolean }
        errors:
          type: array
          items: { type: string }
        checked_at: { type: string, format: date-time }

    BoundaryCheckpoint:
      type: object
      properties:
        checkpoint_id: { type: string }
        sequence: { type: integer, format: int64 }
        previous_checkpoint_hash: { type: string }
        receipt_count: { type: integer }
        record_count: { type: integer }
        root_hash: { type: string }
        checkpoint_hash: { type: string }
        created_at: { type: string, format: date-time }

    EvidenceEnvelopeVerification:
      type: object
      properties:
        manifest_id: { type: string }
        manifest_hash: { type: string }
        native_evidence_hash: { type: string }
        verified: { type: boolean }
        authoritative: { type: boolean }
        errors:
          type: array
          items: { type: string }
        checked_at: { type: string, format: date-time }

    MCPScanRequest:
      type: object
      required: [server_id]
      properties:
        server_id: { type: string }
        name: { type: string }
        transport: { type: string }
        endpoint: { type: string }
        tool_names:
          type: array
          items: { type: string }
        manifest:
          type: object
          additionalProperties: true

    MCPScanResult:
      type: object
      properties:
        server_id: { type: string }
        risk: { type: string }
        state: { type: string }
        tool_count: { type: integer }
        findings:
          type: array
          items: { type: string }
        recommended_action: { type: string }
        quarantine_record_id: { type: string }
        requires_approval: { type: boolean }
        schema_pin_required: { type: boolean }
        authorization_needed: { type: boolean }
        scanned_at: { type: string, format: date-time }

    MCPAuthorizationProfile:
      type: object
      properties:
        profile_id: { type: string }
        protocol_version: { type: string }
        resource: { type: string }
        authorization_servers:
          type: array
          items: { type: string }
        scopes_supported:
          type: array
          items: { type: string }
        tool_scopes:
          type: object
          additionalProperties:
            type: array
            items: { type: string }
        required_audience: { type: string }
        stale_after: { type: string, format: date-time }
        profile_hash: { type: string }

    MCPAuthorizeCallRequest:
      type: object
      required: [server_id, tool_name]
      properties:
        server_id: { type: string }
        tool_name: { type: string }
        args_hash: { type: string }
        granted_scopes:
          type: array
          items: { type: string }
        pinned_schema_hash: { type: string }
        tool_schema:
          type: object
          additionalProperties: true
        output_schema:
          type: object
          additionalProperties: true
        oauth_resource: { type: string }
        receipt_id: { type: string }

    SandboxPreflightRequest:
      type: object
      properties:
        runtime: { type: string }
        profile: { type: string }
        image_digest: { type: string }
        policy_epoch: { type: string }
        requested_grant:
          $ref: '#/components/schemas/SandboxGrant'
        expected_grant_hash: { type: string }

    SandboxPreflightResult:
      type: object
      properties:
        verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        reason_code: { type: string }
        grant_id: { type: string }
        grant_hash: { type: string }
        dispatch_ready: { type: boolean }
        findings:
          type: array
          items: { type: string }
        checked_at: { type: string, format: date-time }

    AuthzSnapshot:
      type: object
      properties:
        snapshot_id: { type: string }
        model_id: { type: string }
        relationship_hash: { type: string }
        tuple_count: { type: integer }
        resolver: { type: string }
        stale: { type: boolean }
        snapshot_token: { type: string }
        checked_at: { type: string, format: date-time }
        snapshot_hash: { type: string }

    AuthzHealth:
      type: object
      properties:
        status: { type: string }
        resolver: { type: string }
        model_id: { type: string }
        relationship_hash: { type: string }
        checked_at: { type: string, format: date-time }

    ApprovalCeremony:
      type: object
      properties:
        approval_id: { type: string }
        subject: { type: string }
        action: { type: string }
        state:
          type: string
          enum: [pending, approved, denied, revoked, expired]
        requested_by: { type: string }
        approvers:
          type: array
          items: { type: string }
        quorum: { type: integer }
        timelock_until: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        break_glass: { type: boolean }
        reason: { type: string }
        receipt_id: { type: string }
        ceremony_hash: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    AgentIdentityProfile:
      type: object
      properties:
        agent_id: { type: string }
        identity_type: { type: string }
        subject: { type: string }
        issuer: { type: string }
        jwks_uri: { type: string }
        spiffe_id: { type: string }
        scopes:
          type: array
          items: { type: string }
        anonymous_dev_mode: { type: boolean }
        created_at: { type: string, format: date-time }

    BudgetCeiling:
      type: object
      properties:
        budget_id: { type: string }
        subject: { type: string }
        window: { type: string }
        max_tool_calls: { type: integer }
        max_spend_minor: { type: integer, format: int64 }
        max_egress_bytes: { type: integer, format: int64 }
        max_write_ops: { type: integer }
        approval_required_after: { type: integer }
        policy_epoch: { type: string }

    CoexistenceCapabilityManifest:
      type: object
      properties:
        manifest_id: { type: string }
        authority: { type: string }
        boundary_role: { type: string }
        supported_inputs:
          type: array
          items: { type: string }
        export_surfaces:
          type: array
          items: { type: string }
        receipt_bindings:
          type: array
          items: { type: string }
        generated_at: { type: string, format: date-time }

    TelemetryOTelConfig:
      type: object
      properties:
        service_name: { type: string }
        signal_type: { type: string }
        authoritative: { type: boolean }
        span_attributes:
          type: object
          additionalProperties: { type: string }
        exported_signals:
          type: array
          items: { type: string }

    TelemetryExportRequest:
      type: object
      properties:
        format: { type: string }
        receipt_id: { type: string }
        record_hash: { type: string }
        policy_epoch: { type: string }
        verdict: { type: string }
        reason_code: { type: string }
        sandbox_grant_hash: { type: string }
        authz_snapshot_hash: { type: string }
        attributes:
          type: object
          additionalProperties: { type: string }

    TelemetryExportResult:
      type: object
      properties:
        export_id: { type: string }
        format: { type: string }
        authoritative: { type: boolean }
        attributes:
          type: object
          additionalProperties: { type: string }
        exported_at: { type: string, format: date-time }

    # ── PDP / EffectBoundary Wire Types ────────────────
    Effect:
      type: object
      description: An effect submitted for governance evaluation
      required: [effect_type, effect_id, params]
      properties:
        effect_type:
          type: string
          description: Category of the effect (file_read, api_call, exec, etc.)
        effect_id:
          type: string
          description: Unique identifier for this effect instance
        params:
          type: object
          description: Effect-specific parameters
          additionalProperties: true
        budget_id:
          type: string
          description: Optional budget to charge against

    GovernanceDecision:
      type: object
      description: PDP decision for an effect
      required: [verdict, decision_id, effect_id]
      properties:
        decision_id:
          type: string
        effect_id:
          type: string
        verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        reason_code:
          type: ['string', 'null']
          description: "Null for ALLOW. Registered code from reason-codes-v1.json for DENY/ESCALATE."
        receipt:
          $ref: '#/components/schemas/Receipt'
        active_packs:
          type: array
          items: { type: string }
          description: Names of policy bundles active during evaluation

    EffectBoundary:
      type: object
      description: The boundary contract for submitting effects to the kernel
      required: [effect, principal]
      properties:
        effect:
          $ref: '#/components/schemas/Effect'
        principal:
          type: string
          description: "Agent/user identity (e.g. agent:analyst)"
        context:
          type: object
          description: Additional context (jurisdiction, industry, budget state)
          additionalProperties: true

    PDPRequest:
      type: object
      description: Request to the Policy Decision Point
      required: [boundary]
      properties:
        boundary:
          $ref: '#/components/schemas/EffectBoundary'

    PDPResponse:
      type: object
      description: Response from the Policy Decision Point
      required: [decision]
      properties:
        decision:
          $ref: '#/components/schemas/GovernanceDecision'

    PolicyBundle:
      type: object
      description: A loaded policy bundle (jurisdiction, industry, or business pack)
      required: [name, version, content_hash]
      properties:
        name:
          type: string
        version:
          type: string
        content_hash:
          type: string
          description: SHA-256 of the bundle contents
        signature:
          type: ['string', 'null']
          description: Ed25519 signature over content_hash
        pack_type:
          type: string
          enum: [jurisdiction, industry, business, custom]

  # ── Responses ───────────────────────────────────────
  responses:
    HelmError:
      description: HELM error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HelmError'
          example:
            error:
              message: "Tool not found: unknown_tool"
              type: "invalid_request"
              code: "tool_not_found"
              reason_code: "DENY_TOOL_NOT_FOUND"