openapi: "3.1.0"
info:
  title: HELM Kernel and Platform API
  version: 0.1.1
  description: |
    HELM AI Kernel kernel plus HELM Platform control-plane APIs.
    Governed execution, cryptographic receipts, organizational bootstrap, workspaces, and pack distribution.
  license:
    name: BSL-1.1
    url: https://github.com/Mindburn-Labs/helm-ai-enterprise/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

security:
  - bearerAuth: []

tags:
  - name: proxy
    description: OpenAI-compatible proxy (viral adoption wedge)
  - name: approval
    description: RFC-005 approval ceremonies
  - name: proofgraph
    description: ProofGraph DAG access
  - name: evidence
    description: EvidencePack export and verification
  - name: conformance
    description: Conformance testing
  - name: organization
    description: Organization bootstrap, genesis, and status
  - name: platform
    description: Bootstrap, workspaces, and browser-facing control plane
  - name: company
    description: Company Artifact Graph, should-vs-is detection, and GeneratedSpec loop
  - name: packs
    description: Pack distribution and verification
  - name: launchpad
    description: Workspace-scoped Launchpad app store planning, approvals, execution gates, repair, and teardown
  - name: workstation
    description: Manifest-first workstation governance receipts and selected-effect review
  - name: connectors
    description: Tenant-scoped connector governance wrappers
  - name: system
    description: Health and version
  - name: incidents
    description: Incident lifecycle management
  - name: budget
    description: Budget tracking and alerting
  - name: plans
    description: Plan-Commit pipeline
  - name: blastradius
    description: Blast-radius impact analysis
  - name: notifications
    description: Notification routing and delivery
  - name: trust
    description: Trust anchor and key lifecycle management
  - name: mcp
    description: Model Context Protocol gateway
  - name: failure-intelligence
    description: Public failure-to-control compiler and proof replay archive

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
    - INFRA_DESTROY_BLOCKED
    - ENV_RECREATE_BLOCKED
    - PROTECTED_INFRA_VIOLATION
    - CI_CREDENTIAL_BLOCKED
    - SOFTWARE_PUBLISH_BLOCKED
    - AGENT_INVOKE_ESCALATION
    - DATA_EGRESS_BLOCKED
    - TUNNEL_START_BLOCKED
    - BUDGET_HARD_LIMIT
    - CONTEXT_MISMATCH
    - IDENTITY_ISOLATION_VIOLATION
    - ERROR_INTERNAL

paths:
  # ── 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'

  # ── OSS Console Compatibility ──────────────────────
  /api/v1/console/bootstrap:
    get:
      operationId: getConsoleBootstrap
      tags: [platform]
      summary: Get OSS Console bootstrap state
      responses:
        '200':
          description: Console bootstrap state
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/evaluate:
    post:
      operationId: evaluatePolicy
      tags: [platform]
      summary: Evaluate a policy request through the OSS compatibility surface
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Evaluation result with receipt reference
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'

  /api/v1/receipts:
    get:
      operationId: listReceipts
      tags: [platform]
      summary: List OSS Console compatibility receipts
      responses:
        '200':
          description: Receipt list
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  # ── ProofGraph ──────────────────────────────────────
  /api/v1/proofgraph/sessions:
    get:
      operationId: listSessions
      tags: [proofgraph]
      summary: List ProofGraph sessions
      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'

  /api/v1/proofgraph/sessions/{session_id}/receipts:
    get:
      operationId: getSessionReceipts
      tags: [proofgraph]
      summary: Get receipts for a specific session
      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'

  /api/v1/proofgraph/receipts/{receipt_hash}:
    get:
      operationId: getReceipt
      tags: [proofgraph]
      summary: Get a single receipt by hash
      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'

  # ── EvidencePack ────────────────────────────────────
  /api/v1/evidence/export:
    post:
      operationId: exportEvidence
      tags: [evidence]
      summary: Export an EvidencePack
      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'

  /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/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
      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'

  /api/v1/conformance/reports/{report_id}:
    get:
      operationId: getConformanceReport
      tags: [conformance]
      summary: Get a conformance report by ID
      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'

  # ── Organization / Genesis ─────────────────────────
  /api/org/genesis/start:
    post:
      operationId: startOrgGenesis
      tags: [organization]
      summary: Start an organization genesis ceremony
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgGenesisStartRequest'
      responses:
        '201':
          description: Genesis ceremony started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgGenesisCeremony'
        '400':
          $ref: '#/components/responses/HelmError'

  /api/org/genesis/{id}:
    get:
      operationId: getOrgGenesis
      tags: [organization]
      summary: Fetch an organization genesis ceremony
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Genesis ceremony
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgGenesisCeremony'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/org/genesis/{id}/advance:
    post:
      operationId: advanceOrgGenesis
      tags: [organization]
      summary: Advance an organization genesis ceremony
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgGenesisAdvanceRequest'
      responses:
        '200':
          description: Updated ceremony
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgGenesisCeremony'
        '400':
          $ref: '#/components/responses/HelmError'

  /api/org/status:
    get:
      operationId: getOrgStatus
      tags: [organization]
      summary: Get current organization runtime status
      parameters:
        - name: org_id
          in: query
          required: false
          schema: { type: string }
          description: Canonical organization ID. Defaults to the selected org or the Mindburn Research Lab reference org.
      responses:
        '200':
          description: Organization status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgStatus'

  /api/public/orgs/{org_id}/status:
    get:
      operationId: getPublicOrgStatus
      tags: [organization, evidence]
      summary: Get public proof-bearing runtime status for an organization
      parameters:
        - name: org_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Public organizational runtime snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgStatus'

  /api/public/orgs/{org_id}/timeline:
    get:
      operationId: getPublicOrgTimeline
      tags: [organization, evidence]
      summary: Get public receipt and evidence timeline for an organization
      parameters:
        - name: org_id
          in: path
          required: true
          schema: { type: string }
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 10 }
      responses:
        '200':
          description: Public organization timeline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgTimelineResponse'

  /api/org/runtime/lab-sync:
    post:
      operationId: syncOrganizationRuntime
      tags: [organization]
      summary: Append runtime heartbeat or completed-run state into the organizational runtime read model
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgRuntimeSyncRequest'
      responses:
        '202':
          description: Accepted runtime snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgStatus'

  # ── Platform ───────────────────────────────────────
  /api/bootstrap:
    get:
      operationId: getBootstrap
      tags: [platform]
      summary: Fetch browser bootstrap envelope
      responses:
        '200':
          description: Bootstrap payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BootstrapEnvelope'

  /api/bootstrap/status:
    get:
      operationId: getBootstrapStatus
      tags: [platform]
      summary: Get bootstrap status for a tenant
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Bootstrap status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BootstrapStatus'

  /api/bootstrap/workspace:
    post:
      operationId: provisionWorkspace
      tags: [platform]
      summary: Provision a workspace for a tenant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionWorkspaceRequest'
      responses:
        '201':
          description: Provisioned workspace status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BootstrapStatus'
        '400':
          $ref: '#/components/responses/HelmError'

  /api/workspaces:
    get:
      operationId: listWorkspaces
      tags: [platform]
      summary: List workspaces available to the current session
      responses:
        '200':
          description: Workspace list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceListResponse'
    post:
      operationId: createWorkspace
      tags: [platform]
      summary: Create a workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceRequest'
      responses:
        '201':
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSummary'
        '400':
          $ref: '#/components/responses/HelmError'

  # ── Console Canonical API ─────────────────────────
  # Generated from apps/controlplane/internal/console/route_registry.go
  # and public proof routes in apps/controlplane/internal/http/router.go.
  /api/v1/signing-key:
    get:
      operationId: consoleGetSigningKey
      tags: [evidence]
      summary: Console receipts GET /api/v1/signing-key
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces:
    post:
      operationId: consolePostWorkspaces
      tags: [platform]
      summary: Console workspaces POST /api/v1/workspaces
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

    get:
      operationId: consoleGetWorkspaces
      tags: [platform]
      summary: Console workspaces GET /api/v1/workspaces
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}:
    get:
      operationId: consoleGetWorkspacesId
      tags: [platform]
      summary: Console workspaces GET /api/v1/workspaces/{id}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

    delete:
      operationId: consoleDeleteWorkspacesId
      tags: [platform]
      summary: Console workspaces DELETE /api/v1/workspaces/{id}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Resource deleted
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/runs:
    post:
      operationId: consolePostWorkspacesIdRuns
      tags: [platform]
      summary: Console runs POST /api/v1/workspaces/{id}/runs
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

    get:
      operationId: consoleGetWorkspacesIdRuns
      tags: [platform]
      summary: Console runs GET /api/v1/workspaces/{id}/runs
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/runs/{run_id}:
    get:
      operationId: consoleGetWorkspacesIdRunsRunId
      tags: [platform]
      summary: Console runs GET /api/v1/workspaces/{id}/runs/{run_id}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: run_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/approvals:
    get:
      operationId: consoleGetWorkspacesIdApprovals
      tags: [platform]
      summary: Console approvals GET /api/v1/workspaces/{id}/approvals
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/approvals/{approval_id}:
    get:
      operationId: consoleGetWorkspacesIdApprovalsApprovalId
      tags: [platform]
      summary: Console approvals GET /api/v1/workspaces/{id}/approvals/{approval_id}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: approval_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/approvals/{approval_id}/resolve:
    post:
      operationId: consolePostWorkspacesIdApprovalsApprovalIdResolve
      tags: [platform]
      summary: Console approvals POST /api/v1/workspaces/{id}/approvals/{approval_id}/resolve
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: approval_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/tools/import:
    post:
      operationId: consolePostWorkspacesIdToolsImport
      tags: [platform]
      summary: Console tools POST /api/v1/workspaces/{id}/tools/import
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/tools:
    get:
      operationId: consoleGetWorkspacesIdTools
      tags: [platform]
      summary: Console tools GET /api/v1/workspaces/{id}/tools
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/policy/draft:
    post:
      operationId: consolePostWorkspacesIdPolicyDraft
      tags: [platform]
      summary: Console policy POST /api/v1/workspaces/{id}/policy/draft
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/policy/compile:
    post:
      operationId: consolePostWorkspacesIdPolicyCompile
      tags: [platform]
      summary: Console policy POST /api/v1/workspaces/{id}/policy/compile
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/policy/activate:
    post:
      operationId: consolePostWorkspacesIdPolicyActivate
      tags: [platform]
      summary: Console policy POST /api/v1/workspaces/{id}/policy/activate
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/policy/active:
    get:
      operationId: consoleGetWorkspacesIdPolicyActive
      tags: [platform]
      summary: Console policy GET /api/v1/workspaces/{id}/policy/active
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/simulations:
    post:
      operationId: consolePostWorkspacesIdSimulations
      tags: [platform]
      summary: Console simulations POST /api/v1/workspaces/{id}/simulations
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

    get:
      operationId: consoleGetWorkspacesIdSimulations
      tags: [platform]
      summary: Console simulations GET /api/v1/workspaces/{id}/simulations
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/export:
    post:
      operationId: consolePostWorkspacesIdExport
      tags: [platform]
      summary: Console exports POST /api/v1/workspaces/{id}/export
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/replays:
    get:
      operationId: consoleGetReplays
      tags: [evidence]
      summary: Console replays GET /api/v1/replays
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/replays/{id}:
    get:
      operationId: consoleGetReplaysId
      tags: [evidence]
      summary: Console replays GET /api/v1/replays/{id}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/runs/{run_id}/receipts:
    get:
      operationId: consoleGetWorkspacesIdRunsRunIdReceipts
      tags: [evidence]
      summary: Console receipts GET /api/v1/workspaces/{id}/runs/{run_id}/receipts
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: run_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/verify:
    post:
      operationId: consolePostVerify
      tags: [evidence]
      summary: Console receipts POST /api/v1/verify
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/tasks:
    post:
      operationId: consolePostWorkspacesIdTasks
      tags: [platform]
      summary: Console tasks POST /api/v1/workspaces/{id}/tasks
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

    get:
      operationId: consoleGetWorkspacesIdTasks
      tags: [platform]
      summary: Console tasks GET /api/v1/workspaces/{id}/tasks
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/tasks/{task_id}:
    get:
      operationId: consoleGetWorkspacesIdTasksTaskId
      tags: [platform]
      summary: Console tasks GET /api/v1/workspaces/{id}/tasks/{task_id}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: task_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/tasks/{task_id}/pause:
    post:
      operationId: consolePostWorkspacesIdTasksTaskIdPause
      tags: [platform]
      summary: Console tasks POST /api/v1/workspaces/{id}/tasks/{task_id}/pause
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: task_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/tasks/{task_id}/resume:
    post:
      operationId: consolePostWorkspacesIdTasksTaskIdResume
      tags: [platform]
      summary: Console tasks POST /api/v1/workspaces/{id}/tasks/{task_id}/resume
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: task_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/tasks/{task_id}/cancel:
    post:
      operationId: consolePostWorkspacesIdTasksTaskIdCancel
      tags: [platform]
      summary: Console tasks POST /api/v1/workspaces/{id}/tasks/{task_id}/cancel
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: task_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/actions:
    get:
      operationId: consoleGetWorkspacesIdActions
      tags: [platform]
      summary: Console actions GET /api/v1/workspaces/{id}/actions
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/actions/{pid}:
    get:
      operationId: consoleGetWorkspacesIdActionsPid
      tags: [platform]
      summary: Console actions GET /api/v1/workspaces/{id}/actions/{pid}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: pid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/actions/{pid}/decide:
    post:
      operationId: consolePostWorkspacesIdActionsPidDecide
      tags: [platform]
      summary: Console actions POST /api/v1/workspaces/{id}/actions/{pid}/decide
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: pid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/actions/batch-decide:
    post:
      operationId: consolePostWorkspacesIdActionsBatchDecide
      tags: [platform]
      summary: Console actions POST /api/v1/workspaces/{id}/actions/batch-decide
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/channels:
    get:
      operationId: consoleGetWorkspacesIdChannels
      tags: [platform]
      summary: Console channels GET /api/v1/workspaces/{id}/channels
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/channels/sessions:
    get:
      operationId: consoleGetWorkspacesIdChannelsSessions
      tags: [platform]
      summary: Console channels GET /api/v1/workspaces/{id}/channels/sessions
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/channels/{sessionId}/reply:
    post:
      operationId: consolePostWorkspacesIdChannelsSessionIdReply
      tags: [platform]
      summary: Console channels POST /api/v1/workspaces/{id}/channels/{sessionId}/reply
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sessionId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/channels/{sessionId}/quarantine:
    post:
      operationId: consolePostWorkspacesIdChannelsSessionIdQuarantine
      tags: [platform]
      summary: Console channels POST /api/v1/workspaces/{id}/channels/{sessionId}/quarantine
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sessionId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills:
    get:
      operationId: consoleGetWorkspacesIdSkills
      tags: [platform]
      summary: Console skills GET /api/v1/workspaces/{id}/skills
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/candidates:
    get:
      operationId: consoleGetWorkspacesIdSkillsCandidates
      tags: [platform]
      summary: Console skills GET /api/v1/workspaces/{id}/skills/candidates
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/candidates/{cid}:
    get:
      operationId: consoleGetWorkspacesIdSkillsCandidatesCid
      tags: [platform]
      summary: Console skills GET /api/v1/workspaces/{id}/skills/candidates/{cid}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: cid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/candidates/{cid}/scan:
    post:
      operationId: consolePostWorkspacesIdSkillsCandidatesCidScan
      tags: [platform]
      summary: Console skills POST /api/v1/workspaces/{id}/skills/candidates/{cid}/scan
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: cid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/candidates/{cid}/promote:
    post:
      operationId: consolePostWorkspacesIdSkillsCandidatesCidPromote
      tags: [platform]
      summary: Console skills POST /api/v1/workspaces/{id}/skills/candidates/{cid}/promote
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: cid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/candidates/{cid}/reject:
    post:
      operationId: consolePostWorkspacesIdSkillsCandidatesCidReject
      tags: [platform]
      summary: Console skills POST /api/v1/workspaces/{id}/skills/candidates/{cid}/reject
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: cid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/{sid}/install:
    post:
      operationId: consolePostWorkspacesIdSkillsSidInstall
      tags: [platform]
      summary: Console skills POST /api/v1/workspaces/{id}/skills/{sid}/install
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/{sid}/rollout:
    post:
      operationId: consolePostWorkspacesIdSkillsSidRollout
      tags: [platform]
      summary: Console skills POST /api/v1/workspaces/{id}/skills/{sid}/rollout
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/{sid}/revoke:
    post:
      operationId: consolePostWorkspacesIdSkillsSidRevoke
      tags: [platform]
      summary: Console skills POST /api/v1/workspaces/{id}/skills/{sid}/revoke
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/{sid}/receipts:
    get:
      operationId: consoleGetWorkspacesIdSkillsSidReceipts
      tags: [platform]
      summary: Console skills GET /api/v1/workspaces/{id}/skills/{sid}/receipts
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/{sid}/usage:
    get:
      operationId: consoleGetWorkspacesIdSkillsSidUsage
      tags: [platform]
      summary: Console skills GET /api/v1/workspaces/{id}/skills/{sid}/usage
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/skills/{sid}/drift:
    get:
      operationId: consoleGetWorkspacesIdSkillsSidDrift
      tags: [platform]
      summary: Console skills GET /api/v1/workspaces/{id}/skills/{sid}/drift
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: sid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/knowledge/lks:
    get:
      operationId: consoleGetWorkspacesIdKnowledgeLks
      tags: [platform]
      summary: Console knowledge GET /api/v1/workspaces/{id}/knowledge/lks
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/knowledge/cks:
    get:
      operationId: consoleGetWorkspacesIdKnowledgeCks
      tags: [platform]
      summary: Console knowledge GET /api/v1/workspaces/{id}/knowledge/cks
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/knowledge/{claimId}/promote:
    post:
      operationId: consolePostWorkspacesIdKnowledgeClaimIdPromote
      tags: [platform]
      summary: Console knowledge POST /api/v1/workspaces/{id}/knowledge/{claimId}/promote
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: claimId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/knowledge/{claimId}/reject:
    post:
      operationId: consolePostWorkspacesIdKnowledgeClaimIdReject
      tags: [platform]
      summary: Console knowledge POST /api/v1/workspaces/{id}/knowledge/{claimId}/reject
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: claimId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/evidence/packs:
    get:
      operationId: consoleGetWorkspacesIdEvidencePacks
      tags: [evidence]
      summary: Console evidence GET /api/v1/workspaces/{id}/evidence/packs
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/evidence/export:
    post:
      operationId: consolePostWorkspacesIdEvidenceExport
      tags: [evidence]
      summary: Console evidence POST /api/v1/workspaces/{id}/evidence/export
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/evidence/replay/{rid}:
    get:
      operationId: consoleGetWorkspacesIdEvidenceReplayRid
      tags: [evidence]
      summary: Console evidence GET /api/v1/workspaces/{id}/evidence/replay/{rid}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: rid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/legal-holds:
    get:
      operationId: consoleGetWorkspacesIdLegalHolds
      tags: [platform]
      summary: Console legal-holds GET /api/v1/workspaces/{id}/legal-holds
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

    post:
      operationId: consolePostWorkspacesIdLegalHolds
      tags: [platform]
      summary: Console legal-holds POST /api/v1/workspaces/{id}/legal-holds
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/legal-holds/{hid}:
    get:
      operationId: consoleGetWorkspacesIdLegalHoldsHid
      tags: [platform]
      summary: Console legal-holds GET /api/v1/workspaces/{id}/legal-holds/{hid}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: hid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/legal-holds/{hid}/release:
    post:
      operationId: consolePostWorkspacesIdLegalHoldsHidRelease
      tags: [platform]
      summary: Console legal-holds POST /api/v1/workspaces/{id}/legal-holds/{hid}/release
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: hid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/jurisdictions:
    get:
      operationId: consoleGetWorkspacesIdJurisdictions
      tags: [platform]
      summary: Console jurisdictions GET /api/v1/workspaces/{id}/jurisdictions
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/connectors/ton-acton:
    get:
      operationId: consoleGetWorkspacesIdConnectorsTonActon
      tags: [connectors]
      summary: Console connectors GET /api/v1/workspaces/{id}/connectors/ton-acton
      description: |
        Returns tenant-scoped TON Acton governance configuration. The wrapper exposes OSS connector contract metadata and evidence references only; it does not execute Acton commands.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: TON Acton connector configuration
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'
    put:
      operationId: consolePutWorkspacesIdConnectorsTonActon
      tags: [connectors]
      summary: Console connectors PUT /api/v1/workspaces/{id}/connectors/ton-acton
      description: |
        Updates tenant-scoped TON Acton governance configuration, wallet references, evidence retention, and public-proof references. Secrets and mnemonic material are rejected.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Updated TON Acton connector configuration
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/connectors/ton-acton/timeline:
    get:
      operationId: consoleGetWorkspacesIdConnectorsTonActonTimeline
      tags: [connectors]
      summary: Console connectors GET /api/v1/workspaces/{id}/connectors/ton-acton/timeline
      description: |
        Returns the TON Acton deployment and approval timeline derived from tenant wrapper state and existing approval ceremony records.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: TON Acton deployment timeline
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/connectors/ton-acton/approval-requests:
    post:
      operationId: consolePostWorkspacesIdConnectorsTonActonApprovalRequests
      tags: [connectors]
      summary: Console connectors POST /api/v1/workspaces/{id}/connectors/ton-acton/approval-requests
      description: |
        Enqueues a TON Acton T3 approval ceremony request through the existing approval store. The endpoint records escalation state and never dispatches Acton.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '202':
          description: TON Acton approval request accepted
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/marketplace/connectors:
    get:
      operationId: consoleGetMarketplaceConnectors
      tags: [packs]
      summary: Console marketplace GET /api/v1/marketplace/connectors
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/marketplace/connectors/{cid}:
    get:
      operationId: consoleGetMarketplaceConnectorsCid
      tags: [packs]
      summary: Console marketplace GET /api/v1/marketplace/connectors/{cid}
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: cid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/marketplace/connectors/{cid}/versions:
    get:
      operationId: consoleGetMarketplaceConnectorsCidVersions
      tags: [packs]
      summary: Console marketplace GET /api/v1/marketplace/connectors/{cid}/versions
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: cid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/marketplace/connectors/{cid}/install:
    post:
      operationId: consolePostMarketplaceConnectorsCidInstall
      tags: [packs]
      summary: Console marketplace POST /api/v1/marketplace/connectors/{cid}/install
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: cid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/marketplace/connectors/{cid}/disable:
    post:
      operationId: consolePostMarketplaceConnectorsCidDisable
      tags: [packs]
      summary: Console marketplace POST /api/v1/marketplace/connectors/{cid}/disable
      description: |
        Canonical Console route served by the Control Plane. Mutations require authenticated tenant/workspace authority and fail closed through structured HELM errors.
      parameters:
        - name: cid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/apps:
    get:
      operationId: consoleLaunchpadApps
      tags: [launchpad]
      summary: List workspace-visible Launchpad apps
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Launchpad catalog apps with kernel registry digest
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/substrates:
    get:
      operationId: consoleLaunchpadSubstrates
      tags: [launchpad]
      summary: List Launchpad substrates
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Local/container/cloud substrates
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/matrix:
    get:
      operationId: consoleLaunchpadMatrix
      tags: [launchpad]
      summary: List app x substrate launchability matrix
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Computed launchability cells
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/plan:
    post:
      operationId: consoleLaunchpadPlan
      tags: [launchpad]
      summary: Create a durable Launchpad plan
      description: |
        Creates a LaunchRun, GeneratedSpec, ActionProposal, approval request, receipt refs, retention ref, and EvidencePack refs. This route does not execute side effects.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [app_id, substrate_id]
              properties:
                app_id: { type: string }
                app_version: { type: string }
                substrate_id: { type: string }
                provider: { type: string }
                channel: { type: string }
                install_mode: { type: string }
      responses:
        '201':
          description: Launch plan with approval, certification, retention, redaction, and evidence references
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '422':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/launch:
    post:
      operationId: consoleLaunchpadLaunch
      tags: [launchpad]
      summary: Plan a launch through the app-store action
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '202':
          description: Accepted launch plan; execution still requires explicit execute after approval gates
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/launches:
    get:
      operationId: consoleLaunchpadLaunches
      tags: [launchpad]
      summary: List durable Launchpad runs for reload-safe UI
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Launch runs
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/workspaces/{id}/launchpad/launches/{launch_id}:
    get:
      operationId: consoleLaunchpadGetLaunch
      tags: [launchpad]
      summary: Get a durable Launchpad run
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: launch_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Launch run
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/audit:
    get:
      operationId: consoleLaunchpadExportAudit
      tags: [launchpad]
      summary: Export a redacted Launchpad audit record
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: launch_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Redacted audit export for the launch
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/evidence:
    get:
      operationId: consoleLaunchpadExportEvidence
      tags: [launchpad]
      summary: Export Launchpad EvidencePack refs and verifier command
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: launch_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: EvidencePack refs and offline verifier command
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/execute:
    post:
      operationId: consoleLaunchpadExecute
      tags: [launchpad]
      summary: Execute an approved Launchpad run if all strict gates pass
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: launch_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                approval_id: { type: string, format: uuid }
                provider: { type: string }
      responses:
        '202':
          description: Launch executed and runtime/provider handles recorded
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '409':
          description: Fail-closed gate response with blocked reasons and launch state
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/repair:
    post:
      operationId: consoleLaunchpadRepair
      tags: [launchpad]
      summary: Build a Launchpad repair plan
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: launch_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Repair plan
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/delete:
    post:
      operationId: consoleLaunchpadDelete
      tags: [launchpad]
      summary: Tear down a Launchpad run and record teardown receipt refs
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: launch_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '202':
          description: Teardown accepted and receipt refs recorded
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/workspaces/{id}/launchpad/repair:
    post:
      operationId: consoleLaunchpadRepairByBody
      tags: [launchpad]
      summary: Build a Launchpad repair plan by request body launch_id
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [launch_id]
              properties:
                launch_id: { type: string, format: uuid }
      responses:
        '200':
          description: Repair plan
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/workspaces/{id}/launchpad/delete:
    post:
      operationId: consoleLaunchpadDeleteByBody
      tags: [launchpad]
      summary: Tear down a Launchpad run by request body launch_id
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [launch_id]
              properties:
                launch_id: { type: string, format: uuid }
                force: { type: boolean }
      responses:
        '202':
          description: Teardown accepted and receipt refs recorded
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/failure-intelligence/runs:
    post:
      operationId: failureIntelligenceRun
      tags: [failure-intelligence]
      summary: Run the HELM Failure Intelligence Loop against fixture-backed public sources
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailureIntelligenceRunRequest'
      responses:
        '202':
          description: Failure intelligence run accepted and processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureIntelligenceRunResult'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
    get:
      operationId: failureIntelligenceListRuns
      tags: [failure-intelligence]
      summary: List HELM Failure Intelligence Loop production runs
      responses:
        '200':
          description: Failure intelligence runs
          content:
            application/json:
              schema:
                type: object
                required: [runs]
                properties:
                  runs:
                    type: array
                    items: { $ref: '#/components/schemas/FailureIntelligenceRunResult' }
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/runs/{runId}:
    get:
      operationId: failureIntelligenceGetRun
      tags: [failure-intelligence]
      summary: Get a HELM Failure Intelligence Loop run
      parameters:
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Failure intelligence run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureIntelligenceRunResult'
        '404':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/sources:
    get:
      operationId: failureIntelligenceListSources
      tags: [failure-intelligence]
      summary: List public failure source registries
      responses:
        '200':
          description: Failure intelligence source registries
          content:
            application/json:
              schema:
                type: object
                required: [sources]
                properties:
                  sources:
                    type: array
                    items: { $ref: '#/components/schemas/SourceRegistry' }
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/sources/{sourceId}/health:
    get:
      operationId: failureIntelligenceSourceHealth
      tags: [failure-intelligence]
      summary: Get source adapter health for public failure discovery
      parameters:
        - name: sourceId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Source health
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureIntelligenceSourceHealth'
        '404':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/candidates:
    get:
      operationId: failureIntelligenceListCandidates
      tags: [failure-intelligence]
      summary: List external public failure candidates
      responses:
        '200':
          description: External incident candidates
          content:
            application/json:
              schema:
                type: object
                required: [candidates]
                properties:
                  candidates:
                    type: array
                    items: { $ref: '#/components/schemas/ExternalIncidentCandidate' }
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays:
    get:
      operationId: failureIntelligenceListReplays
      tags: [failure-intelligence]
      summary: List generated counterfactual proof replays
      responses:
        '200':
          description: Counterfactual replay list
          content:
            application/json:
              schema:
                type: object
                required: [replays]
                properties:
                  replays:
                    type: array
                    items: { $ref: '#/components/schemas/CounterfactualReplay' }
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays/{id}/approve:
    post:
      operationId: failureIntelligenceApproveReplay
      tags: [failure-intelligence]
      summary: Approve a redaction-safe counterfactual proof replay for publication
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reviewer: { type: string }
                reason: { type: string }
      responses:
        '200':
          description: Approved replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterfactualReplay'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays/{id}/publish:
    post:
      operationId: failureIntelligencePublishReplay
      tags: [failure-intelligence]
      summary: Publish an approved counterfactual proof replay to the public archive
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Published archive entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofReplayArchiveEntry'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays/{id}/revoke-publication:
    post:
      operationId: failureIntelligenceRevokePublication
      tags: [failure-intelligence]
      summary: Revoke a previously published counterfactual proof replay
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reviewer: { type: string }
                reason: { type: string }
      responses:
        '200':
          description: Revoked replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterfactualReplay'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays/{id}/reject:
    post:
      operationId: failureIntelligenceRejectReplay
      tags: [failure-intelligence]
      summary: Reject a counterfactual proof replay for public publication
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reviewer: { type: string }
                reason: { type: string }
      responses:
        '200':
          description: Rejected replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterfactualReplay'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays/{id}/legal-review:
    post:
      operationId: failureIntelligenceLegalReviewReplay
      tags: [failure-intelligence]
      summary: Mark a counterfactual proof replay as requiring legal review
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reviewer: { type: string }
                reason: { type: string }
      responses:
        '200':
          description: Replay marked for legal review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterfactualReplay'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays/{id}/export-vector:
    post:
      operationId: failureIntelligenceExportReplayVector
      tags: [failure-intelligence]
      summary: Export Kernel-owned conformance vector bundle draft for a proof replay
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '202':
          description: Vector export batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureIntelligenceExportBatch'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/replays/{id}/kernel-validation:
    post:
      operationId: failureIntelligenceImportKernelValidation
      tags: [failure-intelligence]
      summary: Import signed Kernel HCV validation and governed GitHub merge evidence
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KernelValidationImportRequest'
      responses:
        '200':
          description: Kernel-validated replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterfactualReplay'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/v1/failure-intelligence/archive/export:
    post:
      operationId: failureIntelligenceExportArchive
      tags: [failure-intelligence]
      summary: Export deterministic public proof replay archive artifacts
      responses:
        '202':
          description: Archive export batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureIntelligenceExportBatch'
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'

  /api/public/proof-replays:
    get:
      operationId: publicProofReplayArchive
      tags: [failure-intelligence]
      summary: List public HELM Proof Replay Archive entries
      security: []
      responses:
        '200':
          description: Public proof replay archive index
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofReplayArchiveIndex'

  /api/public/proof-replays/{hprId}:
    get:
      operationId: publicProofReplayArchiveEntry
      tags: [failure-intelligence]
      summary: Get a public HELM Proof Replay Archive entry
      security: []
      parameters:
        - name: hprId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Public proof replay entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofReplayArchiveEntry'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/public/proof-replays/rss.xml:
    get:
      operationId: publicProofReplayArchiveRSS
      tags: [failure-intelligence]
      summary: Public HELM Proof Replay Archive RSS feed
      security: []
      responses:
        '200':
          description: RSS feed
          content:
            application/rss+xml:
              schema:
                type: string

  /api/public/verify/{receiptId}:
    get:
      operationId: publicProofGetVerifyReceiptId
      tags: [evidence]
      summary: Public proof GET /api/public/verify/{receiptId}
      description: |
        Public verification surface served by the canonical controlplane. Responses are policy-redacted and must not expose tenant internals or raw sensitive evidence.
      parameters:
        - name: receiptId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/public/evidence/{bundleId}:
    get:
      operationId: publicProofGetEvidenceBundleId
      tags: [evidence]
      summary: Public proof GET /api/public/evidence/{bundleId}
      description: |
        Public verification surface served by the canonical controlplane. Responses are policy-redacted and must not expose tenant internals or raw sensitive evidence.
      parameters:
        - name: bundleId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  /api/public/approval/{approvalId}:
    get:
      operationId: publicProofGetApprovalApprovalId
      tags: [evidence]
      summary: Public proof GET /api/public/approval/{approvalId}
      description: |
        Public verification surface served by the canonical controlplane. Responses are policy-redacted and must not expose tenant internals or raw sensitive evidence.
      parameters:
        - name: approvalId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Successful controlplane response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/HelmError'
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '404':
          $ref: '#/components/responses/HelmError'

  # ── Packs ──────────────────────────────────────────
  /api/packs:
    get:
      operationId: listPlatformPacks
      tags: [packs]
      summary: List packs exposed by the platform registry
      responses:
        '200':
          description: Pack list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PacksResponse'

  # ── 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"

  # ── Trust ───────────────────────────────────────────
  /api/v1/trust/keys/add:
    post:
      operationId: addTrustKey
      tags: [trust]
      summary: Add a trusted Ed25519 public key for a tenant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              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
      responses:
        '200':
          description: Trust key added
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: key_added }
                  tenant_id: { type: string }
                  key_id: { type: string }
        '400':
          $ref: '#/components/responses/HelmError'
        '500':
          $ref: '#/components/responses/HelmError'

  /api/v1/trust/keys/revoke:
    post:
      operationId: revokeTrustKey
      tags: [trust]
      summary: Revoke a trusted key for a tenant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tenant_id, key_id]
              properties:
                tenant_id: { type: string }
                key_id: { type: string }
      responses:
        '200':
          description: Trust key revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: key_revoked }
                  tenant_id: { type: string }
                  key_id: { type: string }
        '400':
          $ref: '#/components/responses/HelmError'
        '500':
          $ref: '#/components/responses/HelmError'

  # ── Kernel Local Diagnostics ───────────────────────────
  /api/v1/kernel-local/summary:
    get:
      operationId: getKernelLocalSummary
      tags: [platform]
      summary: Return the OSS-local runtime and evidence summary
      responses:
        '200':
          description: OSS-local summary
          content:
            application/json:
              schema:
                type: object

  /api/v1/kernel-local/decision-timeline:
    get:
      operationId: getKernelLocalDecisionTimeline
      tags: [platform]
      summary: Return the latest OSS-local decisions and receipt timeline
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 50 }
      responses:
        '200':
          description: OSS-local decision timeline
          content:
            application/json:
              schema:
                type: object

  /api/v1/kernel-local/replay-report:
    get:
      operationId: getKernelLocalReplayReport
      tags: [platform]
      summary: Return the latest OSS-local replay report
      responses:
        '200':
          description: OSS-local replay report
          content:
            application/json:
              schema:
                type: object
        '500':
          $ref: '#/components/responses/HelmError'

  /api/v1/kernel-local/capabilities:
    get:
      operationId: getKernelLocalCapabilities
      tags: [platform]
      summary: Describe OSS-local control-plane and MCP capabilities
      responses:
        '200':
          description: OSS-local capabilities
          content:
            application/json:
              schema:
                type: object

  # ── MCP Gateway ─────────────────────────────────────
  /mcp:
    post:
      operationId: mcpRoot
      tags: [mcp]
      summary: MCP JSON-RPC entrypoint for governed tool clients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: MCP response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'

  /.well-known/oauth-protected-resource/mcp:
    get:
      operationId: getMcpProtectedResourceMetadata
      tags: [mcp]
      summary: OAuth protected resource metadata for the MCP endpoint
      responses:
        '200':
          description: OAuth protected resource metadata
          content:
            application/json:
              schema:
                type: object

  /mcp/v1/capabilities:
    get:
      operationId: listMCPCapabilities
      tags: [mcp]
      summary: List gateway capabilities for MCP clients
      responses:
        '200':
          description: MCP capabilities response
          content:
            application/json:
              schema:
                type: object

  /mcp/v1/execute:
    post:
      operationId: executeMCPTool
      tags: [mcp]
      summary: Execute an MCP tool call through the governed gateway
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: MCP execution result
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/HelmError'
        '403':
          $ref: '#/components/responses/HelmError'
        '500':
          $ref: '#/components/responses/HelmError'

  # ── Incidents ───────────────────────────────────────
  /api/basic/incidents:
    get:
      operationId: listIncidents
      tags: [incidents]
      summary: List active incidents
      responses:
        '200':
          description: Array of incident objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Incident'
    post:
      operationId: createIncident
      tags: [incidents]
      summary: Create a new incident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, severity, tenant_id]
              properties:
                title: { type: string }
                description: { type: string }
                severity: { type: string, enum: [P0, P1, P2, P3] }
                tenant_id: { type: string }
                reported_by: { type: string }
                is_drill: { type: boolean, default: false }
      responses:
        '201':
          description: Incident created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
        '400':
          $ref: '#/components/responses/HelmError'

  /api/basic/incidents/transition:
    post:
      operationId: transitionIncident
      tags: [incidents]
      summary: Transition incident state
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [incident_id, action, actor]
              properties:
                incident_id: { type: string }
                action: { type: string, enum: [ACKNOWLEDGED, INVESTIGATING, MITIGATING, RESOLVED, POSTMORTEM] }
                actor: { type: string }
                note: { type: string }
      responses:
        '200':
          description: Transition applied
        '400':
          $ref: '#/components/responses/HelmError'

  # ── Budget ──────────────────────────────────────────
  /api/basic/budget/record:
    post:
      operationId: recordBudgetSpend
      tags: [budget]
      summary: Record a budget spend entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tenant_id, category, amount_cents]
              properties:
                tenant_id: { type: string }
                category: { type: string }
                amount_cents: { type: integer, minimum: 1 }
                label: { type: string }
                agent: { type: string }
      responses:
        '201':
          description: Spend recorded
        '400':
          $ref: '#/components/responses/HelmError'

  /api/basic/budget/summary:
    get:
      operationId: getBudgetSummary
      tags: [budget]
      summary: Get budget summary for a tenant (30-day window)
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Budget summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetSummary'

  # ── Plans ───────────────────────────────────────────
  /api/basic/plans:
    post:
      operationId: submitPlan
      tags: [plans]
      summary: Submit an effect plan for analysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan_id, tenant_id, submitted_by, effects]
              properties:
                plan_id: { type: string }
                tenant_id: { type: string }
                submitted_by: { type: string }
                effects:
                  type: array
                  items:
                    $ref: '#/components/schemas/EffectPlan'
      responses:
        '201':
          description: Plan submitted and analyzed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '400':
          $ref: '#/components/responses/HelmError'

  /api/basic/plans/approve:
    post:
      operationId: approvePlan
      tags: [plans]
      summary: Approve a pending plan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan_id, approved_by]
              properties:
                plan_id: { type: string }
                approved_by: { type: string }
      responses:
        '200':
          description: Plan approved
        '400':
          $ref: '#/components/responses/HelmError'

  /api/basic/plans/commit:
    post:
      operationId: commitPlan
      tags: [plans]
      summary: Commit an approved plan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan_id]
              properties:
                plan_id: { type: string }
      responses:
        '200':
          description: Plan committed
        '400':
          $ref: '#/components/responses/HelmError'

  # ── Blast Radius ────────────────────────────────────
  /api/basic/blastradius:
    post:
      operationId: calculateBlastRadius
      tags: [blastradius]
      summary: Compute blast-radius report for an effect plan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan_id, effects]
              properties:
                plan_id: { type: string }
                effects:
                  type: array
                  items:
                    $ref: '#/components/schemas/EffectPlan'
      responses:
        '200':
          description: Blast-radius report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlastRadiusReport'
        '400':
          $ref: '#/components/responses/HelmError'

  # ── Notifications ───────────────────────────────────
  /api/basic/notifications/subscribe:
    post:
      operationId: subscribeNotification
      tags: [notifications]
      summary: Create a notification subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, tenant_id, event_types, channel]
              properties:
                id: { type: string }
                tenant_id: { type: string }
                event_types:
                  type: array
                  items: { type: string }
                min_severity: { type: string, enum: [INFO, WARNING, CRITICAL, URGENT] }
                channel: { type: string, enum: [in_memory, webhook, slack, pagerduty] }
                endpoint: { type: string }
      responses:
        '201':
          description: Subscription created
        '400':
          $ref: '#/components/responses/HelmError'

  /api/basic/notifications/emit:
    post:
      operationId: emitNotification
      tags: [notifications]
      summary: Emit a notification event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [event_id, event_type, severity, tenant_id]
              properties:
                event_id: { type: string }
                event_type: { type: string }
                severity: { type: string, enum: [INFO, WARNING, CRITICAL, URGENT] }
                tenant_id: { type: string }
                source_id: { type: string }
                summary: { type: string }
                payload: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Event emitted
        '400':
          $ref: '#/components/responses/HelmError'

  /api/v1/workspaces/{id}/company/artifacts:
    get:
      tags: [company]
      summary: List company artifacts
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Company artifacts
          content:
            application/json:
              schema:
                type: object
                properties:
                  artifacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyArtifact'
                  count: { type: integer }
    post:
      tags: [company]
      summary: Create a company artifact
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyArtifact'
      responses:
        '201':
          description: Created company artifact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyArtifact'

  /api/v1/workspaces/{id}/company/artifacts/{artifact_id}/promote:
    post:
      tags: [company]
      summary: Promote a draft company artifact to canonical with audit evidence
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: artifact_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyArtifactTransitionRequest'
      responses:
        '200':
          description: Promoted company artifact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyArtifact'

  /api/v1/workspaces/{id}/company/artifacts/{artifact_id}/dispute:
    post:
      tags: [company]
      summary: Mark a company artifact as disputed with audit evidence
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: artifact_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyArtifactTransitionRequest'
      responses:
        '200':
          description: Disputed company artifact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyArtifact'

  /api/v1/workspaces/{id}/company/artifacts/{artifact_id}/stale:
    post:
      tags: [company]
      summary: Mark a company artifact as stale with audit evidence
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: artifact_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyArtifactTransitionRequest'
      responses:
        '200':
          description: Stale company artifact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyArtifact'

  /api/v1/workspaces/{id}/company/artifacts/{artifact_id}/archive:
    post:
      tags: [company]
      summary: Archive a company artifact with audit evidence
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: artifact_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyArtifactTransitionRequest'
      responses:
        '200':
          description: Archived company artifact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyArtifact'

  /api/v1/workspaces/{id}/company/graph:
    get:
      tags: [company]
      summary: Get the Company Artifact Graph
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Company Artifact Graph
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyArtifactGraph'

  /api/v1/workspaces/{id}/company/edges:
    post:
      tags: [company]
      summary: Create a Company Artifact Graph edge
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyArtifactEdge'
      responses:
        '201':
          description: Created company artifact edge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyArtifactEdge'

  /api/v1/workspaces/{id}/company/conflicts:
    get:
      tags: [company]
      summary: List truth conflicts
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Truth conflicts
          content:
            application/json:
              schema:
                type: object
                properties:
                  conflicts:
                    type: array
                    items:
                      $ref: '#/components/schemas/TruthConflict'
                  count: { type: integer }
    post:
      tags: [company]
      summary: Create a truth conflict or run should-vs-is detection
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTruthConflictRequest'
      responses:
        '201':
          description: Created truth conflict or should-vs-is detection result

  /api/v1/workspaces/{id}/company/drift:
    get:
      tags: [company]
      summary: List drift signals
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Drift signals
          content:
            application/json:
              schema:
                type: object
                properties:
                  drift:
                    type: array
                    items:
                      $ref: '#/components/schemas/DriftSignal'
                  count: { type: integer }
    post:
      tags: [company]
      summary: Create a drift signal
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriftSignal'
      responses:
        '201':
          description: Created drift signal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftSignal'

  /api/v1/workspaces/{id}/generated-specs:
    get:
      tags: [company]
      summary: List GeneratedSpecs
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: GeneratedSpecs
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated_specs:
                    type: array
                    items:
                      $ref: '#/components/schemas/GeneratedSpec'
                  count: { type: integer }
    post:
      tags: [company]
      summary: Create a GeneratedSpec
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratedSpec'
      responses:
        '201':
          description: Created GeneratedSpec
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSpec'

  /api/v1/workspaces/{id}/generated-specs/{sid}/approve:
    post:
      tags: [company]
      summary: Approve a reviewed GeneratedSpec with policy evidence
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: sid
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratedSpecTransitionRequest'
      responses:
        '200':
          description: Approved GeneratedSpec
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSpec'

  /api/v1/workspaces/{id}/generated-specs/{sid}/review:
    post:
      tags: [company]
      summary: Review a draft GeneratedSpec against source evidence
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: sid
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratedSpecTransitionRequest'
      responses:
        '200':
          description: Reviewed GeneratedSpec
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSpec'

  /api/v1/workspaces/{id}/generated-specs/{sid}/execution-request:
    post:
      tags: [company]
      summary: Request execution through the HELM boundary for an approved GeneratedSpec
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: sid
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratedSpecTransitionRequest'
      responses:
        '202':
          description: Execution requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSpecExecutionResponse'

  /api/v1/workspaces/{id}/generated-specs/{sid}/boundary-result:
    post:
      tags: [company]
      summary: Record HELM boundary verdict, receipts, and EvidencePack refs
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: sid
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratedSpecTransitionRequest'
      responses:
        '200':
          description: Boundary result recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSpecExecutionResponse'

  /api/v1/workspaces/{id}/generated-specs/{sid}/closure-evidence:
    post:
      tags: [company]
      summary: Attach closure evidence after terminal boundary state
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: sid
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratedSpecTransitionRequest'
      responses:
        '200':
          description: Closure evidence attached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSpec'

  /api/v1/workspaces/{id}/generated-specs/{sid}/close:
    post:
      tags: [company]
      summary: Close a GeneratedSpec only after closure evidence and boundary proof
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: sid
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratedSpecTransitionRequest'
      responses:
        '200':
          description: Closed GeneratedSpec
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSpec'

  /api/v1/workspaces/{id}/harness/state:
    get:
      tags: [harness]
      summary: Get workspace harness state
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Harness state
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/workspaces/{id}/harness/traces:
    get:
      tags: [harness]
      summary: List harness traces
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Harness traces
          content:
            application/json:
              schema:
                type: object
                properties:
                  harness_traces:
                    type: array
                    items:
                      $ref: '#/components/schemas/HarnessTraceRecord'
                  count: { type: integer }
    post:
      tags: [harness]
      summary: Create a harness trace
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HarnessTraceRecord'
      responses:
        '201':
          description: Created harness trace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HarnessTraceRecord'

  /api/v1/workspaces/{id}/harness/traces/{tid}:
    get:
      tags: [harness]
      summary: Get a harness trace
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: tid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Harness trace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HarnessTraceRecord'

  /api/v1/workspaces/{id}/verification-scopes:
    get:
      tags: [harness]
      summary: List verification scopes
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Verification scopes
          content:
            application/json:
              schema:
                type: object
                properties:
                  verification_scopes:
                    type: array
                    items:
                      $ref: '#/components/schemas/VerificationScopeRecord'
                  count: { type: integer }
    post:
      tags: [harness]
      summary: Create a verification scope
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationScopeRecord'
      responses:
        '201':
          description: Created verification scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationScopeRecord'

  /api/v1/workspaces/{id}/verification-scopes/{vid}:
    get:
      tags: [harness]
      summary: Get a verification scope
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: vid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Verification scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationScopeRecord'

  /api/v1/workspaces/{id}/plan-transactions:
    get:
      tags: [harness]
      summary: List plan transactions
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Plan transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan_transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlanTransactionRecord'
                  count: { type: integer }
    post:
      tags: [harness]
      summary: Create a plan transaction
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanTransactionRecord'
      responses:
        '201':
          description: Created plan transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanTransactionRecord'

  /api/v1/workspaces/{id}/plan-transactions/{pid}:
    get:
      tags: [harness]
      summary: Get a plan transaction
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: pid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Plan transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanTransactionRecord'

  /api/v1/workspaces/{id}/plan-transactions/{pid}/conflict-check:
    post:
      tags: [harness]
      summary: Check a plan transaction write set against open GeneratedSpecs
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: pid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Conflict check
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/v1/workspaces/{id}/harness/change-contracts:
    get:
      tags: [harness]
      summary: List harness change contracts
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Harness change contracts
          content:
            application/json:
              schema:
                type: object
                properties:
                  harness_change_contracts:
                    type: array
                    items:
                      $ref: '#/components/schemas/HarnessChangeContractRecord'
                  count: { type: integer }
    post:
      tags: [harness]
      summary: Create a harness change contract
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HarnessChangeContractRecord'
      responses:
        '201':
          description: Created harness change contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HarnessChangeContractRecord'

  /api/v1/workspaces/{id}/harness/change-contracts/{cid}:
    get:
      tags: [harness]
      summary: Get a harness change contract
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: cid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Harness change contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HarnessChangeContractRecord'

  /api/v1/workspaces/{id}/harness/change-contracts/{cid}/approve:
    post:
      tags: [harness]
      summary: Approve a harness change contract
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: cid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Approved harness change contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HarnessChangeContractRecord'

  /api/v1/workspaces/{id}/harness/change-contracts/{cid}/activate:
    post:
      tags: [harness]
      summary: Activate a harness change contract
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: cid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Activated harness change contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HarnessChangeContractRecord'

  /api/v1/workspaces/{id}/evidence/confidence:
    get:
      tags: [harness]
      summary: List evidence confidence records
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Evidence confidence records
          content:
            application/json:
              schema:
                type: object
                properties:
                  evidence_confidence:
                    type: array
                    items:
                      $ref: '#/components/schemas/EvidenceConfidenceRecord'
                  count: { type: integer }
    post:
      tags: [harness]
      summary: Create an evidence confidence record
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvidenceConfidenceRecord'
      responses:
        '201':
          description: Created evidence confidence record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceConfidenceRecord'

  /api/v1/workspaces/{id}/evidence/confidence/{subject_hash}:
    get:
      tags: [harness]
      summary: Get latest evidence confidence for a subject hash
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: subject_hash
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Evidence confidence record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceConfidenceRecord'

  /api/v1/workspaces/{id}/orggenome/compiler/runs:
    get:
      tags: [orggenome]
      summary: List OrgGenome compiler runs
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: OrgGenome compiler runs
          content:
            application/json:
              schema:
                type: object
                properties:
                  runs:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrgGenomeCompilerRun'
                  count: { type: integer }
    post:
      tags: [orggenome]
      summary: Record an OrgGenome compiler request/result for draft import
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request:
                  $ref: '#/components/schemas/OrgGenomeCompilerRequest'
                result:
                  $ref: '#/components/schemas/OrgGenomeCompilerResult'
      responses:
        '201':
          description: Created compiler run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgGenomeCompilerRun'

  /api/v1/workspaces/{id}/orggenome/compiler/runs/{rid}:
    get:
      tags: [orggenome]
      summary: Get an OrgGenome compiler run
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: rid
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: OrgGenome compiler run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgGenomeCompilerRun'

  /api/v1/workspaces/{id}/orggenome/compiler/runs/{rid}/import:
    post:
      tags: [orggenome]
      summary: Import compiler output as draft company state only
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: rid
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgGenomeCompilerResult'
      responses:
        '201':
          description: Draft import result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgGenomeCompilerImportResult'

  /api/v1/workspaces/{id}/connector-inventory:
    get:
      tags: [connectors]
      summary: List workspace connector inventory records
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Connector inventory records
          content:
            application/json:
              schema:
                type: object
                properties:
                  connector_inventory:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectorInventory'
                  count: { type: integer }
    post:
      tags: [connectors]
      summary: Create a connector inventory record
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorInventory'
      responses:
        '201':
          description: Created connector inventory record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorInventory'

  /api/v1/workspaces/{id}/connector-contracts:
    get:
      tags: [connectors]
      summary: List workspace connector contracts
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Connector contracts
          content:
            application/json:
              schema:
                type: object
                properties:
                  connector_contracts:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectorContract'
                  count: { type: integer }
    post:
      tags: [connectors]
      summary: Create a connector contract
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorContract'
      responses:
        '201':
          description: Created connector contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorContract'

  /api/v1/workspaces/{id}/connector-contracts/drift-check:
    post:
      tags: [connectors]
      summary: Check a connector observation against the pinned contract and fail closed on drift
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorDriftCheckRequest'
      responses:
        '200':
          description: Connector drift verdict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorDriftCheckResult'

  /api/v1/workspaces/{id}/tool-registry:
    get:
      tags: [tools]
      summary: List workspace tool registry entries
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Tool registry entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  tool_registry:
                    type: array
                    items:
                      $ref: '#/components/schemas/ToolRegistryEntry'
                  count: { type: integer }
    post:
      tags: [tools]
      summary: Create a tool registry entry
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolRegistryEntry'
      responses:
        '201':
          description: Created tool registry entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolRegistryEntry'

  /api/v1/workspaces/{id}/sandbox-grants:
    get:
      tags: [sandbox]
      summary: List workspace sandbox grants
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Sandbox grants
          content:
            application/json:
              schema:
                type: object
                properties:
                  sandbox_grants:
                    type: array
                    items:
                      $ref: '#/components/schemas/SandboxGrant'
                  count: { type: integer }
    post:
      tags: [sandbox]
      summary: Create a sandbox grant
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxGrant'
      responses:
        '201':
          description: Created sandbox grant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGrant'

  /api/v1/workspaces/{id}/mcp-approvals:
    get:
      tags: [mcp]
      summary: List MCP approval and quarantine records
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: MCP approvals
          content:
            application/json:
              schema:
                type: object
                properties:
                  mcp_approvals:
                    type: array
                    items:
                      $ref: '#/components/schemas/MCPApprovalRecord'
                  count: { type: integer }
    post:
      tags: [mcp]
      summary: Create an MCP approval record
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPApprovalRecord'
      responses:
        '201':
          description: Created MCP approval record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPApprovalRecord'

  /api/v1/workspaces/{id}/mcp-approvals/evaluate:
    post:
      tags: [mcp]
      summary: Evaluate whether an MCP server/tool is approved or quarantined
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPEvaluationRequest'
      responses:
        '200':
          description: MCP quarantine verdict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPEvaluationResponse'

  # ── Agent UI ────────────────────────────────────────
  /api/ag-ui/info:
    get:
      operationId: getAgUiInfo
      tags: [platform]
      summary: Get public AG-UI capability metadata
      responses:
        '200':
          description: AG-UI metadata
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }

  /api/ag-ui/run:
    post:
      operationId: runAgUiRequest
      tags: [platform]
      summary: Run an AG-UI request through the Console frontend facade
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: AG-UI run response
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/info:
    get:
      operationId: consoleGetWorkspaceAgentUiInfo
      tags: [platform]
      summary: Get workspace Agent UI capability metadata
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Workspace Agent UI metadata
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/threads:
    get:
      operationId: consoleListWorkspaceAgentUiThreads
      tags: [platform]
      summary: List Agent UI threads for a workspace
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Agent UI thread list
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }
    post:
      operationId: consoleCreateWorkspaceAgentUiThread
      tags: [platform]
      summary: Create an Agent UI thread for a workspace
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Created Agent UI thread
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/threads/{thread_id}:
    get:
      operationId: consoleGetWorkspaceAgentUiThread
      tags: [platform]
      summary: Get an Agent UI thread
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: thread_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Agent UI thread
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/threads/{thread_id}/messages:
    post:
      operationId: consolePostWorkspaceAgentUiThreadMessage
      tags: [platform]
      summary: Append a message to an Agent UI thread
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: thread_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Agent UI message response
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/runs/{run_id}/stream:
    get:
      operationId: consoleStreamWorkspaceAgentUiRun
      tags: [platform]
      summary: Stream an Agent UI run
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: run_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Agent UI run stream
          content:
            text/event-stream:
              schema: { type: string }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/runs/{run_id}/cancel:
    post:
      operationId: consoleCancelWorkspaceAgentUiRun
      tags: [platform]
      summary: Cancel an Agent UI run
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: run_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Agent UI run cancellation result
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/tool-calls/preview:
    post:
      operationId: consolePreviewWorkspaceAgentUiToolCall
      tags: [platform]
      summary: Preview an Agent UI tool call
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Agent UI tool-call preview
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/tool-calls/{call_id}/confirm:
    post:
      operationId: consoleConfirmWorkspaceAgentUiToolCall
      tags: [platform]
      summary: Confirm an Agent UI tool call
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: call_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Agent UI tool-call confirmation result
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/tool-calls/{call_id}/cancel:
    post:
      operationId: consoleCancelWorkspaceAgentUiToolCall
      tags: [platform]
      summary: Cancel an Agent UI tool call
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: call_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Agent UI tool-call cancellation result
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/context/build:
    post:
      operationId: consoleBuildWorkspaceAgentUiContext
      tags: [platform]
      summary: Build Agent UI context for a workspace
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Agent UI context build result
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/agent-ui/approval-ceremonies/{approval_id}/execute:
    post:
      operationId: consoleExecuteWorkspaceAgentUiApprovalCeremony
      tags: [approval]
      summary: Execute an Agent UI approval ceremony
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: approval_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Approval ceremony execution result
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  # ── Workstation Governance ──────────────────────────
  /api/v1/workspaces/{id}/workstation/receipts/import:
    post:
      operationId: consoleImportWorkstationReceipt
      tags: [workstation]
      summary: Import a workstation Agent Run Receipt or selected-effect decision receipt
      description: |
        Imports parsed workstation governance evidence into the Console read model.
        The endpoint stores receipt summaries and selected proof fields; transcript-like
        fields are stripped before detail records are returned.
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/WorkstationAgentRunReceipt'
                - $ref: '#/components/schemas/WorkstationDecisionReceipt'
                - $ref: '#/components/schemas/WorkstationImportEnvelope'
      responses:
        '201':
          description: Workstation receipt imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkstationImportResponse'
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/workstation/runs:
    get:
      operationId: consoleListWorkstationRuns
      tags: [workstation]
      summary: List imported workstation runs
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Imported workstation run summaries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkstationRunsResponse'
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/workstation/runs/{run_id}:
    get:
      operationId: consoleGetWorkstationRun
      tags: [workstation]
      summary: Get workstation run detail
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: run_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Workstation run detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkstationRunDetail'
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/workstation/denied:
    get:
      operationId: consoleListWorkstationDeniedTimeline
      tags: [workstation]
      summary: List denied workstation effects
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Denied workstation effects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkstationDeniedResponse'
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/workstation/memory:
    get:
      operationId: consoleListWorkstationMemoryReview
      tags: [workstation]
      summary: List workstation memory writes awaiting review
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Workstation memory review queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkstationMemoryResponse'
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/workstation/loops:
    get:
      operationId: consoleListWorkstationRecurringLoops
      tags: [workstation]
      summary: List workstation recurring loop registrations
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Workstation recurring loop registry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkstationLoopsResponse'
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  # ── FinanceOps ──────────────────────────────────────
  /api/v1/workspaces/{id}/financeops/payment-authority:
    get:
      operationId: consoleGetWorkspaceFinanceOpsPaymentAuthority
      tags: [company]
      summary: Get workspace FinanceOps payment-authority records
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      responses:
        '200':
          description: Payment-authority records
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }
    post:
      operationId: consoleCreateWorkspaceFinanceOpsPaymentAuthority
      tags: [company]
      summary: Create a workspace FinanceOps payment-authority record
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Created payment-authority record
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

  /api/v1/workspaces/{id}/financeops/payment-authority/{pid}/evaluate:
    post:
      operationId: consoleEvaluateWorkspaceFinanceOpsPaymentAuthority
      tags: [company]
      summary: Evaluate a FinanceOps payment-authority proposal
      parameters:
        - $ref: '#/components/parameters/WorkspaceID'
        - name: pid
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Payment-authority evaluation result
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/HelmError' }
        '401': { $ref: '#/components/responses/HelmError' }
        '403': { $ref: '#/components/responses/HelmError' }
        '404': { $ref: '#/components/responses/HelmError' }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or JWT
  parameters:
    WorkspaceID:
      name: id
      in: path
      required: true
      schema: { type: string, format: uuid }
  # ── 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
                - INFRA_DESTROY_BLOCKED
                - ENV_RECREATE_BLOCKED
                - PROTECTED_INFRA_VIOLATION
                - CI_CREDENTIAL_BLOCKED
                - SOFTWARE_PUBLISH_BLOCKED
                - AGENT_INVOKE_ESCALATION
                - DATA_EGRESS_BLOCKED
                - TUNNEL_START_BLOCKED
                - BUDGET_HARD_LIMIT
                - CONTEXT_MISMATCH
                - IDENTITY_ISOLATION_VIOLATION
                - ERROR_INTERNAL
            details:
              type: object
              description: Additional error context
              additionalProperties: true

    LaunchpadApp:
      type: object
      required: [id, name, availability, license, redistribution, risk_class]
      properties:
        id: { type: string }
        name: { type: string }
        version: { type: string }
        availability:
          type: string
          enum: [oss_supported, oss_candidate, external_proprietary_adapter, blocked_license, blocked_policy, blocked_runtime, blocked_e2e]
        license: { type: string }
        redistribution: { type: string }
        risk_class: { type: string }
        required_secret_refs:
          type: array
          items: { type: string }
        evidence_refs:
          type: array
          items: { type: string }
        blockers:
          type: array
          items: { type: string }

    LaunchpadSubstrate:
      type: object
      required: [id, name, kind, default, dry_run_by_default, policy_ref]
      properties:
        id: { type: string }
        name: { type: string }
        kind: { type: string }
        default: { type: boolean }
        dry_run_by_default: { type: boolean }
        policy_ref: { type: string }
        blockers:
          type: array
          items: { type: string }

    LaunchpadMatrixCell:
      type: object
      required: [app_id, substrate_id, status]
      properties:
        app_id: { type: string }
        substrate_id: { type: string }
        status:
          type: string
          enum: [AVAILABLE, EXPERIMENTAL, EXTERNAL_ADAPTER, BLOCKED_LICENSE, BLOCKED_POLICY, BLOCKED_RUNTIME, BLOCKED_E2E]
        reason: { type: string }
        blockers:
          type: array
          items: { type: string }

    LaunchpadPlanRequest:
      type: object
      required: [app_id]
      properties:
        app_id: { type: string }
        substrate_id: { type: string, default: local-container }
        principal: { type: string }

    LaunchpadLaunchRequest:
      type: object
      required: [app_id]
      properties:
        app_id: { type: string }
        substrate_id: { type: string, default: local-container }
        principal: { type: string }
        approval_ref: { type: string }
        dry_run: { type: boolean }

    LaunchpadDeleteRequest:
      type: object
      properties:
        cascade: { type: boolean }
        teardown_receipt_ref: { type: string }
        approval_ref: { type: string }

    LaunchRepairPlan:
      type: object
      required: [launch_id, state, verdict, reasons, required_refs]
      properties:
        launch_id: { type: string }
        state:
          type: string
          enum: [PLANNED, VALIDATED, ESCALATED, DENIED, PROVISIONING, INSTALLING, STARTING, HEALTHCHECKING, RUNNING, REPAIR_REQUIRED, REPAIRING, TEARING_DOWN, DELETED, FAILED]
        verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        reasons:
          type: array
          items: { type: string }
        required_refs:
          type: array
          items: { type: string }

    LaunchRun:
      type: object
      required: [id, workspace_id, launch_id, app_id, substrate_id, principal, plan_hash, policy_hash, state, verdict]
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        launch_id: { type: string }
        app_id: { type: string }
        app_version: { type: string }
        substrate_id: { type: string }
        principal: { type: string }
        plan_hash: { type: string }
        policy_hash: { type: string }
        state:
          type: string
          enum: [PLANNED, VALIDATED, ESCALATED, DENIED, PROVISIONING, INSTALLING, STARTING, HEALTHCHECKING, RUNNING, REPAIR_REQUIRED, REPAIRING, TEARING_DOWN, DELETED, FAILED]
        verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        reason_code: { type: string }
        boundary_record_refs:
          type: array
          items: { type: string }
        cpi_refs:
          type: array
          items: { type: string }
        sandbox_grant_refs:
          type: array
          items: { type: string }
        mcp_refs:
          type: array
          items: { type: string }
        receipt_refs:
          type: array
          items: { type: string }
        evidence_pack_refs:
          type: array
          items: { type: string }
        generated_spec_ref: { type: string }
        action_proposal_ref: { type: string }
        company_artifact_graph_refs:
          type: array
          items: { type: string }
        runtime_handles: { type: object, additionalProperties: true }
        idempotency_keys: { type: object, additionalProperties: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        terminal_at: { type: string, format: date-time }

    LaunchpadPlanResponse:
      type: object
      required: [plan, run, status]
      properties:
        plan: { type: object, additionalProperties: true }
        run:
          $ref: '#/components/schemas/LaunchRun'
        status: { type: string }

    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

    Receipt:
      type: object
      properties:
        receipt_id: { type: string }
        decision_id: { type: string }
        effect_id: { type: string }
        status:
          type: string
          enum: [APPROVED, DENIED, PENDING]
        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 }

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

    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] }
        errors:
          type: array
          items: { 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 }

    OrgGenesisStartRequest:
      type: object
      required: [org_id, genome_draft_hash]
      properties:
        org_id: { type: string }
        genome_draft_hash: { type: string }

    OrgGenesisAdvanceRequest:
      type: object
      required: [receipt_hash, signer_id]
      properties:
        receipt_hash: { type: string }
        signer_id: { type: string }

    OrgGenesisPhaseState:
      type: object
      properties:
        phase: { type: string }
        status: { type: string }
        started_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        receipt_hash: { type: string }
        signer_id: { type: string }

    OrgGenesisCeremony:
      type: object
      properties:
        id: { type: string }
        org_id: { type: string }
        status: { type: string }
        current_phase: { type: string }
        phases:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OrgGenesisPhaseState'
        genome_draft_hash: { type: string }
        created_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        compile_receipt_hash: { type: string }
        mirror_text_hash: { type: string }
        impact_report_hash: { type: string }
        p0_ceilings_hash: { type: string }
        genesis_receipt_hash: { type: string }

    OrgStatus:
      type: object
      additionalProperties: true
      properties:
        status: { type: string }
        org_id: { type: string }
        org_name: { type: string }
        component: { type: string }
        thesis: { type: string }
        updated_at: { type: string, format: date-time }
        current_refs:
          type: object
          additionalProperties: true
        genesis:
          type: object
          additionalProperties: true
        compiler:
          type: object
          additionalProperties: true
        governance:
          type: object
          additionalProperties: true
        conformance:
          type: object
          additionalProperties: true
        runtime:
          type: object
          additionalProperties: true
        proof:
          type: object
          additionalProperties: true

    OrgTimelineItem:
      type: object
      additionalProperties: true
      properties:
        event_id: { type: string }
        type: { type: string }
        occurred_at: { type: string, format: date-time }
        run_id: { type: string }
        agent_id: { type: string }
        principal_id: { type: string }
        verdict: { type: string }
        evidence_pack_url: { type: string }
        report_url: { type: string }
        receipt_count: { type: integer }
        latest_receipt:
          type: object
          additionalProperties: true

    OrgTimelineResponse:
      type: object
      properties:
        org_id: { type: string }
        total_count: { type: integer }
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrgTimelineItem'

    OrgRuntimeSyncRequest:
      type: object
      required: [org_id, event_type]
      properties:
        org_id: { type: string }
        event_type:
          type: string
          enum: [heartbeat, run_completed]
        occurred_at: { type: string, format: date-time }
        run:
          type: object
          additionalProperties: true
        heartbeat:
          type: object
          additionalProperties: true

    Entitlement:
      type: object
      properties:
        capability: { type: string }
        limit: { type: integer }
        current_usage: { type: integer }
        source: { type: string }
        expires_at: { type: string, format: date-time }

    PlatformSession:
      type: object
      properties:
        session_id: { type: string }
        principal_id: { type: string }
        tenant_id: { type: string }
        workspace_id: { type: string }
        edition: { type: string }
        deployment_mode: { type: string }
        account_lifecycle: { type: string }
        offer_code: { type: string }
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/Entitlement'
        created_at: { type: string, format: date-time }
        last_seen_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        device_fingerprint: { type: string }
        signer_id: { type: string }

    WorkspaceSummary:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        slug: { type: string }
        edition: { type: string }
        offer_code: { type: string }

    WorkspaceListResponse:
      type: object
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceSummary'

    CreateWorkspaceRequest:
      type: object
      required: [name]
      properties:
        name: { type: string }
        slug: { type: string }
        edition: { type: string }
        offer_code: { type: string }
        plan: { type: string }

    ProvisionWorkspaceRequest:
      type: object
      required: [tenant_id]
      properties:
        tenant_id: { type: string }
        workspace_name: { type: string }
        edition: { type: string }
        offer_code: { type: string }
        plan: { type: string }

    BootstrapEnvelope:
      type: object
      properties:
        session:
          $ref: '#/components/schemas/PlatformSession'
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceSummary'
        snapshot:
          type: object
          additionalProperties: true

    BootstrapStatus:
      type: object
      properties:
        tenant_id: { type: string }
        workspace_id: { type: string }
        project_id: { type: string }
        environment_id: { type: string }
        edition: { type: string }
        offer_code: { type: string }
        account_lifecycle: { type: string }
        status: { type: string }
        failure_reason: { type: string }
        created_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        trial_expires_at: { type: string, format: date-time }
        trial_expired: { type: boolean }

    PackSummary:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        version: { type: string }
        author: { type: string }
        category: { type: string }
        channel: { type: string }
        description: { type: string }
        verified: { type: boolean }
        installed: { type: boolean }
        downloads: { type: integer }
        signatureValid: { type: boolean }
        updatedAt: { type: string }
        manifest_hash: { type: string }
        minimum_edition: { type: string }
        status: { type: string }
        installed_at: { type: string }
        receipt_id: { type: string }

    PacksResponse:
      type: object
      properties:
        packs:
          type: array
          items:
            $ref: '#/components/schemas/PackSummary'

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

    # ── New schemas (Phase G4) ───────────────────────────

    Incident:
      type: object
      properties:
        id: { type: string }
        tenant_id: { type: string }
        title: { type: string }
        description: { type: string }
        severity: { type: string, enum: [P0, P1, P2, P3] }
        state: { type: string, enum: [DETECTED, ACKNOWLEDGED, INVESTIGATING, MITIGATING, RESOLVED, POSTMORTEM] }
        is_drill: { type: boolean }
        detected_at: { type: string, format: date-time }
        acked_at: { type: string, format: date-time }
        resolved_at: { type: string, format: date-time }
        timeline:
          type: array
          items:
            type: object
            properties:
              timestamp: { type: string, format: date-time }
              action: { type: string }
              actor: { type: string }
              from_state: { type: string }
              to_state: { type: string }
              note: { type: string }

    EffectPlan:
      type: object
      required: [effect_type, target]
      properties:
        effect_type: { type: string }
        target: { type: string }
        target_type: { type: string }
        cost_cents: { type: integer }
        impact: { type: string, enum: [read, modify, delete, create] }

    Plan:
      type: object
      properties:
        id: { type: string }
        tenant_id: { type: string }
        submitted_by: { type: string }
        submitted_at: { type: string, format: date-time }
        status: { type: string, enum: [DRAFT, ANALYZED, PENDING, APPROVED, REJECTED, COMMITTING, COMMITTED, FAILED] }
        approval_required: { type: boolean }
        approved_by: { type: string }
        rejected_by: { type: string }
        reject_reason: { type: string }
        blast_radius:
          $ref: '#/components/schemas/BlastRadiusReport'

    BlastRadiusReport:
      type: object
      properties:
        plan_id: { type: string }
        computed_at: { type: string, format: date-time }
        effect_count: { type: integer }
        max_risk_taxon: { type: string, enum: [E0, E1, E2, E3, E4] }
        risk_score: { type: number, minimum: 0, maximum: 100 }
        estimated_cost_cents: { type: integer }
        reversibility_profile: { type: string, enum: [reversible, compensatable, irreversible] }
        required_approval_level: { type: string, enum: [none, single_human, dual_control, quorum] }
        requires_full_evidence_pack: { type: boolean }
        requires_two_phase: { type: boolean }
        human_summary: { type: string }
        affected_resources:
          type: array
          items:
            type: object
            properties:
              resource_id: { type: string }
              resource_type: { type: string }
              effect_type: { type: string }
              impact: { type: string }

    BudgetSummary:
      type: object
      properties:
        tenant_id: { type: string }
        total_cents: { type: integer }
        record_count: { type: integer }

    CompanyArtifact:
      type: object
      required: [type, source, title]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        type: { type: string }
        source: { type: string }
        source_ref: { type: string }
        source_url: { type: string }
        hash: { type: string }
        permissions: { type: object, additionalProperties: true }
        permission_state: { type: string, enum: [unresolved, resolved, restricted, denied, revoked] }
        freshness: { type: string, enum: [unknown, fresh, stale] }
        provenance: { type: object, additionalProperties: true }
        receipt_refs:
          type: array
          items: { type: string }
        status: { type: string, enum: [draft, canonical, disputed, stale, archived] }
        title: { type: string }
        body: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CompanyArtifactTransitionRequest:
      type: object
      required: [evidence_refs]
      properties:
        actor_id: { type: string }
        evidence_refs:
          type: array
          items: { type: string }
        receipt_refs:
          type: array
          items: { type: string }
        reason: { type: string }

    CompanyArtifactEdge:
      type: object
      required: [from_artifact_id, to_artifact_id, edge_type]
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        from_artifact_id: { type: string, format: uuid }
        to_artifact_id: { type: string, format: uuid }
        edge_type:
          type: string
          enum: [supports, contradicts, implements, blocks, decided_by, owned_by, generated_from, executed_by, verified_by, reads_from, writes_to, assumes, invalidates, supersedes, requires_approval_from, blocked_by_policy, proven_by_receipt]
        created_at: { type: string, format: date-time }

    CompanyArtifactGraph:
      type: object
      properties:
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/CompanyArtifact'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/CompanyArtifactEdge'

    TruthConflict:
      type: object
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        claim_artifact_id: { type: string, format: uuid }
        reality_artifact_id: { type: string, format: uuid }
        claim_source: { type: string }
        reality_source: { type: string }
        claim: { type: string }
        reality: { type: string }
        severity: { type: string, enum: [info, warning, critical] }
        status: { type: string, enum: [open, triaged, resolved, ignored] }
        suggested_resolution: { type: string }
        generated_spec_id: { type: string, format: uuid }
        created_at: { type: string, format: date-time }
        resolved_at: { type: string, format: date-time }

    CreateTruthConflictRequest:
      type: object
      properties:
        mode:
          type: string
          enum: [should_vs_is]
        create_generated_spec: { type: boolean }
        conflict:
          $ref: '#/components/schemas/TruthConflict'

    DriftSignal:
      type: object
      required: [drift_type, summary]
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        source_artifact_id: { type: string, format: uuid }
        drift_type: { type: string }
        severity: { type: string, enum: [info, warning, critical] }
        status: { type: string, enum: [open, triaged, resolved, ignored] }
        summary: { type: string }
        evidence_refs:
          type: array
          items: { type: string }
        created_at: { type: string, format: date-time }
        resolved_at: { type: string, format: date-time }

    GeneratedSpec:
      type: object
      required: [goal]
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        goal: { type: string }
        non_goals:
          type: array
          items: { type: string }
        source_evidence:
          type: array
          items: { type: string }
        customer_signal: { type: object, additionalProperties: true }
        linked_process: { type: string }
        affected_refs:
          type: array
          items: { type: string }
        acceptance_criteria:
          type: array
          items: { type: string }
        test_plan:
          type: array
          items: { type: string }
        risk_class: { type: string }
        required_approvals:
          type: array
          items: { type: string }
        policy_envelope: { type: object, additionalProperties: true }
        target_tools:
          type: array
          items: { type: string }
        work_payloads: { type: object, additionalProperties: true }
        execution_plan: { type: object, additionalProperties: true }
        receipt_requirements:
          type: array
          items: { type: string }
        read_set:
          type: array
          items: { type: string }
        write_set:
          type: array
          items: { type: string }
        assumption_set:
          type: array
          items: { type: string }
        version_dependencies:
          type: array
          items: { type: string }
        verification_scope: { type: object, additionalProperties: true }
        verification_scope_ref: { type: string }
        harness_trace_refs:
          type: array
          items: { type: string }
        plan_transaction_ref: { type: string }
        stale_dependency_refs:
          type: array
          items: { type: string }
        conflict_policy:
          type: string
          enum: [deny, escalate, last_writer_forbidden]
        rollback_policy: { type: object, additionalProperties: true }
        rollback_or_compensation_policy: { type: object, additionalProperties: true }
        human_review_state: { type: object, additionalProperties: true }
        evidence_confidence_ref: { type: string }
        receipt_refs:
          type: array
          items: { type: string }
        evidence_pack_refs:
          type: array
          items: { type: string }
        boundary_record_refs:
          type: array
          items: { type: string }
        source_evidence_refs:
          type: array
          items: { type: string }
        closure_evidence: { type: object, additionalProperties: true }
        execution_boundary_verdict: { type: string }
        actor_id: { type: string }
        approver_id: { type: string }
        policy_envelope_hash: { type: string }
        run_id: { type: string, format: uuid }
        action_proposal_ref: { type: string }
        status:
          type: string
          enum:
            - draft
            - reviewed
            - approved
            - execution_requested
            - boundary_submitted
            - executed
            - denied
            - escalated
            - failed
            - closure_evidence_attached
            - closed
        created_at: { type: string, format: date-time }
        reviewed_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time }
        execution_requested_at: { type: string, format: date-time }
        boundary_submitted_at: { type: string, format: date-time }
        terminal_at: { type: string, format: date-time }
        closure_evidence_attached_at: { type: string, format: date-time }
        closed_at: { type: string, format: date-time }

    GeneratedSpecTransitionRequest:
      type: object
      properties:
        actor_id: { type: string }
        approver_id: { type: string }
        policy_envelope_hash: { type: string }
        receipt_refs:
          type: array
          items: { type: string }
        evidence_pack_refs:
          type: array
          items: { type: string }
        source_evidence_refs:
          type: array
          items: { type: string }
        boundary_record_refs:
          type: array
          items: { type: string }
        execution_boundary_verdict: { type: string }
        closure_evidence: { type: object, additionalProperties: true }
        run_id: { type: string, format: uuid }
        action_proposal_ref: { type: string }
        verification_scope_ref: { type: string }
        harness_trace_refs:
          type: array
          items: { type: string }
        plan_transaction_ref: { type: string }
        evidence_confidence_ref: { type: string }

    GeneratedSpecExecutionResponse:
      type: object
      required: [generated_spec]
      properties:
        generated_spec:
          $ref: '#/components/schemas/GeneratedSpec'
        run:
          type: object
          additionalProperties: true

    VerificationScopeRecord:
      type: object
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        verification_scope_id: { type: string }
        subject_hash: { type: string }
        risk_class: { type: string, enum: [T0, T1, T2, T3] }
        checks_performed: { type: array, items: { type: string } }
        assumptions: { type: array, items: { type: string } }
        untested_regions: { type: array, items: { type: string } }
        known_limits: { type: array, items: { type: string } }
        remaining_risks: { type: array, items: { type: string } }
        required_followup: { type: array, items: { type: string } }
        verifier_hash: { type: string }
        policy_hash: { type: string }
        scope_hash: { type: string }
        payload: { type: object, additionalProperties: true }
        created_at: { type: string, format: date-time }

    HarnessTraceRecord:
      type: object
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        trace_id: { type: string }
        plan_hash: { type: string }
        context_refs: { type: array, items: { type: string } }
        memory_reads: { type: array, items: { type: string } }
        memory_writes: { type: array, items: { type: string } }
        tool_schema_hashes: { type: array, items: { type: string } }
        permission_requests: { type: array, items: { type: string } }
        sandbox_grant_hash: { type: string }
        mcp_approval_ref: { type: string }
        connector_contract_hash: { type: string }
        policy_hash: { type: string }
        cpi_output_hash: { type: string }
        verifier_outputs: { type: array, items: { type: string } }
        human_interventions: { type: array, items: { type: string } }
        state_updates: { type: array, items: { type: string } }
        receipt_refs: { type: array, items: { type: string } }
        trace_hash: { type: string }
        payload: { type: object, additionalProperties: true }
        created_at: { type: string, format: date-time }

    PlanTransactionRecord:
      type: object
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        plan_transaction_id: { type: string }
        plan_hash: { type: string }
        read_set: { type: array, items: { type: string } }
        write_set: { type: array, items: { type: string } }
        assumption_set: { type: array, items: { type: string } }
        version_dependencies: { type: array, items: { type: string } }
        verification_obligations: { type: array, items: { type: string } }
        conflict_policy: { type: string, enum: [deny, escalate, last_writer_forbidden] }
        rollback_policy: { type: object, additionalProperties: true }
        approval_state: { type: string, enum: [none, required, approved, denied, expired] }
        transaction_hash: { type: string }
        payload: { type: object, additionalProperties: true }
        created_at: { type: string, format: date-time }

    HarnessChangeContractRecord:
      type: object
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        change_contract_id: { type: string }
        component_modified:
          type: string
          enum: [connector_contract, tool_schema, sandbox_grant, mcp_approval, policy_overlay, verifier, evidence_template, routing_rule]
        failure_mode_targeted: { type: string }
        predicted_improvement: { type: string }
        invariants_preserved: { type: array, items: { type: string } }
        safety_properties: { type: array, items: { type: string } }
        regression_suite_refs: { type: array, items: { type: string } }
        simulation_evidence_refs: { type: array, items: { type: string } }
        canary_scope: { type: object, additionalProperties: true }
        rollback_plan: { type: object, additionalProperties: true }
        approval_required: { type: boolean }
        approval_receipt_ref: { type: string }
        activation_receipt_ref: { type: string }
        status: { type: string, enum: [draft, approved, activated, rejected, revoked] }
        contract_hash: { type: string }
        payload: { type: object, additionalProperties: true }
        created_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time }
        activated_at: { type: string, format: date-time }

    EvidenceConfidenceRecord:
      type: object
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        subject_hash: { type: string }
        subject_ref: { type: string }
        proven: { type: array, items: { type: string } }
        checked: { type: array, items: { type: string } }
        assumed: { type: array, items: { type: string } }
        untested: { type: array, items: { type: string } }
        stale: { type: array, items: { type: string } }
        blocked: { type: array, items: { type: string } }
        remaining_risk: { type: array, items: { type: string } }
        confidence_score: { type: number }
        confidence_hash: { type: string }
        payload: { type: object, additionalProperties: true }
        created_at: { type: string, format: date-time }

    OrgGenomeCompilerRequest:
      type: object
      required: [request_id, target_schema, prompt]
      properties:
        request_id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        target_schema:
          type: string
          enum: [orggenome_ast, processgraph, connector_contract, jurisdiction_overlay, gap_report, snapshot_envelope, orggraph, semantic_mirror]
        prompt: { type: string }
        evidence_refs: { type: array, items: { type: string } }
        company_artifact_refs: { type: array, items: { type: string } }
        permission_scope: { type: object, additionalProperties: true }
        provenance: { type: object, additionalProperties: true }
        model_hints: { type: object, additionalProperties: true }
        adapter_hints: { type: object, additionalProperties: true }

    OrgGenomeDraftArtifact:
      type: object
      required: [artifact_id, schema_name, artifact, artifact_hash]
      properties:
        artifact_id: { type: string }
        schema_name:
          type: string
          enum: [orggenome_ast, processgraph, connector_contract, jurisdiction_overlay, gap_report, snapshot_envelope, orggraph, semantic_mirror]
        artifact: { type: object, additionalProperties: true }
        artifact_hash: { type: string }
        confidence_score: { type: number }

    OrgGenomeCompilerResult:
      type: object
      required: [request_id, status]
      properties:
        request_id: { type: string, format: uuid }
        status: { type: string, enum: [succeeded, failed, partial, invalid] }
        draft_artifacts:
          type: array
          items:
            $ref: '#/components/schemas/OrgGenomeDraftArtifact'
        validation_errors: { type: array, items: { type: string } }
        confidence_score: { type: number }
        eval_score: { type: number }
        evidence_hashes: { type: array, items: { type: string } }
        model_id: { type: string }
        adapter_id: { type: string }
        compiler_version: { type: string }
        schema_version: { type: string }
        result_hash: { type: string }

    OrgGenomeCompilerRun:
      type: object
      properties:
        id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        request:
          $ref: '#/components/schemas/OrgGenomeCompilerRequest'
        result:
          $ref: '#/components/schemas/OrgGenomeCompilerResult'
        status: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        imported_at: { type: string, format: date-time }

    OrgGenomeCompilerImportResult:
      type: object
      properties:
        run_id: { type: string, format: uuid }
        draft_artifacts:
          type: array
          items:
            $ref: '#/components/schemas/CompanyArtifact'
        drift_signals:
          type: array
          items:
            $ref: '#/components/schemas/DriftSignal'
        connector_candidates:
          type: array
          items:
            $ref: '#/components/schemas/CompanyArtifact'
        genesis_review_refs:
          type: array
          items:
            $ref: '#/components/schemas/CompanyArtifact'
        side_effects_authorized: { type: boolean }


    ReceiptRef:
      type: object
      properties:
        receipt_ref: { type: string }
        subject_hash: { type: string }
        policy_hash: { type: string }
        plan_hash: { type: string }
        action_urn: { type: string }
        verdict: { type: string, enum: [ALLOW, DENY, ESCALATE] }
        reason_code: { type: string }

    EvidenceRef:
      type: object
      properties:
        evidence_ref: { type: string }
        subject_hash: { type: string }
        evidence_pack_hash: { type: string }

    BoundaryRecordRef:
      type: object
      properties:
        boundary_record_ref: { type: string }
        run_id: { type: string, format: uuid }
        verdict: { type: string, enum: [ALLOW, DENY, ESCALATE] }

    ConnectorInventory:
      type: object
      required: [connector_id, version]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        connector_id: { type: string }
        version: { type: string }
        display_name: { type: string }
        health_state: { type: string }
        metadata: { type: object, additionalProperties: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    ConnectorContract:
      type: object
      required: [connector_id, version, schema_hash, executor_kind, effect_class, idempotency_strategy]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        connector_id: { type: string }
        version: { type: string }
        schema_artifacts: { type: object, additionalProperties: true }
        schema_hash: { type: string }
        allowed_endpoints:
          type: array
          items: { type: string }
        action_urns:
          type: array
          items: { type: string }
        executor_kind: { type: string, enum: [DIGITAL, KINETIC, ANALOG] }
        effect_class: { type: string, enum: [REVERSIBLE, COMPENSABLE, IRREVERSIBLE] }
        idempotency_strategy: { type: string }
        required_headers:
          type: array
          items: { type: string }
        retry_policy: { type: object, additionalProperties: true }
        compensation_capability: { type: string }
        irreversible_reason: { type: string }
        endpoint_fingerprint: { type: string }
        rate_limit_fingerprint: { type: string }
        drift_fixtures: { type: object, additionalProperties: true }
        health_state: { type: string }
        last_drift_check: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    ConnectorDriftCheckRequest:
      type: object
      required: [connector_id, version]
      properties:
        connector_id: { type: string }
        version: { type: string }
        schema_hash: { type: string }
        required_fields_present: { type: boolean }
        unrecognized_enum_values:
          type: array
          items: { type: string }
        endpoint_fingerprint: { type: string }
        rate_limit_fingerprint: { type: string }

    ConnectorDriftCheckResult:
      type: object
      required: [verdict, reason_code]
      properties:
        verdict: { type: string, enum: [ALLOW, DENY, ESCALATE] }
        reason_code: { type: string }
        drift_types:
          type: array
          items:
            type: string
            enum: [schema_hash_mismatch, required_field_missing, enum_extension_unrecognized, endpoint_fingerprint_change, rate_limit_behavior_change]

    ToolRegistryEntry:
      type: object
      required: [action_urn, input_schema_hash, output_schema_hash, risk_class, effect_class, executor_kind]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        action_urn: { type: string }
        input_schema_hash: { type: string }
        output_schema_hash: { type: string }
        risk_class: { type: string }
        effect_class: { type: string }
        executor_kind: { type: string, enum: [DIGITAL, KINETIC, ANALOG] }
        required_sandbox_profile: { type: string }
        allowed_principals:
          type: array
          items: { type: string }
        required_approvals: { type: array, items: { type: string } }
        connector_contract_hash: { type: string }
        health_state: { type: string }
        last_drift_check: { type: string, format: date-time }
        revocation_state: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    SandboxGrant:
      type: object
      required: [runtime, runtime_version, backend_profile]
      properties:
        grant_id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        runtime: { type: string }
        runtime_version: { type: string }
        backend_profile: { type: string }
        image_digest: { type: string }
        template_digest: { type: string }
        filesystem_preopens:
          type: array
          items: { type: string }
        env_vars: { type: object, additionalProperties: true }
        network_policy: { type: object, additionalProperties: true }
        resource_limits: { type: object, additionalProperties: true }
        policy_epoch: { type: integer, format: int64 }
        grant_hash: { type: string }
        status: { type: string }
        expires_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
        revoked_at: { type: string, format: date-time }

    MCPApprovalRecord:
      type: object
      required: [server_identity, endpoint, risk_class, approver_id, approval_receipt_id]
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        workspace_id: { type: string, format: uuid }
        server_identity: { type: string }
        endpoint: { type: string }
        discovered_tools:
          type: array
          items: { type: object, additionalProperties: true }
        schema_hashes: { type: object, additionalProperties: { type: string } }
        risk_class: { type: string }
        approver_id: { type: string }
        approval_receipt_id: { type: string }
        status: { type: string, enum: [approved, quarantined, revoked, expired] }
        expires_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
        revoked_at: { type: string, format: date-time }

    MCPEvaluationRequest:
      type: object
      required: [server_identity, endpoint]
      properties:
        server_identity: { type: string }
        endpoint: { type: string }
        tool_name: { type: string }

    MCPEvaluationResponse:
      type: object
      required: [verdict, reason_code]
      properties:
        verdict: { type: string, enum: [ALLOW, DENY, ESCALATE] }
        reason_code: { type: string }
        approval_id: { type: string, format: uuid }

    WorkstationRunSummary:
      type: object
      required:
        - run_id
        - tool_action_count
        - changed_file_count
        - validation_count
        - denied_count
        - memory_review_count
        - recurring_loop_count
        - created_at
        - updated_at
      properties:
        run_id: { type: string }
        receipt_id: { type: string }
        decision_ids:
          type: array
          items: { type: string }
        goal: { type: string }
        agent_surface: { type: string }
        policy_profile: { type: string }
        verdict: { type: string }
        receipt_hash: { type: string }
        tool_action_count: { type: integer }
        changed_file_count: { type: integer }
        validation_count: { type: integer }
        denied_count: { type: integer }
        memory_review_count: { type: integer }
        recurring_loop_count: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    WorkstationToolAction:
      type: object
      properties:
        action_id: { type: string }
        tool_id: { type: string }
        action: { type: string }
        effect_type: { type: string }
        effect_mode: { type: string }
        status: { type: string }
        verdict: { type: string }
        reason_code: { type: string }
        target: { type: string }
        occurred_at: { type: string, format: date-time }
        taint_labels:
          type: array
          items: { type: string }

    WorkstationChangedFile:
      type: object
      required: [path, status]
      properties:
        path: { type: string }
        status: { type: string }
        additions: { type: integer }
        deletions: { type: integer }

    WorkstationValidationResult:
      type: object
      required: [command, exit_code, status]
      properties:
        command: { type: string }
        exit_code: { type: integer }
        status: { type: string }
        stdout_hash: { type: string }
        stderr_hash: { type: string }
        started_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }

    WorkstationDeniedTimelineItem:
      type: object
      required: [run_id, effect_type, verdict, occurred_at]
      properties:
        run_id: { type: string }
        receipt_id: { type: string }
        decision_id: { type: string }
        effect_id: { type: string }
        effect_type: { type: string }
        tool_id: { type: string }
        action: { type: string }
        target: { type: string }
        verdict: { type: string }
        reason_code: { type: string }
        reason: { type: string }
        agent_surface: { type: string }
        policy_profile: { type: string }
        occurred_at: { type: string, format: date-time }

    WorkstationMemoryReviewItem:
      type: object
      required: [run_id, effect_id, observed_only, created_at]
      properties:
        run_id: { type: string }
        receipt_id: { type: string }
        effect_id: { type: string }
        memory_class: { type: string }
        data_class: { type: string }
        sensitivity: { type: string }
        ttl_days: { type: integer }
        content_hash: { type: string }
        content_ref: { type: string }
        purpose: { type: string }
        review_state: { type: string }
        verdict: { type: string }
        reason_code: { type: string }
        taint_labels:
          type: array
          items: { type: string }
        observed_only: { type: boolean }
        policy_profile: { type: string }
        created_at: { type: string, format: date-time }

    WorkstationRecurringLoopItem:
      type: object
      required: [run_id, effect_id, schedule, max_runtime, tool_scope, expires_at, observed_only]
      properties:
        run_id: { type: string }
        receipt_id: { type: string }
        effect_id: { type: string }
        schedule: { type: string }
        max_runtime: { type: string }
        tool_scope:
          type: array
          items: { type: string }
        expires_at: { type: string, format: date-time }
        verdict: { type: string }
        reason_code: { type: string }
        observed_only: { type: boolean }
        policy_profile: { type: string }

    WorkstationReceiptDetail:
      type: object
      additionalProperties: true
      properties:
        receipt_id: { type: string }
        decision_id: { type: string }
        run_id: { type: string }
        goal: { type: string }
        agent_surface: { type: string }
        policy_profile: { type: string }
        verdict: { type: string }
        reason_code: { type: string }
        receipt_hash: { type: string }
        tool_actions:
          type: array
          items: { $ref: '#/components/schemas/WorkstationToolAction' }
        changed_files:
          type: array
          items: { $ref: '#/components/schemas/WorkstationChangedFile' }
        validation_results:
          type: array
          items: { $ref: '#/components/schemas/WorkstationValidationResult' }
        proofgraph_refs:
          type: array
          items: { type: string }
        evidence_pack_refs:
          type: array
          items: { type: string }
        created_at: { type: string, format: date-time }

    WorkstationRunDetail:
      type: object
      required: [summary, denied_timeline, memory_review_queue, recurring_loop_registry]
      properties:
        summary:
          $ref: '#/components/schemas/WorkstationRunSummary'
        receipt_details:
          type: array
          items: { $ref: '#/components/schemas/WorkstationReceiptDetail' }
        denied_timeline:
          type: array
          items: { $ref: '#/components/schemas/WorkstationDeniedTimelineItem' }
        memory_review_queue:
          type: array
          items: { $ref: '#/components/schemas/WorkstationMemoryReviewItem' }
        recurring_loop_registry:
          type: array
          items: { $ref: '#/components/schemas/WorkstationRecurringLoopItem' }

    WorkstationOperatorCounts:
      type: object
      required: [runs, denied_timeline, memory_review_queue, recurring_loop_registry]
      properties:
        runs: { type: integer }
        denied_timeline: { type: integer }
        memory_review_queue: { type: integer }
        recurring_loop_registry: { type: integer }

    WorkstationOperatorView:
      type: object
      required: [runs, denied_timeline, memory_review_queue, recurring_loop_registry, counts]
      properties:
        runs:
          type: array
          items: { $ref: '#/components/schemas/WorkstationRunSummary' }
        denied_timeline:
          type: array
          items: { $ref: '#/components/schemas/WorkstationDeniedTimelineItem' }
        memory_review_queue:
          type: array
          items: { $ref: '#/components/schemas/WorkstationMemoryReviewItem' }
        recurring_loop_registry:
          type: array
          items: { $ref: '#/components/schemas/WorkstationRecurringLoopItem' }
        counts:
          $ref: '#/components/schemas/WorkstationOperatorCounts'

    WorkstationRunsResponse:
      type: object
      required: [runs, count]
      properties:
        runs:
          type: array
          items: { $ref: '#/components/schemas/WorkstationRunSummary' }
        count: { type: integer }

    WorkstationDeniedResponse:
      type: object
      required: [denied_timeline, count]
      properties:
        denied_timeline:
          type: array
          items: { $ref: '#/components/schemas/WorkstationDeniedTimelineItem' }
        count: { type: integer }

    WorkstationMemoryResponse:
      type: object
      required: [memory_review_queue, count]
      properties:
        memory_review_queue:
          type: array
          items: { $ref: '#/components/schemas/WorkstationMemoryReviewItem' }
        count: { type: integer }

    WorkstationLoopsResponse:
      type: object
      required: [recurring_loop_registry, count]
      properties:
        recurring_loop_registry:
          type: array
          items: { $ref: '#/components/schemas/WorkstationRecurringLoopItem' }
        count: { type: integer }

    WorkstationImportResponse:
      type: object
      required: [kind, view]
      properties:
        kind: { type: string }
        run:
          $ref: '#/components/schemas/WorkstationRunSummary'
        decision_id: { type: string }
        receipt_id: { type: string }
        view:
          $ref: '#/components/schemas/WorkstationOperatorView'

    WorkstationAgentRunReceipt:
      type: object
      additionalProperties: true
      required: [run_id]
      properties:
        receipt_id: { type: string }
        run_id: { type: string }
        goal: { type: string }
        agent_surface: { type: string }
        policy_profile: { type: string }
        receipt_hash: { type: string }
        tool_actions:
          type: array
          items: { $ref: '#/components/schemas/WorkstationToolAction' }
        changed_files:
          type: array
          items: { $ref: '#/components/schemas/WorkstationChangedFile' }
        validation_results:
          type: array
          items: { $ref: '#/components/schemas/WorkstationValidationResult' }
        memory_effects:
          type: array
          items: { $ref: '#/components/schemas/WorkstationMemoryReviewItem' }
        recurring_loop_effects:
          type: array
          items: { $ref: '#/components/schemas/WorkstationRecurringLoopItem' }
        denied_effects:
          type: array
          items: { $ref: '#/components/schemas/WorkstationDeniedTimelineItem' }
        created_at: { type: string, format: date-time }

    WorkstationDecisionReceipt:
      type: object
      additionalProperties: true
      required: [decision_id, request, policy_profile, verdict, reason_code]
      properties:
        decision_id: { type: string }
        request:
          type: object
          additionalProperties: true
          properties:
            run_id: { type: string }
            agent_surface: { type: string }
            tool_id: { type: string }
            action: { type: string }
            effect_type: { type: string }
            target: { type: string }
            occurred_at: { type: string, format: date-time }
        policy_profile: { type: string }
        verdict: { type: string }
        reason_code: { type: string }
        reason: { type: string }
        created_at: { type: string, format: date-time }
        receipt_hash: { type: string }

    WorkstationImportEnvelope:
      type: object
      additionalProperties: true
      required: [receipt]
      properties:
        receipt:
          $ref: '#/components/schemas/WorkstationAgentRunReceipt'

    FailureMode:
      type: string
      enum:
        - PROMPT_INJECTION_TOOL_HIJACK
        - UNAUTHORIZED_TOOL_EXECUTION
        - MCP_SERVER_EXPOSURE
        - DATA_EGRESS_ATTEMPT
        - SECRET_OR_CREDENTIAL_EXPOSURE
        - AGENT_IDENTITY_BYPASS
        - APPROVAL_BYPASS
        - CONNECTOR_CONTRACT_DRIFT
        - MODEL_SUBSTITUTION
        - SUPPLY_CHAIN_AGENT_COMPROMISE
        - RUNAWAY_LOOP_OR_RESOURCE_ABUSE
        - UNAUTHORIZED_INFRASTRUCTURE_MUTATION
        - UNAUTHORIZED_FINANCIAL_ACTION
        - REGULATED_COMMUNICATION_WITHOUT_APPROVAL
        - ANALOG_PROXY_ABUSE
        - KINETIC_EXECUTOR_RISK
        - PUBLIC_PROOF_LEAK_RISK

    SourceRegistry:
      type: object
      required: [source_id, source_type, authority_level, fetch_mode, base_url_hash, update_cadence, robots_policy, confidence_weight, stores_raw_html, redaction_required, live_polling_enabled]
      properties:
        source_id: { type: string }
        source_type: { type: string }
        authority_level: { type: string }
        fetch_mode: { type: string }
        base_url: { type: string }
        base_url_hash: { type: string }
        update_cadence: { type: string }
        robots_policy: { type: string }
        confidence_weight: { type: number }
        stores_raw_html: { type: boolean }
        redaction_required: { type: boolean }
        live_polling_enabled: { type: boolean }
        rate_limit: { type: string }
        timeout: { type: string }
        retry_policy: { type: string }

    SourceSnapshot:
      type: object
      required: [id, source_id, source_url, source_url_hash, claim_hash, snapshot_hash, retrieved_at, stores_raw, redacted]
      properties:
        id: { type: string }
        source_id: { type: string }
        source_url: { type: string, format: uri }
        source_url_hash: { type: string }
        claim_hash: { type: string }
        snapshot_hash: { type: string }
        artifact_ref: { type: string }
        retrieved_at: { type: string, format: date-time }
        stores_raw: { type: boolean }
        redacted: { type: boolean }

    SourceAssertion:
      type: object
      required: [id, source, source_url, title, claim, retrieved_at, confidence, content_hash]
      properties:
        id: { type: string }
        candidate_id: { type: string }
        source: { type: string }
        source_id: { type: string }
        source_url: { type: string, format: uri }
        source_url_hash: { type: string }
        publisher: { type: string }
        title: { type: string }
        claim: { type: string }
        claim_hash: { type: string }
        raw_snapshot_ref: { type: string }
        source_type: { type: string }
        published_at: { type: string, format: date-time }
        retrieved_at: { type: string, format: date-time }
        confidence:
          type: string
          enum: [high, medium, low]
        content_hash: { type: string }

    ExternalIncidentCandidate:
      type: object
      required: [id, dedupe_key, title, public_summary, status, source_confidence, discovered_at, failure_modes, source_assertions]
      properties:
        id: { type: string }
        dedupe_key: { type: string }
        dedupe_keys:
          type: object
          additionalProperties: { type: string }
        title: { type: string }
        public_summary: { type: string }
        status:
          type: string
          enum: [confirmed, probable, emerging, watchlist, rejected_not_helm_boundary]
        source_confidence:
          type: string
          enum: [high, medium, low]
        confidence:
          type: object
          properties:
            source_count: { type: integer }
            source_quality:
              type: string
              enum: [high, medium, low]
            status:
              type: string
              enum: [confirmed, probable, emerging, watchlist, rejected_not_helm_boundary]
            score: { type: number }
        risk_level:
          type: string
          enum: [low, medium, high, blocked]
        incident_date: { type: string, format: date-time }
        discovered_at: { type: string, format: date-time }
        failure_modes:
          type: array
          items: { $ref: '#/components/schemas/FailureMode' }
        source_assertions:
          type: array
          items: { $ref: '#/components/schemas/SourceAssertion' }
        merge_refs:
          type: array
          items: { type: string }

    FailureIntelligenceRunRequest:
      type: object
      properties:
        seed_only: { type: boolean, default: true }
        source_ids:
          type: array
          items: { type: string }
        limit: { type: integer, minimum: 1 }
        source: { type: string }
        dry_run: { type: boolean }
        shadow_mode: { type: boolean }
        publish_policy:
          type: string
          enum: [manual_only, shadow_only, auto_low_risk]

    FailureIntelligenceRunResult:
      type: object
      required: [run_id, started_at, completed_at, candidates_imported, replays_generated, network_polling]
      properties:
        run_id: { type: string }
        mode:
          type: string
          enum: [seed, live, shadow]
        source_set:
          type: array
          items: { type: string }
        status:
          type: string
          enum: [running, completed, failed]
        started_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }
        stage_counts:
          type: object
          additionalProperties: { type: integer }
        error_summary: { type: string }
        gate_failures:
          type: array
          items: { type: string }
        dry_run: { type: boolean }
        shadow_mode: { type: boolean }
        auto_publish_enabled: { type: boolean }
        candidates_imported: { type: integer }
        replays_generated: { type: integer }
        candidates_merged: { type: integer }
        verification_passed: { type: integer }
        vectors_exported: { type: integer }
        archive_artifacts_exported: { type: integer }
        source_registries_registered: { type: integer }
        source_snapshots_captured: { type: integer }
        generated_specs_drafted: { type: integer }
        network_polling: { type: boolean }

    FailureIntelligenceSourceHealth:
      type: object
      required: [source_id, source_type, authority_level, live_polling_enabled, candidate_count, dedupe_count]
      properties:
        source_id: { type: string }
        source_type: { type: string }
        authority_level: { type: string }
        live_polling_enabled: { type: boolean }
        last_successful_poll: { type: string, format: date-time }
        last_error: { type: string }
        candidate_count: { type: integer }
        dedupe_count: { type: integer }
        confidence_distribution:
          type: object
          additionalProperties: { type: integer }

    FailureIntelligenceArtifactRef:
      type: object
      required: [id, artifact_ref, artifact_kind, sha256, size_bytes, content_type, retention_class, public_safe, created_at]
      properties:
        id: { type: string }
        artifact_ref: { type: string }
        artifact_kind: { type: string }
        hpr_id: { type: string }
        source_id: { type: string }
        sha256: { type: string }
        size_bytes: { type: integer, format: int64 }
        content_type: { type: string }
        retention_class: { type: string }
        public_safe: { type: boolean }
        created_at: { type: string, format: date-time }

    FailureIntelligenceExportBatch:
      type: object
      required: [id, kind, status, artifact_refs, artifact_hash, created_at]
      properties:
        id: { type: string }
        kind: { type: string }
        status: { type: string }
        artifact_refs:
          type: array
          items: { $ref: '#/components/schemas/FailureIntelligenceArtifactRef' }
        artifact_hash: { type: string }
        created_at: { type: string, format: date-time }
        error_summary: { type: string }

    FailureIntelligenceVerificationResult:
      type: object
      required: [id, replay_id, hpr_id, status, verifier_command, evidencepack_hash, verified_at, offline_verified, conformance_passed, exit_code]
      properties:
        id: { type: string }
        replay_id: { type: string }
        hpr_id: { type: string }
        status:
          type: string
          enum: [pending, passed, failed]
        verifier_command: { type: string }
        evidencepack_hash: { type: string }
        verified_at: { type: string, format: date-time }
        failure_reason: { type: string }
        offline_verified: { type: boolean }
        conformance_passed: { type: boolean }
        exit_code: { type: integer }
        stdout_hash: { type: string }
        stderr_hash: { type: string }
        report:
          type: object
          additionalProperties: true

    KernelValidationManifest:
      type: object
      required: [id, hpr_id, hcv_ids, expected_verdicts, evidencepack_hash, conformance_result_hash, kernel_commit, issued_at, signer, signature]
      properties:
        id: { type: string }
        hpr_id: { type: string }
        hcv_ids:
          type: array
          items: { type: string }
        expected_verdicts:
          type: array
          items:
            type: string
            enum: [ALLOW, DENY, ESCALATE]
        evidencepack_hash: { type: string }
        conformance_result_hash: { type: string }
        kernel_commit: { type: string }
        issued_at: { type: string, format: date-time }
        signer: { type: string }
        signature: { type: string }

    GitHubMergeEvidence:
      type: object
      required: [repository, pull_request_url, merge_commit, checks_passed, merged_at]
      properties:
        repository: { type: string }
        pull_request_url: { type: string }
        merge_commit: { type: string }
        checks_passed: { type: boolean }
        merged_at: { type: string, format: date-time }

    KernelValidationImportRequest:
      type: object
      required: [manifest, github_merge_evidence]
      properties:
        manifest:
          $ref: '#/components/schemas/KernelValidationManifest'
        github_merge_evidence:
          $ref: '#/components/schemas/GitHubMergeEvidence'

    ConformanceVector:
      type: object
      required: [id, candidate_id, hpr_id, failure_mode, title, template, expected_verdict, expected_reason_code, must_emit_receipt, must_not_dispatch, must_bind_evidence]
      properties:
        id: { type: string }
        vector_id: { type: string }
        candidate_id: { type: string }
        hpr_id: { type: string }
        failure_mode: { $ref: '#/components/schemas/FailureMode' }
        failure_modes:
          type: array
          items: { $ref: '#/components/schemas/FailureMode' }
        title: { type: string }
        template: { type: string }
        level:
          type: string
          enum: [L1, L2, L3, L4]
        policy_profile: { type: string }
        input:
          type: object
          properties:
            plan_ir: { type: string }
            policy: { type: string }
            fixtures:
              type: array
              items: { type: string }
        expected:
          type: object
          properties:
            verdict:
              type: string
              enum: [ALLOW, DENY, ESCALATE]
            reason_code: { type: string }
            receipt_required: { type: boolean }
            evidencepack_required: { type: boolean }
        negative_assertions:
          type: array
          items: { 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: boolean }
        generated_at: { type: string, format: date-time }

    CounterfactualReplay:
      type: object
      additionalProperties: true
      required: [id, hpr_id, candidate_id, title, counterfactual_verdict, reason_codes, replay_policy_hash, synthetic_plan_hash, receipt_hash, evidencepack_hash, generated_vectors, counterfactual_claim]
      properties:
        id: { type: string }
        hpr_id: { type: string }
        candidate_id: { type: string }
        title: { type: string }
        risk_level:
          type: string
          enum: [low, medium, high, blocked]
        missing_authority:
          type: array
          items: { type: string }
        counterfactual_verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        reason_codes:
          type: array
          items: { type: string }
        replay_policy_hash: { type: string }
        synthetic_plan_hash: { type: string }
        receipt_hash: { type: string }
        evidencepack_hash: { type: string }
        evidencepack_ref: { type: string }
        verification_command: { type: string }
        verification_status:
          type: string
          enum: [pending, passed, failed]
        verification_result:
          $ref: '#/components/schemas/FailureIntelligenceVerificationResult'
        vector_status:
          type: string
          enum: [draft, exported, approved_export_pending_merge, validated_in_kernel, rejected]
        lifecycle_state:
          type: string
          enum: [draft_replay, verified, vector_exported, kernel_validated, review_approved, published, rejected, legal_review_required, revoked]
        kernel_validation:
          $ref: '#/components/schemas/KernelValidationManifest'
        github_merge_evidence:
          $ref: '#/components/schemas/GitHubMergeEvidence'
        published_artifact_hash: { type: string }
        revoked_at: { type: string, format: date-time }
        gate_failures:
          type: array
          items: { type: string }
        shadow_mode: { type: boolean }
        auto_publish_eligible: { type: boolean }
        proofgraph_root: { type: string }
        artifact_refs:
          type: array
          items: { $ref: '#/components/schemas/FailureIntelligenceArtifactRef' }
        public_safe: { type: boolean }
        redaction_passed: { type: boolean }
        review_approved: { type: boolean }
        generated_vectors:
          type: array
          items: { $ref: '#/components/schemas/ConformanceVector' }
        source_registries:
          type: array
          items: { $ref: '#/components/schemas/SourceRegistry' }
        source_snapshots:
          type: array
          items: { $ref: '#/components/schemas/SourceSnapshot' }
        safety_constraints:
          type: object
          properties:
            live_network: { type: boolean }
            live_connectors: { type: boolean }
            raw_exploit_reproduction: { type: boolean }
            uses_customer_data: { type: boolean }
        generated_spec:
          $ref: '#/components/schemas/FailureIntelligenceGeneratedSpec'
        counterfactual_claim: { type: string }

    FailureIntelligenceGeneratedSpec:
      type: object
      required: [generated_spec_id, goal, non_goals, source_evidence, affected_repos, acceptance_criteria, risk_class, required_approvals, receipt_requirements, status]
      properties:
        generated_spec_id: { type: string }
        goal: { type: string }
        non_goals:
          type: array
          items: { type: string }
        source_evidence:
          type: array
          items: { type: string }
        affected_repos:
          type: array
          items: { type: string }
        acceptance_criteria:
          type: array
          items: { type: string }
        risk_class: { type: string }
        required_approvals:
          type: array
          items: { type: string }
        receipt_requirements:
          type: array
          items: { type: string }
        status: { type: string }

    ProofReplayArchiveEntry:
      type: object
      required: [id, title, status, source_confidence, failure_modes, helm_controls, counterfactual_verdict, reason_codes, evidence, verification, limits, generated_vectors, counterfactual_claim]
      properties:
        id: { type: string }
        title: { type: string }
        status:
          type: string
          enum: [confirmed, probable, emerging, watchlist, rejected_not_helm_boundary]
        source_confidence:
          type: string
          enum: [high, medium, low]
        risk_level:
          type: string
          enum: [low, medium, high, blocked]
        failure_modes:
          type: array
          items: { $ref: '#/components/schemas/FailureMode' }
        missing_authority:
          type: array
          items: { type: string }
        helm_controls:
          type: array
          items: { type: string }
        counterfactual_verdict:
          type: string
          enum: [ALLOW, DENY, ESCALATE]
        reason_codes:
          type: array
          items: { type: string }
        evidence:
          type: object
          required: [replay_policy_hash, synthetic_plan_hash, receipt_hash, evidencepack_hash]
          properties:
            replay_policy_hash: { type: string }
            synthetic_plan_hash: { type: string }
            receipt_hash: { type: string }
            evidencepack_hash: { type: string }
        verification:
          type: object
          required: [command]
          properties:
            command: { type: string }
        limits:
          type: array
          items: { type: string }
        generated_vectors:
          type: array
          items: { type: string }
        vector_status:
          type: string
          enum: [draft, exported, approved_export_pending_merge, validated_in_kernel, rejected]
        evidencepack_ref: { type: string }
        published_artifact_hash: { type: string }
        counterfactual_claim: { type: string }
        public_summary: { type: string }
        source_count: { type: integer }
        generated_spec_id: { type: string }
        source_assertions:
          type: array
          items: { $ref: '#/components/schemas/SourceAssertion' }
        published_at: { type: string, format: date-time }

    ProofReplayArchiveIndex:
      type: object
      required: [generated_at, count, entries]
      properties:
        generated_at: { type: string, format: date-time }
        count: { type: integer }
        entries:
          type: array
          items: { $ref: '#/components/schemas/ProofReplayArchiveEntry' }

  # ── 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"
