openapi: 3.0.3
info:
  title: Agent Maturity Compass API
  description: |
    REST API for the Agent Maturity Compass (AMC) — score, govern, and assure AI agent deployments.
    Protected `/v1/*` routes use a signed AMC Studio session cookie or the Studio bootstrap admin token.
    Studio applies a least-privilege role policy per route; public compatibility routes opt out explicitly.
    Bridge hook routes override the Studio server and auth defaults with their own Bridge server roots and lease scope.
  version: 1.1.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000/api
    description: Local AMC Studio instance
  - url: https://{host}/api
    description: Self-hosted AMC API behind your ingress, load balancer, or API gateway
    variables:
      host:
        default: amc.example.com
        description: DNS name for your self-hosted AMC deployment

security:
  - amcSessionCookie: []
  - amcAdminToken: []

components:
  securitySchemes:
    amcSessionCookie:
      type: apiKey
      in: cookie
      name: amc_session
      description: Signed Studio session cookie. Route access is least-privilege by role; VIEWER reads, OPERATOR runs workflows, APPROVER issues approved execution intents, AUDITOR verifies or attests, and OWNER controls secrets, signing, identity, and policy.
    amcAdminToken:
      type: apiKey
      in: header
      name: x-amc-admin-token
      description: Studio bootstrap admin token with owner-equivalent emergency access. Keep local and rotate if exposed.
    valueWebhookToken:
      type: apiKey
      in: header
      name: x-amc-webhook-token
      description: Vault-backed value webhook token stored under value/webhook/token.
    leaseToken:
      type: http
      scheme: bearer
      description: Signed, short-lived AMC agent lease. Observation requires hook:observe; explicit loopback control also requires hook:control. Both require an allowed /hooks route.

  schemas:
    ApiResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          type: object
        error:
          type: string

    ToolContextServer:
      type: object
      additionalProperties: false
      required: [serverIdentity, id, name, version, transport]
      properties:
        serverIdentity:
          type: string
          pattern: '^mcp-server:[a-f0-9]{64}$'
        id:
          type: string
          minLength: 1
          maxLength: 160
        name:
          type: string
          minLength: 1
          maxLength: 160
        version:
          type: string
          nullable: true
        transport:
          type: string
          nullable: true
          enum: [stdio, streamable-http, sse, http, null]

    ToolContextTool:
      type: object
      additionalProperties: false
      required: [toolIdentity, name, kind, actionClass, requireExecTicket, serverIdentity]
      properties:
        toolIdentity:
          type: string
          pattern: '^tool:(native|mcp):[a-f0-9]{64}$'
        name:
          type: string
        kind:
          type: string
          enum: [native, mcp]
        actionClass:
          type: string
          enum: [READ_ONLY, WRITE_LOW, WRITE_HIGH, DEPLOY, SECURITY, FINANCIAL, NETWORK_EXTERNAL, DATA_EXPORT, IDENTITY]
        requireExecTicket:
          type: boolean
        serverIdentity:
          type: string
          nullable: true
          pattern: '^mcp-server:[a-f0-9]{64}$'

    ToolContextGroup:
      type: object
      additionalProperties: false
      required: [groupIdentity, kind, label, server, tools]
      properties:
        groupIdentity:
          type: string
        kind:
          type: string
          enum: [native, mcp-server]
        label:
          type: string
        server:
          allOf:
            - $ref: '#/components/schemas/ToolContextServer'
          nullable: true
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolContextTool'

    ToolContextProjection:
      type: object
      additionalProperties: false
      required: [schemaVersion, authority, integrity, groups, tools, total, derivedView, recorded, proofEligible, claimBoundary]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-13']
        authority:
          type: object
          additionalProperties: false
          required: [kind, configSha256]
          properties:
            kind:
              type: string
              enum: [signed-toolhub-config]
            configSha256:
              type: string
              nullable: true
              pattern: '^[a-f0-9]{64}$'
        integrity:
          type: object
          additionalProperties: false
          required: [status, signatureValid, reasonCodes]
          properties:
            status:
              type: string
              enum: [trusted, untrusted]
            signatureValid:
              type: boolean
            reasonCodes:
              type: array
              items:
                type: string
                enum: [TOOL_CONTEXT_CONFIG_MISSING, TOOL_CONTEXT_SIGNATURE_MISSING, TOOL_CONTEXT_SIGNATURE_INVALID, TOOL_CONTEXT_SCHEMA_INVALID, TOOL_CONTEXT_DUPLICATE_TOOL_NAME, TOOL_CONTEXT_DUPLICATE_IDENTITY, TOOL_CONTEXT_SERVER_METADATA_CONFLICT]
        groups:
          type: array
          items:
            $ref: '#/components/schemas/ToolContextGroup'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ToolContextTool'
        total:
          type: integer
          minimum: 0
        derivedView:
          type: boolean
          enum: [true]
        recorded:
          type: boolean
          enum: [false]
        proofEligible:
          type: boolean
          enum: [false]
        claimBoundary:
          type: string

    ToolContextApiResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok:
          type: boolean
          enum: [true]
        data:
          $ref: '#/components/schemas/ToolContextProjection'

    ScoreResult:
      type: object
      properties:
        runId:
          type: string
        agentId:
          type: string
        layerScores:
          type: array
          items:
            type: object
        trustLabel:
          type: string
        integrityIndex:
          type: number

    EvidenceReadiness:
      type: object
      description: Evidence sufficiency and external-claim readiness, evaluated separately from artifact validity.
      required:
        - schemaVersion
        - status
        - claimEligible
        - label
        - reasonCodes
        - claimBoundary
        - nextStep
        - thresholds
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-10']
        status:
          type: string
          enum: [READY, LIMITED, INSUFFICIENT_EVIDENCE, UNVERIFIED]
        claimEligible:
          type: boolean
          description: True only when the evidence status is READY.
        label:
          type: string
        reasonCodes:
          type: array
          items:
            type: string
            enum:
              - ARTIFACT_UNSIGNED
              - ARTIFACT_INVALID
              - ARTIFACT_VERIFICATION_FAILED
              - TRUST_BOUNDARY_VIOLATION
              - MISSING_EVIDENCE_METADATA
              - NO_ACCEPTED_EVIDENCE
              - LOW_INTEGRITY
              - LIMITED_INTEGRITY
              - TRUST_LABEL_BLOCKED
        claimBoundary:
          type: string
        nextStep:
          type: string
        thresholds:
          type: object
          required: [readyIntegrity, insufficientIntegrityBelow]
          properties:
            readyIntegrity:
              type: number
              enum: [0.6]
            insufficientIntegrityBelow:
              type: number
              enum: [0.4]

    DiagnosticReport:
      type: object
      description: Signed AMC diagnostic artifact. Current reports include evidenceReadiness inside the signed payload; legacy reports may omit it.
      required:
        - runId
        - agentId
        - status
        - verificationPassed
        - integrityIndex
        - trustLabel
        - evidenceCoverage
      additionalProperties: true
      properties:
        runId:
          type: string
        agentId:
          type: string
        ts:
          type: integer
        status:
          type: string
          enum: [VALID, INVALID, UNSIGNED]
          description: Artifact validity only; VALID does not mean that evidence is sufficient or claims are allowed.
        verificationPassed:
          type: boolean
        trustBoundaryViolated:
          type: boolean
        trustBoundaryMessage:
          type: string
          nullable: true
        integrityIndex:
          type: number
          minimum: 0
          maximum: 1
        trustLabel:
          type: string
        evidenceCoverage:
          type: number
          minimum: 0
          maximum: 1
        evidenceTrustCoverage:
          type: object
          required: [observed, attested, selfReported]
          properties:
            observed:
              type: number
            attested:
              type: number
            selfReported:
              type: number
        evidenceReadiness:
          allOf:
            - $ref: '#/components/schemas/EvidenceReadiness'
          description: Present on reports generated with methodology 2026.07.10-r221 or later.

    DiagnosticReportResponse:
      type: object
      required: [ok, data]
      properties:
        ok:
          type: boolean
          enum: [true]
        data:
          $ref: '#/components/schemas/DiagnosticReport'

    Incident:
      type: object
      properties:
        incidentId:
          type: string
        agentId:
          type: string
        severity:
          type: string
          enum: [INFO, WARN, CRITICAL]
        state:
          type: string
          enum: [OPEN, INVESTIGATING, RESOLVED]
        title:
          type: string
        createdTs:
          type: integer

    WorkOrder:
      type: object
      properties:
        workOrderId:
          type: string
        title:
          type: string
        riskTier:
          type: string
        mode:
          type: string

    WebhookSignatureHeaders:
      type: object
      description: Headers AMC sends with signed outbound webhook deliveries.
      required:
        - x-amc-webhook-delivery-id
        - x-amc-webhook-attempt
        - x-amc-webhook-timestamp
        - x-amc-webhook-signature
      properties:
        x-amc-webhook-delivery-id:
          type: string
          example: wh_3f6e9a4c7b8245158c9df1a4b5d2f901
        x-amc-webhook-attempt:
          type: string
          example: "1"
        x-amc-webhook-timestamp:
          type: string
          description: Unix timestamp in seconds used in the HMAC signing base string.
          example: "1781607200"
        x-amc-webhook-signature:
          type: string
          description: HMAC-SHA256 signature in `sha256=<hex>` form over `<timestamp>.<body>`.
          example: sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

    WebhookEventEnvelope:
      type: object
      description: Generic AMC event envelope for webhook-style integrations and portal submissions.
      required: [eventType, source, data]
      properties:
        eventType:
          type: string
          example: value.signal.recorded
        source:
          type: string
          example: amc.value
        data:
          type: object
          additionalProperties: true
        timestamp:
          type: integer
          format: int64
        correlationId:
          type: string
        idempotencyKey:
          type: string

    WebhookDeliveryRequest:
      type: object
      description: Outbound signed webhook delivery request used by AMC integration dispatch.
      required: [url, eventType, payload, secret]
      properties:
        url:
          type: string
          format: uri
        eventType:
          type: string
        payload:
          oneOf:
            - $ref: '#/components/schemas/WebhookEventEnvelope'
            - type: object
              additionalProperties: true
            - type: string
        secret:
          type: string
          writeOnly: true
        headers:
          type: object
          additionalProperties:
            type: string

    WebhookAttemptReceipt:
      type: object
      required: [attempt, startedTs, completedTs, delivered, httpStatus, error, signature, backoffMs]
      properties:
        attempt:
          type: integer
          minimum: 1
        startedTs:
          type: integer
          format: int64
        completedTs:
          type: integer
          format: int64
        delivered:
          type: boolean
        httpStatus:
          type: integer
          nullable: true
        error:
          type: string
          nullable: true
        signature:
          type: string
        backoffMs:
          type: integer
          nullable: true

    WebhookDeliveryReceipt:
      type: object
      description: Delivery receipt emitted after AMC attempts a signed outbound webhook.
      required: [deliveryId, eventType, url, payloadSha256, createdTs, completedTs, delivered, attempts]
      properties:
        deliveryId:
          type: string
        eventType:
          type: string
        url:
          type: string
          format: uri
        payloadSha256:
          type: string
          pattern: '^[a-f0-9]{64}$'
        createdTs:
          type: integer
          format: int64
        completedTs:
          type: integer
          format: int64
        delivered:
          type: boolean
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/WebhookAttemptReceipt'

    PortalWebhookPayload:
      type: object
      description: Generic portal webhook payload accepted as a product job payload.
      required: [eventType, source, data]
      properties:
        eventType:
          type: string
        source:
          type: string
        data:
          type: object
          additionalProperties: true
        timestamp:
          type: integer
          format: int64
        correlationId:
          type: string

    OutcomeWebhookPayload:
      type: object
      description: Outcome signal webhook payload shape used by AMC outcome ingestion helpers.
      required: [agentId, signalId, category, value]
      properties:
        agentId:
          type: string
        signalId:
          type: string
        category:
          type: string
          enum: [Emotional, Functional, Economic, Brand, Lifetime]
        value:
          oneOf:
            - type: number
            - type: string
            - type: boolean
        unit:
          type: string
        ts:
          type: integer
          format: int64
        workOrderId:
          type: string
        meta:
          type: object
          additionalProperties: true

    ValueWebhookPayload:
      type: object
      description: Value KPI webhook payload accepted by AMC value ingestion helpers.
      required: [v, sourceId, scope, events]
      properties:
        v:
          type: integer
          enum: [1]
        sourceId:
          type: string
        scope:
          type: object
          required: [type, id]
          properties:
            type:
              type: string
              enum: [WORKSPACE, NODE, AGENT]
            id:
              type: string
        events:
          type: array
          minItems: 1
          items:
            type: object
            required: [kpiId, value]
            properties:
              ts:
                type: integer
                format: int64
              kpiId:
                type: string
              value:
                type: number
              unit:
                type: string
              labels:
                type: object
                additionalProperties:
                  type: string

    TypedGraphValidationIssue:
      type: object
      properties:
        code:
          type: string
          enum:
            - invalid_schema
            - duplicate_node
            - duplicate_edge
            - missing_node
            - missing_node_contract
            - missing_handoff_contract
            - contract_schema_mismatch
            - unsafe_permission_without_policy
            - cycle_detected
            - unbounded_fanout
        severity:
          type: string
          enum: [warning, error]
        message:
          type: string
        nodeId:
          type: string
        edgeId:
          type: string
        evidenceRefs:
          type: array
          items:
            type: string

    TypedGraphValidation:
      type: object
      properties:
        valid:
          type: boolean
        summary:
          type: string
        issueCount:
          type: integer
        issues:
          type: array
          items:
            $ref: '#/components/schemas/TypedGraphValidationIssue'

    TypedMultiAgentGraph:
      type: object
      required: [schemaVersion, graphId, nodes]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-05-22']
        graphId:
          type: string
        fleetId:
          type: string
        createdAt:
          type: string
        maxFanOut:
          type: integer
        nodes:
          type: array
          items:
            type: object
        edges:
          type: array
          items:
            type: object
        invariants:
          type: array
          items:
            type: object

    TypedMultiAgentGraphRef:
      type: object
      properties:
        graphId:
          type: string
        path:
          type: string
        digestSha256:
          type: string
        nodeCount:
          type: integer
        edgeCount:
          type: integer
        validation:
          $ref: '#/components/schemas/TypedGraphValidation'

    ExploitConfirmationScope:
      type: object
      required: [schemaVersion, scopeId, target, allowedTechniques, windowStartTs, windowEndTs, safeMode]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-05-22']
        scopeId:
          type: string
        target:
          type: object
          properties:
            type:
              type: string
              enum: [WORKSPACE, AGENT, NODE, URL, SERVICE]
            id:
              type: string
            ownership:
              type: object
        allowedTechniques:
          type: array
          items:
            type: string
            enum: [prompt_injection, tool_abuse, data_exfiltration, sandbox_escape, auth_bypass, model_route_poisoning, rag_poisoning]
        windowStartTs:
          type: integer
        windowEndTs:
          type: integer
        safeMode:
          type: string
          enum: [synthetic_replay, sandbox_repro, log_correlation]
        reviewerApproval:
          type: object
        constraints:
          type: object

    ExploitConfirmationTask:
      type: object
      required: [taskId, findingId, targetId, technique, hypothesis, requestedBy, requestedTs]
      properties:
        taskId:
          type: string
        findingId:
          type: string
        targetId:
          type: string
        technique:
          type: string
        hypothesis:
          type: string
          description: Raw hypothesis is never included in safe proof exports; only its SHA-256 hash is persisted in public artifacts.
        requestedBy:
          type: string
        requestedTs:
          type: integer
        evidenceRefs:
          type: array
          items:
            type: string
        proofSignals:
          type: array
          items:
            type: object

    ExploitConfirmationProof:
      type: object
      properties:
        proofId:
          type: string
        scopeId:
          type: string
        findingId:
          type: string
        confirmationStatus:
          type: string
          enum: [CONFIRMED_SAFE_PROOF, INCONCLUSIVE]
        exploitInstructionsIncluded:
          type: boolean
          enum: [false]
        rawPayloadStored:
          type: boolean
          enum: [false]
        safeProof:
          type: object

    NeutralImportPlan:
      type: object
      properties:
        importId:
          type: string
        agentId:
          type: string
        sourcePath:
          type: string
        status:
          type: string
          enum: [ready, unsupported, blocked]
        candidateCount:
          type: integer
        redactionCount:
          type: integer
        categories:
          type: array
          items:
            type: string
            enum: [trace-jsonl, event-log, run-directory, workflow-graph, agent-config, memory-store, eval-output, benchmark-result]
        candidates:
          type: array
          items:
            type: object

    NeutralImportResult:
      type: object
      properties:
        importId:
          type: string
        mode:
          type: string
          enum: [dry-run, validate, import]
        applied:
          type: boolean
        plan:
          $ref: '#/components/schemas/NeutralImportPlan'
        normalizedPath:
          type: string
          nullable: true

    InferenceStrategyRun:
      type: object
      properties:
        strategyRunId:
          type: string
        recommendedStrategyId:
          type: string
        confidence:
          type: number
        tradeoffSummary:
          type: string
        routeChange:
          type: object
        strategies:
          type: array
          items:
            type: object

    DomainProofSourceRuleManifest:
      type: object
      additionalProperties: false
      required: [v, manifestId, domainId, jurisdiction, sourceTitle, sourceUrl, sourceHash, effectiveDate, retrievedAt, clauses, review, proofCoverage]
      properties:
        v:
          type: integer
          const: 1
        manifestId:
          type: string
          pattern: '^srcmanifest_[A-Za-z0-9_-]{3,}$'
        domainId:
          type: string
          enum: [health, education, environment, mobility, governance, technology, wealth]
        jurisdiction:
          type: string
        sourceTitle:
          type: string
        sourceUrl:
          type: string
        sourceHash:
          type: string
          pattern: '^[a-f0-9]{64}$'
        effectiveDate:
          type: string
          format: date
        retrievedAt:
          type: string
        clauses:
          type: array
          minItems: 1
          items:
            type: object
            additionalProperties: false
            required: [clauseId, sourceSpan, formalClauseId, owner, reviewer, ambiguityFlags, staleAfter, dependencies, exceptions, clauseHash]
            properties:
              clauseId: { type: string }
              sourceSpan: { type: string }
              formalClauseId: { type: string }
              owner: { type: string }
              reviewer: { type: string }
              ambiguityFlags:
                type: array
                items: { type: string }
              staleAfter: { type: string, format: date }
              dependencies:
                type: array
                items: { type: string }
              exceptions:
                type: array
                items: { type: string }
              clauseHash:
                type: string
                pattern: '^[a-f0-9]{64}$'
        review:
          type: object
          additionalProperties: false
          required: [status, reviewerRole, reviewedAt, nonLegalDisclaimer]
          properties:
            status:
              type: string
              enum: [pending, reviewed, rejected]
            reviewerRole: { type: string }
            reviewedAt: { type: string }
            notes: { type: string }
            nonLegalDisclaimer: { type: string }
        proofCoverage:
          type: object
          additionalProperties: false
          required: [sourceClauseCount, formalizedCount, reviewedCount]
          properties:
            sourceClauseCount: { type: integer, minimum: 0 }
            formalizedCount: { type: integer, minimum: 0 }
            reviewedCount: { type: integer, minimum: 0 }

    DomainProofCheckInput:
      type: object
      additionalProperties: false
      required: [claimText]
      properties:
        claimText:
          type: string
          minLength: 1
        facts:
          type: object
          additionalProperties: false
          properties:
            age: { type: integer }
            residency: { type: string }
        evidenceRefs:
          type: array
          items: { type: string, minLength: 1 }

    DomainProofCheckRequest:
      type: object
      additionalProperties: false
      required: [domain, manifest, input]
      properties:
        domain:
          type: string
          description: Domain proof fixture or rule lane. Current public P0 support is governance.
          enum: [governance]
          example: governance
        manifest:
          description: Inline source-to-rule manifest. The current toy lane requires AMC's canonical toy source and manifest structure, not only schema shape. Deprecated path strings are accepted only inside the built-in fixtures/domain-proof root and cannot follow symlinks outside it.
          oneOf:
            - $ref: '#/components/schemas/DomainProofSourceRuleManifest'
            - type: string
              deprecated: true
              pattern: '^fixtures/domain-proof/'
              example: fixtures/domain-proof/toy-governance/source-rule-manifest.json
        input:
          description: Inline proof-check input. Deprecated path strings are accepted only inside the built-in examples/domain-proof root and cannot follow symlinks outside it.
          oneOf:
            - $ref: '#/components/schemas/DomainProofCheckInput'
            - type: string
              deprecated: true
              pattern: '^examples/domain-proof/'
              example: examples/domain-proof/toy-governance/proven.json

    DomainProofStatus:
      type: object
      properties:
        status:
          type: string
          example: available
        lane:
          type: string
          example: Domain Proof Lane
        supportedDomains:
          type: array
          items:
            type: string
        proofClasses:
          type: array
          items:
            type: string
            enum: [evidence_integrity, runtime_policy, domain_correctness]
        correctnessProofStatuses:
          type: array
          items:
            type: string
            enum: [proven, disproven, unsupported, not_applicable]
        preferredInputMode:
          type: string
          enum: [inline_json]
        legacyFixturePaths:
          type: string
          enum: [deprecated]
        apiFileWrites:
          type: string
          enum: [disabled]
        nonClaim:
          type: string

    ObservedAepActionEvent:
      $ref: './schemas/observed-aep-action-event-0.1.schema.json'

    ObservedHookReceipt:
      $ref: './schemas/observed-hook-receipt.schema.json'

    ControlProjectionSource:
      type: object
      additionalProperties: false
      required: [sourceId, ownerModule, configPath, signaturePath, integrity, configured, revision, reason, remediation]
      properties:
        sourceId:
          type: string
          enum: [runtime-firewall-policy, guardrail-control-state, action-policy, approval-policy]
        ownerModule: { type: string }
        configPath: { type: string }
        signaturePath: { type: string }
        integrity:
          type: string
          enum: [trusted, uninitialized, invalid]
        configured: { type: boolean }
        revision:
          type: integer
          nullable: true
        reason: { type: string }
        remediation:
          type: string
          nullable: true

    ProjectedControl:
      type: object
      additionalProperties: false
      required: [controlId, label, scope, when, requestedAction, effectiveAction, status, trusted, scopeTemplateIds, sourceRefs, reasons]
      properties:
        controlId: { type: string }
        label: { type: string }
        scope: { type: string }
        when:
          type: array
          items: { type: string }
        requestedAction:
          type: string
          enum: [observe, warn, block, execute, simulate, deny, require_approval, allow, inactive, unavailable]
        effectiveAction:
          type: string
          enum: [observe, warn, block, execute, simulate, deny, require_approval, allow, inactive, unavailable]
        status:
          type: string
          enum: [active, inactive, fail_closed, unavailable]
        trusted: { type: boolean }
        scopeTemplateIds:
          type: array
          maxItems: 1
          items:
            type: string
            enum: [read-only, workspace-change, release-external, privileged-sensitive]
        sourceRefs:
          type: array
          items:
            type: string
            enum: [runtime-firewall-policy, guardrail-control-state, action-policy, approval-policy]
        reasons:
          type: array
          items: { type: string }

    ControlFamilyProjection:
      type: object
      additionalProperties: false
      required: [familyId, label, ownerModule, integrity, sources, controls, unboundGuardrails, reasons]
      properties:
        familyId:
          type: string
          enum: [runtime-traffic, action-policy, approval-policy]
        label: { type: string }
        ownerModule: { type: string }
        integrity:
          type: string
          enum: [trusted, uninitialized, invalid]
        sources:
          type: array
          items: { $ref: '#/components/schemas/ControlProjectionSource' }
        controls:
          type: array
          items: { $ref: '#/components/schemas/ProjectedControl' }
        unboundGuardrails:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [name, category, description, status, reason]
            properties:
              name: { type: string }
              category: { type: string }
              description: { type: string }
              status:
                type: string
                enum: [unbound]
              reason: { type: string }
        reasons:
          type: array
          items: { type: string }

    ControlProjection:
      type: object
      additionalProperties: false
      required: [schemaVersion, projectedAt, status, counts, families, reasons]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-11']
        projectedAt:
          type: string
          format: date-time
        status:
          type: string
          enum: [trusted, partial, uninitialized, fail_closed]
        counts:
          type: object
          additionalProperties: false
          required: [families, controls, active, inactive, failClosed, unavailable, trusted, unboundGuardrails]
          properties:
            families: { type: integer, minimum: 0 }
            controls: { type: integer, minimum: 0 }
            active: { type: integer, minimum: 0 }
            inactive: { type: integer, minimum: 0 }
            failClosed: { type: integer, minimum: 0 }
            unavailable: { type: integer, minimum: 0 }
            trusted: { type: integer, minimum: 0 }
            unboundGuardrails: { type: integer, minimum: 0 }
        families:
          type: array
          items: { $ref: '#/components/schemas/ControlFamilyProjection' }
        reasons:
          type: array
          items: { type: string }

    ControlProjectionResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok:
          type: boolean
          enum: [true]
        data:
          $ref: '#/components/schemas/ControlProjection'

    ActionClass:
      type: string
      enum: [READ_ONLY, WRITE_LOW, WRITE_HIGH, DEPLOY, SECURITY, FINANCIAL, NETWORK_EXTERNAL, DATA_EXPORT, IDENTITY]

    PolicyEvidenceLogic:
      description: Strict gate/all/any tree. The server additionally enforces depth 6, 64 total nodes, 16 children per group, 8,192 serialized bytes, and at most 60 declared gates.
      oneOf:
        - type: object
          additionalProperties: false
          required: [gate]
          properties:
            gate:
              type: string
              maxLength: 128
              pattern: '^(maturity|assurance):(?:[A-Za-z0-9][A-Za-z0-9._-]*|~[a-f0-9]{64})$'
        - type: object
          additionalProperties: false
          required: [all]
          properties:
            all:
              type: array
              minItems: 2
              maxItems: 16
              items: { $ref: '#/components/schemas/PolicyEvidenceLogic' }
        - type: object
          additionalProperties: false
          required: [any]
          properties:
            any:
              type: array
              minItems: 2
              maxItems: 16
              items: { $ref: '#/components/schemas/PolicyEvidenceLogic' }

    NullablePolicyEvidenceLogic:
      oneOf:
        - type: object
          nullable: true
          enum: [null]
        - { $ref: '#/components/schemas/PolicyEvidenceLogic' }

    ActionEvidenceGate:
      type: object
      additionalProperties: false
      required: [gateId, family, label]
      properties:
        gateId: { type: string, maxLength: 128 }
        family: { type: string, enum: [maturity, assurance] }
        label: { type: string }

    ActionEvidencePolicyHash:
      type: object
      additionalProperties: false
      required: [actionPolicySha256]
      properties:
        actionPolicySha256: { type: string, pattern: '^[a-f0-9]{64}$' }

    ActionEvidenceLogicCompileRequest:
      type: object
      additionalProperties: false
      required: [actionClass, logic]
      properties:
        actionClass: { $ref: '#/components/schemas/ActionClass' }
        logic: { $ref: '#/components/schemas/PolicyEvidenceLogic' }

    ActionEvidenceLogicApplyRequest:
      type: object
      additionalProperties: false
      required: [actionClass, logic, confirmCompileId, acknowledgeAlternatives]
      properties:
        actionClass: { $ref: '#/components/schemas/ActionClass' }
        logic: { $ref: '#/components/schemas/PolicyEvidenceLogic' }
        confirmCompileId: { type: string, pattern: '^action-logic-compile-[a-f0-9]{16}$' }
        acknowledgeAlternatives: { type: boolean, default: false }

    ActionEvidenceLogicInspection:
      type: object
      additionalProperties: false
      required: [schemaVersion, actionClass, configured, gateCount, gates, effectiveLogic, effectiveLogicSha256, hasAlternatives, mandatoryGates, baseline]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-11'] }
        actionClass: { $ref: '#/components/schemas/ActionClass' }
        configured: { type: boolean }
        gateCount: { type: integer, minimum: 0, maximum: 60 }
        gates:
          type: array
          maxItems: 60
          items: { $ref: '#/components/schemas/ActionEvidenceGate' }
        effectiveLogic: { $ref: '#/components/schemas/NullablePolicyEvidenceLogic' }
        effectiveLogicSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        hasAlternatives: { type: boolean }
        mandatoryGates:
          type: array
          minItems: 9
          maxItems: 9
          items: { type: string }
        baseline: { $ref: '#/components/schemas/ActionEvidencePolicyHash' }

    ActionEvidenceLogicCompilation:
      type: object
      additionalProperties: false
      required: [schemaVersion, compileId, actionClass, status, canApply, hasAlternatives, requiresAlternativeAcknowledgement, gateCount, gates, mandatoryGates, baseline, candidate, logic]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-11'] }
        compileId: { type: string, pattern: '^action-logic-compile-[a-f0-9]{16}$' }
        actionClass: { $ref: '#/components/schemas/ActionClass' }
        status: { type: string, enum: [ready, no_changes] }
        canApply: { type: boolean }
        hasAlternatives: { type: boolean }
        requiresAlternativeAcknowledgement: { type: boolean }
        gateCount: { type: integer, minimum: 1, maximum: 60 }
        gates:
          type: array
          minItems: 1
          maxItems: 60
          items: { $ref: '#/components/schemas/ActionEvidenceGate' }
        mandatoryGates:
          type: array
          minItems: 9
          maxItems: 9
          items: { type: string }
        baseline: { $ref: '#/components/schemas/ActionEvidencePolicyHash' }
        candidate: { $ref: '#/components/schemas/ActionEvidencePolicyHash' }
        logic:
          type: object
          additionalProperties: false
          required: [configuredBefore, current, candidate, currentSha256, candidateSha256]
          properties:
            configuredBefore: { type: boolean }
            current: { $ref: '#/components/schemas/NullablePolicyEvidenceLogic' }
            candidate: { $ref: '#/components/schemas/NullablePolicyEvidenceLogic' }
            currentSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
            candidateSha256: { type: string, pattern: '^[a-f0-9]{64}$' }

    ActionEvidenceLogicApplyResult:
      type: object
      additionalProperties: false
      required: [schemaVersion, applied, reason, compileId, compilation, transparencyHash, auditEventId]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-11'] }
        applied: { type: boolean }
        reason: { type: string, nullable: true, enum: [NO_CHANGES, null] }
        compileId: { type: string, pattern: '^action-logic-compile-[a-f0-9]{16}$' }
        compilation: { $ref: '#/components/schemas/ActionEvidenceLogicCompilation' }
        transparencyHash: { type: string, nullable: true, pattern: '^[a-f0-9]{64}$' }
        auditEventId: { type: string, nullable: true }

    ActionEvidenceLogicInspectionResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data: { $ref: '#/components/schemas/ActionEvidenceLogicInspection' }

    ActionEvidenceLogicCompilationResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data: { $ref: '#/components/schemas/ActionEvidenceLogicCompilation' }

    ActionEvidenceLogicApplyResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data: { $ref: '#/components/schemas/ActionEvidenceLogicApplyResult' }

    ScopeTemplate:
      type: object
      additionalProperties: false
      required: [schemaVersion, templateId, version, label, description, actionClasses]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-11']
        templateId:
          type: string
          enum: [read-only, workspace-change, release-external, privileged-sensitive]
        version:
          type: integer
          enum: [1]
        label: { type: string, minLength: 1, maxLength: 80 }
        description: { type: string, minLength: 1, maxLength: 240 }
        actionClasses:
          type: array
          minItems: 1
          maxItems: 9
          uniqueItems: true
          items:
            type: string
            enum: [READ_ONLY, WRITE_LOW, WRITE_HIGH, DEPLOY, SECURITY, FINANCIAL, NETWORK_EXTERNAL, DATA_EXPORT, IDENTITY]

    ScopeTemplateCompileRequest:
      type: object
      additionalProperties: false
      required: [templateId, packId]
      properties:
        templateId:
          type: string
          enum: [read-only, workspace-change, release-external, privileged-sensitive]
        packId: { type: string, pattern: '^[a-z0-9][a-z0-9.-]*$', maxLength: 120 }

    ScopeTemplateApplyRequest:
      type: object
      additionalProperties: false
      required: [templateId, packId, confirmCompileId]
      properties:
        templateId:
          type: string
          enum: [read-only, workspace-change, release-external, privileged-sensitive]
        packId: { type: string, pattern: '^[a-z0-9][a-z0-9.-]*$', maxLength: 120 }
        confirmCompileId: { type: string, pattern: '^scope-compile-[a-f0-9]{16}$' }

    ScopeTemplatePolicyChangeCell:
      type: object
      additionalProperties: false
      required: [changed, beforeSha256, afterSha256]
      properties:
        changed: { type: boolean }
        beforeSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        afterSha256: { type: string, pattern: '^[a-f0-9]{64}$' }

    ScopeTemplatePolicyChange:
      type: object
      additionalProperties: false
      required: [actionClass, actionPolicy, approvalPolicy]
      properties:
        actionClass:
          type: string
          enum: [READ_ONLY, WRITE_LOW, WRITE_HIGH, DEPLOY, SECURITY, FINANCIAL, NETWORK_EXTERNAL, DATA_EXPORT, IDENTITY]
        actionPolicy: { $ref: '#/components/schemas/ScopeTemplatePolicyChangeCell' }
        approvalPolicy: { $ref: '#/components/schemas/ScopeTemplatePolicyChangeCell' }

    ScopeTemplatePolicyHashes:
      type: object
      additionalProperties: false
      required: [actionPolicySha256, approvalPolicySha256]
      properties:
        actionPolicySha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        approvalPolicySha256: { type: string, pattern: '^[a-f0-9]{64}$' }

    ScopeTemplateCompilation:
      type: object
      additionalProperties: false
      required: [schemaVersion, compileId, scope, fleetBoundary, template, pack, status, canApply, baseline, candidate, changes]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-11']
        compileId: { type: string, pattern: '^scope-compile-[a-f0-9]{16}$' }
        scope:
          type: string
          enum: [workspace]
        fleetBoundary: { type: string }
        template: { $ref: '#/components/schemas/ScopeTemplate' }
        pack:
          type: object
          additionalProperties: false
          required: [packId, name, riskTier]
          properties:
            packId: { type: string }
            name: { type: string }
            riskTier:
              type: string
              enum: [low, medium, high, critical]
        status:
          type: string
          enum: [ready, no_changes]
        canApply: { type: boolean }
        baseline: { $ref: '#/components/schemas/ScopeTemplatePolicyHashes' }
        candidate: { $ref: '#/components/schemas/ScopeTemplatePolicyHashes' }
        changes:
          type: array
          minItems: 1
          maxItems: 4
          items: { $ref: '#/components/schemas/ScopeTemplatePolicyChange' }

    ScopeTemplateApplyResult:
      type: object
      additionalProperties: false
      required: [schemaVersion, applied, reason, compileId, compilation, transparencyHash, auditEventId]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-11']
        applied: { type: boolean }
        reason:
          type: string
          enum: [NO_CHANGES]
          nullable: true
        compileId: { type: string, pattern: '^scope-compile-[a-f0-9]{16}$' }
        compilation: { $ref: '#/components/schemas/ScopeTemplateCompilation' }
        transparencyHash:
          type: string
          pattern: '^[a-f0-9]{64}$'
          nullable: true
        auditEventId:
          type: string
          nullable: true

    ScopeTemplateCatalogResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok:
          type: boolean
          enum: [true]
        data:
          type: object
          additionalProperties: false
          required: [templates]
          properties:
            templates:
              type: array
              minItems: 4
              maxItems: 4
              items: { $ref: '#/components/schemas/ScopeTemplate' }

    ScopeTemplateCompilationResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok:
          type: boolean
          enum: [true]
        data: { $ref: '#/components/schemas/ScopeTemplateCompilation' }

    ScopeTemplateApplyResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok:
          type: boolean
          enum: [true]
        data: { $ref: '#/components/schemas/ScopeTemplateApplyResult' }

    EnforceResourceIntegrity:
      type: object
      additionalProperties: false
      required: [valid, reasonCodes]
      properties:
        valid: { type: boolean }
        reasonCodes:
          type: array
          items:
            type: string
            enum:
              - MANIFEST_MISSING
              - MANIFEST_SCHEMA_INVALID
              - MANIFEST_HASH_INVALID
              - MANIFEST_ID_INVALID
              - MANIFEST_COUNT_INVALID
              - MANIFEST_DUPLICATE_RESOURCE
              - MANIFEST_SIGNATURE_INVALID
              - MANIFEST_SCOPE_INVALID
              - MANIFEST_PATH_INVALID
              - SNAPSHOT_MISSING
              - SNAPSHOT_MANIFEST_INVALID
              - SNAPSHOT_SIGNATURE_INVALID
              - SNAPSHOT_RESOURCE_INVALID
              - ACTIVATION_CONFIRMATION_REQUIRED
              - ROLLBACK_CONFIRMATION_REQUIRED
              - ROLLBACK_TARGET_MISSING
              - ROLLBACK_STATE_CHANGED
              - RESOURCE_STATE_CHANGED
              - RESOURCE_STATE_BUSY
              - RECEIPT_SIGNATURE_INVALID

    EnforceResourceDiff:
      type: object
      additionalProperties: false
      required: [added, removed, changed, unchanged]
      properties:
        added: { type: array, items: { type: object } }
        removed: { type: array, items: { type: object } }
        changed: { type: array, items: { type: object } }
        unchanged: { type: integer, minimum: 0 }

    EnforceResourceVersionRef:
      type: object
      additionalProperties: false
      required: [manifestId, version, resourcesSha256, resourceCount, createdAt, ref]
      properties:
        manifestId: { type: string, pattern: '^enforce-resources-[a-f0-9]{16}$' }
        version: { type: string }
        resourcesSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        resourceCount: { type: integer, minimum: 0 }
        createdAt: { type: string, format: date-time }
        ref: { type: string, description: Workspace-relative canonical manifest reference }

    EnforceResourceLifecycleStatus:
      type: object
      additionalProperties: false
      required: [schemaVersion, agentId, state, active, previous, rollbackTarget, pendingDiff, integrity, nextAction, claimBoundary]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-11'] }
        agentId: { type: string }
        state: { type: string, enum: [NOT_INITIALIZED, ACTIVE, DRIFTED, BLOCKED] }
        active:
          nullable: true
          allOf: [{ $ref: '#/components/schemas/EnforceResourceVersionRef' }]
        previous:
          nullable: true
          allOf: [{ $ref: '#/components/schemas/EnforceResourceVersionRef' }]
        rollbackTarget:
          nullable: true
          allOf: [{ $ref: '#/components/schemas/EnforceResourceVersionRef' }]
        pendingDiff: { $ref: '#/components/schemas/EnforceResourceDiff' }
        integrity: { $ref: '#/components/schemas/EnforceResourceIntegrity' }
        nextAction:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            label: { type: string }
            command: { type: string }
        claimBoundary: { type: string }

    EnforceResourceLifecycleStatusResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data: { $ref: '#/components/schemas/EnforceResourceLifecycleStatus' }

    EnforceResourceVerificationResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data:
          type: object
          additionalProperties: false
          required: [valid, manifestPath, expectedManifestId, currentManifestId, diff, signature, integrity]
          properties:
            valid: { type: boolean }
            manifestPath: { type: string }
            expectedManifestId: { type: string }
            currentManifestId: { type: string }
            diff: { $ref: '#/components/schemas/EnforceResourceDiff' }
            signature: { type: object }
            integrity: { $ref: '#/components/schemas/EnforceResourceIntegrity' }

    EnforceResourceApplyRequest:
      type: object
      additionalProperties: false
      properties:
        agentId: { type: string }
        manifestPath: { type: string, description: Workspace-relative canonical baseline reference }
        dryRun: { type: boolean, default: true }
        force: { type: boolean, default: false, description: Cannot bypass hard integrity failures }
        confirmManifestId: { type: string, pattern: '^enforce-resources-[a-f0-9]{16}$', description: Required for activation and must equal the preview currentManifestId }

    EnforceResourceRollbackRequest:
      type: object
      additionalProperties: false
      properties:
        agentId: { type: string }
        manifestPath: { type: string, description: Workspace-relative canonical signed snapshot reference }
        resource: { type: string }
        apply: { type: boolean, default: false }
        includeImmutable: { type: boolean, default: false }
        confirmManifestId: { type: string, pattern: '^enforce-resources-[a-f0-9]{16}$', description: Required for applied rollback and must equal the preview targetManifestId }

    ControlSimulationRequest:
      type: object
      additionalProperties: false
      required: [controlId]
      properties:
        controlId:
          type: string
          minLength: 1
          maxLength: 100
          description: Control ID returned by amc policy controls
        content:
          type: string
          minLength: 1
          maxLength: 250000
          description: Runtime Firewall input; transient and never returned or recorded
        direction:
          type: string
          enum: [request, response]
        agentId:
          type: string
          minLength: 1
          maxLength: 200
        riskTier:
          type: string
          enum: [low, med, high, critical]
        requestedMode:
          type: string
          enum: [SIMULATE, EXECUTE]
        hasExecTicket:
          type: boolean

    ControlSimulationCondition:
      type: object
      additionalProperties: false
      required: [conditionId, label, passed, actual, expected, reason]
      properties:
        conditionId: { type: string }
        label: { type: string }
        passed:
          type: boolean
          nullable: true
        actual:
          anyOf:
            - { type: string, nullable: true }
            - { type: number }
            - { type: boolean }
        expected:
          anyOf:
            - { type: string, nullable: true }
            - { type: number }
            - { type: boolean }
        reason: { type: string }

    ControlSimulation:
      type: object
      additionalProperties: false
      required: [schemaVersion, simulatedAt, familyId, controlId, label, sourceIntegrity, evaluator, evaluatorParity, outcome, matched, matchedRuleIds, matchedControlIds, conditions, reasons, inputSha256, simulationOnly, recorded, proofEligible, failClosed]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-11']
        simulatedAt:
          type: string
          format: date-time
        familyId:
          type: string
          enum: [runtime-traffic, action-policy, approval-policy]
        controlId: { type: string }
        label: { type: string }
        sourceIntegrity:
          type: string
          enum: [trusted, uninitialized, invalid]
        evaluator:
          type: string
          enum: [runtime-firewall, action-policy, approval-policy]
        evaluatorParity:
          type: string
          enum: [production]
        outcome:
          type: string
          enum: [observe, warn, block, execute, simulate, deny, require_approval, allow]
        matched: { type: boolean }
        matchedRuleIds:
          type: array
          items: { type: string }
        matchedControlIds:
          type: array
          items: { type: string }
        conditions:
          type: array
          items: { $ref: '#/components/schemas/ControlSimulationCondition' }
        reasons:
          type: array
          items: { type: string }
        inputSha256:
          type: string
          pattern: '^[a-f0-9]{64}$'
        simulationOnly:
          type: boolean
          enum: [true]
        recorded:
          type: boolean
          enum: [false]
        proofEligible:
          type: boolean
          enum: [false]
        failClosed: { type: boolean }

    ControlSimulationResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok:
          type: boolean
          enum: [true]
        data:
          $ref: '#/components/schemas/ControlSimulation'

    RuntimeFirewallRolloutStatus:
      type: object
      additionalProperties: false
      required: [schemaVersion, status, claimEligible, currentPolicy, evidence, counters, byRule, window, reasonCodes, claimBoundary]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-12']
        status:
          type: string
          enum: [empty, trusted, partial, fail_closed]
        claimEligible:
          type: boolean
          description: True only when an enabled current exact-policy binding contains verified evidence and no fail-closed condition exists. Disabled policies are never claim-eligible, and this value never authorizes automatic promotion.
        currentPolicy:
          type: object
          additionalProperties: false
          required: [integrity, enabled, mode, revision, sha256]
          properties:
            integrity: { type: string, enum: [uninitialized, trusted, invalid] }
            enabled: { type: boolean }
            mode: { type: string, enum: [observe, warn, block, disabled, missing-policy, invalid-policy, invalid-control-state] }
            revision: { type: integer, nullable: true, minimum: 1 }
            sha256: { type: string, nullable: true, pattern: '^[a-f0-9]{64}$' }
        evidence:
          type: object
          additionalProperties: false
          required: [totalEvaluations, trustedEvaluations, invalidEvaluations, legacyUnclassifiedEvaluations, otherPolicyEvaluations]
          properties:
            totalEvaluations: { type: integer, minimum: 0 }
            trustedEvaluations: { type: integer, minimum: 0 }
            invalidEvaluations: { type: integer, minimum: 0 }
            legacyUnclassifiedEvaluations: { type: integer, minimum: 0 }
            otherPolicyEvaluations: { type: integer, minimum: 0 }
        counters:
          type: object
          additionalProperties: false
          required: [evaluations, matchedEvaluations, nonMatchedEvaluations, candidateAllow, wouldWarn, wouldBlock, actualAllow, actualWarn, actualBlock, enforcementSuppressed]
          properties:
            evaluations: { type: integer, minimum: 0 }
            matchedEvaluations: { type: integer, minimum: 0 }
            nonMatchedEvaluations: { type: integer, minimum: 0 }
            candidateAllow: { type: integer, minimum: 0 }
            wouldWarn: { type: integer, minimum: 0 }
            wouldBlock: { type: integer, minimum: 0 }
            actualAllow: { type: integer, minimum: 0 }
            actualWarn: { type: integer, minimum: 0 }
            actualBlock: { type: integer, minimum: 0 }
            enforcementSuppressed: { type: integer, minimum: 0 }
        byRule:
          type: object
          additionalProperties:
            type: object
            additionalProperties: false
            required: [matches, wouldWarn, wouldBlock, actualWarn, actualBlock, enforcementSuppressed]
            properties:
              matches: { type: integer, minimum: 0 }
              wouldWarn: { type: integer, minimum: 0 }
              wouldBlock: { type: integer, minimum: 0 }
              actualWarn: { type: integer, minimum: 0 }
              actualBlock: { type: integer, minimum: 0 }
              enforcementSuppressed: { type: integer, minimum: 0 }
        window:
          type: object
          additionalProperties: false
          required: [firstEventAt, lastEventAt]
          properties:
            firstEventAt: { type: string, format: date-time, nullable: true }
            lastEventAt: { type: string, format: date-time, nullable: true }
        reasonCodes:
          type: array
          items:
            type: string
            enum: [NO_DECISION_EVIDENCE, CURRENT_POLICY_UNAVAILABLE, INVALID_DECISION_EVIDENCE, LEGACY_UNCLASSIFIED_EVIDENCE, HISTORICAL_POLICY_EVIDENCE_EXCLUDED, NO_CURRENT_POLICY_EVIDENCE, CURRENT_POLICY_DISABLED, COUNTER_INVARIANT_FAILED]
        claimBoundary: { type: string }

    RuntimeFirewallDecisionRollout:
      type: object
      additionalProperties: false
      required: [schemaVersion, mode, sourceIntegrity, policyRevision, policySha256, thresholds, candidateAction, actualAction, enforcementSuppressed]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-12'] }
        mode: { type: string, enum: [observe, warn, block, disabled, missing-policy, invalid-policy, invalid-control-state] }
        sourceIntegrity: { type: string, enum: [uninitialized, trusted, invalid] }
        policyRevision: { type: integer, nullable: true, minimum: 1 }
        policySha256: { type: string, nullable: true, pattern: '^[a-f0-9]{64}$' }
        thresholds:
          type: object
          nullable: true
          additionalProperties: false
          required: [warnAt, blockAt]
          properties:
            warnAt: { type: number, minimum: 0, maximum: 100 }
            blockAt: { type: number, minimum: 0, maximum: 100 }
        candidateAction: { type: string, enum: [allow, warn, block] }
        actualAction: { type: string, enum: [allow, warn, block] }
        enforcementSuppressed: { type: boolean }

    RuntimeFirewallDecisionResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data:
          type: object
          additionalProperties: true
          required: [schemaVersion, mode, action, rollout]
          properties:
            schemaVersion: { type: string, enum: ['2026-07-12'] }
            mode: { type: string, enum: [observe, warn, block, disabled, missing-policy, invalid-policy, invalid-control-state] }
            action: { type: string, enum: [allow, warn, block] }
            rollout: { $ref: '#/components/schemas/RuntimeFirewallDecisionRollout' }

    RuntimeFirewallEventsResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data:
          type: object
          additionalProperties: false
          required: [events, total]
          properties:
            events:
              type: array
              items:
                type: object
                additionalProperties: true
                required: [schemaVersion, mode, action]
                properties:
                  schemaVersion: { type: string, enum: ['2026-05-22', '2026-07-12'] }
                  mode: { type: string, enum: [observe, warn, block, disabled, missing-policy, invalid-policy, invalid-control-state] }
                  action: { type: string, enum: [allow, warn, block] }
                  rollout: { $ref: '#/components/schemas/RuntimeFirewallDecisionRollout' }
            total: { type: integer, minimum: 0 }

    RuntimeFirewallStatusResponse:
      type: object
      additionalProperties: false
      required: [ok, data]
      properties:
        ok: { type: boolean, enum: [true] }
        data:
          type: object
          additionalProperties: true
          required: [rollout]
          properties:
            rollout: { $ref: '#/components/schemas/RuntimeFirewallRolloutStatus' }

    HookHealthDiagnostic:
      type: object
      additionalProperties: false
      required: [schemaVersion, provider, agentId, mode, status, failClosed, reasonCodes, installation, evidence, repairCommands, derivedDiagnostic, recorded, proofEligible, claimBoundary]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-13'] }
        provider: { type: string, enum: [claude-code, gemini-cli] }
        agentId: { type: string, nullable: true }
        mode: { type: string, nullable: true, enum: [observe, control] }
        status: { type: string, enum: [not_installed, awaiting_first_event, observed, fail_closed] }
        failClosed: { type: boolean }
        reasonCodes:
          type: array
          items:
            type: string
            enum: [HOOK_NOT_INSTALLED, HOOK_INSTALLATION_DRIFTED, HOOK_INSTALLATION_EXPIRED, HOOK_INSTALLATION_INVALID, HOOK_EVENT_NOT_OBSERVED, HOOK_EVENT_METADATA_INVALID, HOOK_EVIDENCE_INTEGRITY_FAILED, HOOK_EVIDENCE_UNAVAILABLE]
        installation:
          type: object
          additionalProperties: false
          required: [state, configOwned, manifestValid, leaseValid, expiresAt]
          properties:
            state: { type: string, enum: [not-installed, installed, drifted, expired, invalid] }
            configOwned: { type: boolean }
            manifestValid: { type: boolean }
            leaseValid: { type: boolean }
            expiresAt: { type: string, format: date-time, nullable: true }
        evidence:
          type: object
          additionalProperties: false
          required: [state, eventCount, lastEvent]
          properties:
            state: { type: string, enum: [missing, verified, invalid, unavailable] }
            eventCount: { type: integer, minimum: 0 }
            lastEvent:
              type: object
              nullable: true
              additionalProperties: false
              required: [eventId, eventHash, eventType, actionId, observedAt, receiptId, receiptSha256, integrity]
              properties:
                eventId: { type: string }
                eventHash: { type: string, pattern: '^[a-f0-9]{64}$' }
                eventType: { type: string, enum: [action.requested, action.completed, action.failed, action.denied] }
                actionId: { type: string }
                observedAt: { type: string, format: date-time }
                receiptId: { type: string }
                receiptSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
                integrity: { type: string, enum: [verified] }
        repairCommands:
          type: array
          items: { type: string }
        derivedDiagnostic: { type: boolean, enum: [true] }
        recorded: { type: boolean, enum: [false] }
        proofEligible: { type: boolean, enum: [false] }
        claimBoundary: { type: string }

    HookActionLifecycle:
      type: object
      additionalProperties: false
      required: [schemaVersion, agentId, actionId, provider, status, valid, failClosed, reasonCodes, phases, evidenceEventIds, receiptIds, rawProviderPayloadStored, claimBoundary]
      properties:
        schemaVersion:
          type: string
          enum: ['2026-07-12']
        agentId:
          type: string
        actionId:
          type: string
        provider:
          type: string
          nullable: true
          enum: [claude-code, gemini-cli]
        status:
          type: string
          enum: [requested, awaiting_terminal, completed, failed, denied, steered, fail_closed]
        valid:
          type: boolean
        failClosed:
          type: boolean
        reasonCodes:
          type: array
          items: { type: string }
        phases:
          type: object
          additionalProperties: false
          required: [requested, decision, terminal]
          properties:
            requested:
              type: object
              nullable: true
              additionalProperties: false
              description: Receipt-bound provider action request phase, or null when the request is missing.
              required: [eventId, eventHash, receiptId, receiptSha256, observedAt, type]
              properties:
                eventId: { type: string }
                eventHash: { type: string, pattern: '^[a-f0-9]{64}$' }
                receiptId: { type: string }
                receiptSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
                observedAt: { type: string, format: date-time }
                type: { type: string, enum: [action.requested] }
            decision:
              type: object
              nullable: true
              additionalProperties: false
              required: [eventId, eventHash, receiptId, receiptSha256, observedAt, decision, requestedDecision, effectiveOutcome, providerMapping]
              properties:
                eventId: { type: string }
                eventHash: { type: string, pattern: '^[a-f0-9]{64}$' }
                receiptId: { type: string }
                receiptSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
                observedAt: { type: string, format: date-time }
                decision:
                  type: string
                  enum: [allow, deny, ask]
                requestedDecision:
                  type: string
                  enum: [allow, deny, ask, steer]
                effectiveOutcome:
                  type: string
                  enum: [allow, deny, ask, steer]
                providerMapping:
                  type: string
                  enum: [native, corrective_deny, fail_closed_deny]
            terminal:
              type: object
              nullable: true
              additionalProperties: false
              description: Receipt-bound provider terminal phase, or null when the current call was blocked or remains unresolved.
              required: [eventId, eventHash, receiptId, receiptSha256, observedAt, type, status]
              properties:
                eventId: { type: string }
                eventHash: { type: string, pattern: '^[a-f0-9]{64}$' }
                receiptId: { type: string }
                receiptSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
                observedAt: { type: string, format: date-time }
                type: { type: string, enum: [action.completed, action.failed, action.denied] }
                status:
                  type: string
                  nullable: true
                  enum: [success, failure, timeout, cancelled]
        evidenceEventIds:
          type: array
          items: { type: string }
        receiptIds:
          type: array
          items: { type: string }
        rawProviderPayloadStored:
          type: boolean
          enum: [false]
        claimBoundary:
          type: string

    AdapterCapabilityReceipt:
      type: object
      additionalProperties: false
      required: [receiptVersion, receiptId, issuedAt, subject, adapter, inspection, effective, verification, receiptHash, signature]
      properties:
        receiptVersion:
          type: string
          enum: [amc.adapter-capability-receipt.v1]
        receiptId:
          type: string
          pattern: '^adcap_[a-f0-9]{32}$'
        issuedAt:
          type: string
          format: date-time
        subject:
          type: object
          additionalProperties: false
          required: [agentId, adapterId]
          properties:
            agentId: { type: string }
            adapterId: { type: string }
        adapter:
          type: object
          description: Authoritative adapter identity and versioned capability declaration.
        inspection:
          type: object
          description: Runtime/version, signed configuration, and provider-hook state inspected for this subject.
        effective:
          type: object
          additionalProperties: false
          required: [events, controls]
          properties:
            events:
              type: array
              items: { type: string }
            controls:
              type: array
              items: { type: string }
        verification:
          type: object
          additionalProperties: false
          required: [status, reasons]
          properties:
            status:
              type: string
              enum: [verified, partial, fail_closed]
            reasons:
              type: array
              items: { type: string }
        receiptHash:
          type: string
          pattern: '^[a-f0-9]{64}$'
        signature:
          type: object
          description: Existing AMC auditor signature over the canonical receipt hash.

    ApprovalQuorum:
      type: object
      additionalProperties: false
      required: [required, received, status]
      properties:
        required: { type: integer, minimum: 0 }
        received: { type: integer, minimum: 0 }
        status:
          type: string
          enum: [PENDING, QUORUM_MET, DENIED, EXPIRED, CANCELLED, CONSUMED]

    ApprovalActivityFilters:
      type: object
      additionalProperties: false
      required: [query, status, actionClass, riskTier, effectiveMode, createdAfterTs, createdBeforeTs, order, limit]
      properties:
        query: { type: string, nullable: true, maxLength: 128 }
        status: { type: string, nullable: true, enum: [PENDING, QUORUM_MET, DENIED, EXPIRED, CANCELLED, CONSUMED] }
        actionClass: { type: string, nullable: true, enum: [READ_ONLY, WRITE_LOW, WRITE_HIGH, DEPLOY, SECURITY, FINANCIAL, NETWORK_EXTERNAL, DATA_EXPORT, IDENTITY] }
        riskTier: { type: string, nullable: true, enum: [low, medium, high, critical] }
        effectiveMode: { type: string, nullable: true, enum: [SIMULATE, EXECUTE] }
        createdAfterTs: { type: integer, nullable: true }
        createdBeforeTs: { type: integer, nullable: true }
        order: { type: string, enum: [newest, oldest] }
        limit: { type: integer, minimum: 1, maximum: 200 }

    ApprovalActivityIntegrity:
      type: object
      additionalProperties: false
      required: [valid, reasonCodes, scannedRequests, trustedRequests, scannedDecisions, scannedConsumptions]
      properties:
        valid: { type: boolean }
        reasonCodes: { type: array, items: { type: string } }
        scannedRequests: { type: integer, minimum: 0 }
        trustedRequests: { type: integer, minimum: 0 }
        scannedDecisions: { type: integer, minimum: 0 }
        scannedConsumptions: { type: integer, minimum: 0 }

    ApprovalInboxSummary:
      type: object
      additionalProperties: false
      required: [schemaVersion, approvalRequestId, requestDigestSha256, agentId, actionClass, riskTier, requestedMode, effectiveMode, createdTs, expiresTs, status, quorum, decisionCount, requestIntegrity, chainIntegrity, contextIntegrity, executionReady]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-11'] }
        approvalRequestId: { type: string, pattern: '^apprreq_' }
        requestDigestSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        agentId: { type: string }
        actionClass: { type: string, enum: [READ_ONLY, WRITE_LOW, WRITE_HIGH, DEPLOY, SECURITY, FINANCIAL, NETWORK_EXTERNAL, DATA_EXPORT, IDENTITY] }
        riskTier: { type: string, enum: [low, medium, high, critical] }
        requestedMode: { type: string, enum: [SIMULATE, EXECUTE] }
        effectiveMode: { type: string, enum: [SIMULATE, EXECUTE] }
        createdTs: { type: integer }
        expiresTs: { type: integer }
        status: { type: string, enum: [PENDING, QUORUM_MET, DENIED, EXPIRED, CANCELLED, CONSUMED] }
        quorum: { $ref: '#/components/schemas/ApprovalQuorum' }
        decisionCount: { type: integer, minimum: 0 }
        requestIntegrity: { type: object }
        chainIntegrity: { type: object }
        contextIntegrity: { type: object }
        executionReady: { type: boolean }

    ApprovalDeliverySummary:
      type: object
      additionalProperties: false
      required: [schemaVersion, approvalRequestId, status, reasonCode, eventName, requestDigestSha256, expiresTs, channels, queued, skipped, notificationOnly, proofEligible, evidence]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-11'] }
        approvalRequestId: { type: string }
        status: { type: string, enum: [DELIVERED, QUEUED, SKIPPED, FAILED, BLOCKED] }
        reasonCode: { type: string, nullable: true }
        eventName: { type: string, nullable: true }
        requestDigestSha256: { type: string, nullable: true }
        expiresTs: { type: integer, nullable: true }
        channels: { type: array, items: { type: object } }
        queued: { type: array, items: { type: object } }
        skipped: { type: array, items: { type: string } }
        notificationOnly: { type: boolean, enum: [true] }
        proofEligible: { type: boolean, enum: [false] }
        evidence: { type: object, nullable: true }

    ApprovalDecisionRequest:
      type: object
      additionalProperties: false
      required: [decision]
      properties:
        decision: { type: string, enum: [APPROVE_EXECUTE, APPROVE_SIMULATE, DENY] }
        mode: { type: string, enum: [SIMULATE, EXECUTE] }
        reason: { type: string, minLength: 1, maxLength: 1000 }

    OnboardingSetupDetail:
      type: object
      additionalProperties: false
      required: [schemaVersion, agentId, mode, status, createdAt, updatedAt, provider, detectedFrameworks, refs, steps, errorPresent]
      properties:
        schemaVersion: { type: string, enum: ['2026-05-22'] }
        agentId: { type: string }
        mode: { type: string, enum: [cli, studio] }
        status: { type: string, enum: [not_started, in_progress, complete, failed] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        provider: { type: string, nullable: true }
        detectedFrameworks: { type: array, items: { type: string } }
        refs:
          type: object
          additionalProperties: false
          required: [runId, reportReady, lifecycleReady, episodeReady, studioEvidenceReady]
          properties:
            runId: { type: string, nullable: true }
            reportReady: { type: boolean }
            lifecycleReady: { type: boolean }
            episodeReady: { type: boolean }
            studioEvidenceReady: { type: boolean }
        steps:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [id, label, status, summary, updatedAt]
            properties:
              id: { type: string, enum: [detect, workspace, provider, score, studio] }
              label: { type: string }
              status: { type: string, enum: [pending, running, complete, skipped, failed] }
              summary: { type: string, nullable: true }
              updatedAt: { type: string, format: date-time, nullable: true }
        errorPresent: { type: boolean }

    OnboardingActivationEvidenceRef:
      type: object
      additionalProperties: false
      required: [eventId, eventType, receiptId, receiptSha256, observedAt, source, studioPath]
      properties:
        eventId: { type: string }
        eventType: { type: string, enum: [llm_request, tool_action, audit] }
        receiptId: { type: string }
        receiptSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        observedAt: { type: string, format: date-time }
        source: { type: string, enum: [gateway, hook, hook_control, toolhub] }
        studioPath: { type: string, pattern: '^/console/evidence\?' }

    OnboardingActivationMilestone:
      type: object
      additionalProperties: false
      required: [id, label, status, summary, evidence]
      properties:
        id: { type: string, enum: [connected_agent, observed_action, control_decision, signed_proof] }
        label: { type: string }
        status: { type: string, enum: [WAITING, READY, COMPLETE, BLOCKED] }
        summary: { type: string }
        evidence:
          allOf:
            - { $ref: '#/components/schemas/OnboardingActivationEvidenceRef' }
          nullable: true

    OnboardingActivation:
      type: object
      additionalProperties: false
      required: [schemaVersion, agentId, status, progress, milestones, nextAction, integrity, claimBoundary]
      properties:
        schemaVersion: { type: string, enum: ['2026-07-11'] }
        agentId: { type: string }
        status: { type: string, enum: [NOT_STARTED, IN_PROGRESS, COMPLETE, BLOCKED] }
        progress:
          type: object
          additionalProperties: false
          required: [completed, total, percent]
          properties:
            completed: { type: integer, minimum: 0, maximum: 4 }
            total: { type: integer, enum: [4] }
            percent: { type: integer, minimum: 0, maximum: 100 }
        milestones:
          type: array
          minItems: 4
          maxItems: 4
          items: { $ref: '#/components/schemas/OnboardingActivationMilestone' }
        nextAction:
          type: object
          nullable: true
          additionalProperties: false
          required: [label, command]
          properties:
            label: { type: string }
            command: { type: string }
        integrity:
          type: object
          additionalProperties: false
          required: [valid, reasonCodes]
          properties:
            valid: { type: boolean }
            reasonCodes:
              type: array
              items:
                type: string
                enum: [ADAPTER_CONFIG_INVALID, EVIDENCE_CHAIN_INVALID, EVIDENCE_METADATA_INVALID, EVIDENCE_RECEIPT_INVALID, HOOK_AGENT_MISMATCH, HOOK_INTEGRATION_INVALID]
        claimBoundary: { type: string }

    OnboardingStatusResponse:
      type: object
      additionalProperties: false
      required: [state, activation]
      properties:
        state: { $ref: '#/components/schemas/OnboardingSetupDetail' }
        activation: { $ref: '#/components/schemas/OnboardingActivation' }

    # BEGIN GENERATED NATIVE TASK SCHEMAS
    NativeTaskError:
      type: object
      required:
        - error
      properties:
        ok:
          type: boolean
          enum:
            - false
        error:
          type: string
        code:
          type: string
    NativeTaskStart:
      type: object
      additionalProperties: false
      required:
        - clientRequestId
        - agentId
        - provider
        - tools
      properties:
        clientRequestId:
          type: string
          format: uuid
        agentId:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[a-z0-9][a-z0-9_-]*$
        provider:
          type: string
          enum:
            - stub
            - openai
            - openai-responses
            - anthropic
            - deepseek
            - gemini
            - gemini-audio
            - ollama
        model:
          type: string
          minLength: 1
          maxLength: 200
        tools:
          type: string
          enum:
            - none
            - workspace
        toolsDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
        validation:
          $ref: "#/components/schemas/NativeTaskValidationSelection"
        prompt:
          type: string
          minLength: 1
          maxLength: 16384
          description: Nonblank task text, at most 16 KiB UTF-8. Control characters other than tabs/newlines are rejected.
        input:
          $ref: "#/components/schemas/NativeTaskStructuredInput"
        maxSteps:
          type: integer
          minimum: 1
          maximum: 8
        maxTokens:
          type: integer
          minimum: 1
          maximum: 1024
      oneOf:
        - required:
            - prompt
          not:
            required:
              - input
        - required:
            - input
          not:
            required:
              - prompt
      description: Supply exactly one of prompt or ordered input. Workspace tools require the reviewed toolsDigest;
        no-tools requests must omit it. Real providers require an explicit model and an operator credential. Retry
        the identical request ID and body, including original attachment bytes, order and format; a conflicting
        reuse is refused. No input is automatically replayed.
    NativeTaskTurn:
      type: object
      additionalProperties: false
      required:
        - clientRequestId
        - expectedRevision
      properties:
        clientRequestId:
          type: string
          format: uuid
        expectedRevision:
          type: integer
          minimum: 1
          maximum: 32
        prompt:
          type: string
          minLength: 1
          maxLength: 16384
          description: Nonblank task text, at most 16 KiB UTF-8. Control characters other than tabs/newlines are rejected.
        input:
          $ref: "#/components/schemas/NativeTaskStructuredInput"
      oneOf:
        - required:
            - prompt
          not:
            required:
              - input
        - required:
            - input
          not:
            required:
              - prompt
    NativeTaskStructuredInput:
      type: object
      additionalProperties: false
      required:
        - format
        - parts
      properties:
        format:
          type: string
          enum:
            - amc-image-input@2
            - amc-audio-input@1
        parts:
          type: array
          minItems: 1
          maxItems: 256
          items:
            oneOf:
              - type: object
                additionalProperties: false
                required:
                  - type
                  - text
                properties:
                  type:
                    type: string
                    enum:
                      - text
                  text:
                    type: string
                    maxLength: 16384
              - type: object
                additionalProperties: false
                required:
                  - type
                  - mimeType
                  - data
                properties:
                  type:
                    type: string
                    enum:
                      - image
                  mimeType:
                    type: string
                    enum:
                      - image/png
                      - image/jpeg
                      - image/gif
                      - image/webp
                  data:
                    type: string
                    minLength: 1
                    maxLength: 260096
                    contentEncoding: base64
              - type: object
                additionalProperties: false
                required:
                  - type
                  - mimeType
                  - data
                properties:
                  type:
                    type: string
                    enum:
                      - audio
                  mimeType:
                    type: string
                    enum:
                      - audio/wav
                  data:
                    type: string
                    minLength: 1
                    maxLength: 260096
                    contentEncoding: base64
      description: Exact ordered text/original canonical-base64 parts; empty and adjacent text are preserved. At
        most eight images and eight audio parts, aggregate text 16 KiB UTF-8, serialized parts 260096 bytes and
        complete ACP frame 262144 bytes. Image format requires an image and forbids audio; audio format requires
        audio and literal gemini-audio. Gemini refuses GIF. No URLs, filenames, paths, annotations, transcoding or
        client commitments. Native header checks and runtime negotiation still apply; no remote model support is
        claimed.
    NativeTaskControl:
      type: object
      additionalProperties: false
      required:
        - expectedRevision
      properties:
        expectedRevision:
          type: integer
          minimum: 1
          maximum: 32
    NativeTask:
      type: object
      additionalProperties: false
      required:
        - taskId
        - sessionId
        - agentId
        - revision
        - clientRequestId
        - lastClientRequestId
        - provider
        - model
        - tools
        - toolsDigest
        - validationSelection
        - validation
        - validationOutputs
        - maxSteps
        - maxTokens
        - state
        - createdAt
        - updatedAt
        - archived
        - turnEndReason
        - error
        - verification
        - approvals
        - approvalError
        - nextCursor
        - firstCursor
        - droppedEvents
        - canResume
        - resumeBlockedReason
        - history
        - recovery
      properties:
        taskId:
          type: string
          pattern: ^[a-f0-9]{64}$
        sessionId:
          type: string
          nullable: true
        agentId:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[a-z0-9][a-z0-9_-]*$
        revision:
          type: integer
          minimum: 0
        clientRequestId:
          type: string
          format: uuid
        lastClientRequestId:
          type: string
          format: uuid
        provider:
          type: string
          enum:
            - stub
            - openai
            - openai-responses
            - anthropic
            - deepseek
            - gemini
            - gemini-audio
            - ollama
        model:
          type: string
          nullable: true
        tools:
          type: string
          enum:
            - none
            - workspace
        toolsDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
          nullable: true
        validationSelection:
          oneOf:
            - $ref: "#/components/schemas/NativeTaskValidationSelection"
            - type: object
              nullable: true
              enum:
                - null
        validation:
          $ref: "#/components/schemas/NativeTaskValidationResult"
        validationOutputs:
          type: array
          maxItems: 8
          items:
            $ref: "#/components/schemas/NativeTaskValidationOutput"
        maxSteps:
          type: integer
          minimum: 0
        maxTokens:
          type: integer
          minimum: 0
        state:
          type: string
          enum:
            - starting
            - idle
            - running
            - cancel-requested
            - releasing
            - released
            - failed
            - verifying
            - closed
        createdAt:
          type: integer
          minimum: 0
        updatedAt:
          type: integer
          minimum: 0
        archived:
          type: boolean
        turnEndReason:
          type: string
          nullable: true
        error:
          type: string
          nullable: true
        verification:
          type: string
          enum:
            - not-verified
            - workspace-key-consistency
            - externally-anchored
            - failed
          description: Evidence integrity result, separate from task success. Other open ledger writers can prevent a
            complete verification.
        approvals:
          type: array
          items:
            $ref: "#/components/schemas/NativeTaskApproval"
        approvalError:
          type: string
          nullable: true
        nextCursor:
          type: integer
          minimum: 0
        firstCursor:
          type: integer
          minimum: 0
        droppedEvents:
          type: integer
          minimum: 0
        canResume:
          type: boolean
        resumeBlockedReason:
          type: string
          nullable: true
        history:
          $ref: "#/components/schemas/NativeTaskHistory"
        recovery:
          oneOf:
            - $ref: "#/components/schemas/NativeTaskRecovery"
            - type: object
              nullable: true
              enum:
                - null
    NativeTaskRecovery:
      type: object
      additionalProperties: false
      required:
        - eligible
        - state
        - message
      properties:
        eligible:
          type: boolean
        state:
          type: string
          enum:
            - ready
            - interrupted
            - blocked
        message:
          type: string
      description: Read-only native JSONL recovery eligibility, not a writer grant. Resume rechecks original
        history, identity, settings, accounting and actual abandoned ownership under the writer mutex. An
        interrupted turn is acknowledged without replaying its effects; submit a new explicit turn. Closed or
        archived sessions remain non-resumable.
    NativeTaskHistory:
      type: object
      additionalProperties: false
      required:
        - status
        - backend
        - headEventHash
        - eventCount
        - message
      properties:
        status:
          type: string
          enum:
            - not-started
            - authenticated
            - unavailable
        backend:
          type: string
          enum:
            - sqlite
            - jsonl
            - null
          nullable: true
        headEventHash:
          type: string
          pattern: ^[a-f0-9]{64}$
          nullable: true
        eventCount:
          type: integer
          minimum: 0
        message:
          type: string
      description: Actual selected-backend session metadata status; never a private payload access grant or JSONL
        writer-resume capability. When unavailable, withhold previous transcript/validation/verifier displays.
        eventCount zero then means unknown, not verified empty history.
    NativeTaskApproval:
      type: object
      additionalProperties: false
      required:
        - approvalRequestId
        - requestDigestSha256
        - toolName
        - actionClass
        - riskTier
        - status
        - required
        - received
        - expiresTs
      properties:
        approvalRequestId:
          type: string
        requestDigestSha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        toolName:
          type: string
        actionClass:
          type: string
        riskTier:
          type: string
        status:
          type: string
        required:
          type: integer
          minimum: 0
        received:
          type: integer
          minimum: 0
        expiresTs:
          type: integer
          minimum: 0
    NativeTaskValidationSelection:
      type: object
      additionalProperties: false
      required:
        - configSha256
        - checkIds
      properties:
        configSha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        checkIds:
          type: array
          minItems: 1
          maxItems: 8
          uniqueItems: true
          items:
            type: string
            pattern: ^[a-zA-Z0-9_-]{1,64}$
      description: Creation-only selection from the operator's public check catalogue. The digest and ordered IDs
        stay pinned across follow-up and resume; no commands, paths or grants are accepted.
    NativeTaskValidationResult:
      type: object
      additionalProperties: false
      required:
        - status
        - turn
        - configSha256
        - checks
      properties:
        status:
          type: string
          enum:
            - not-requested
            - pending
            - passed
            - failed
            - unavailable
        turn:
          type: integer
          minimum: 0
          nullable: true
        configSha256:
          type: string
          pattern: ^[a-f0-9]{64}$
          nullable: true
        checks:
          type: array
          maxItems: 8
          items:
            type: object
            additionalProperties: false
            required:
              - id
              - title
              - status
              - callId
              - exitCode
              - timedOut
              - reason
              - outputEventId
            properties:
              id:
                type: string
              title:
                type: string
              status:
                type: string
                enum:
                  - pending
                  - passed
                  - failed
                  - unavailable
              callId:
                type: string
                nullable: true
              exitCode:
                type: integer
                nullable: true
              timedOut:
                type: boolean
              reason:
                type: string
                nullable: true
              outputEventId:
                type: string
                nullable: true
    NativeTaskValidationConfiguration:
      type: object
      additionalProperties: false
      required:
        - ready
        - configSha256
        - checks
        - message
      properties:
        ready:
          type: boolean
        configSha256:
          type: string
          pattern: ^[a-f0-9]{64}$
          nullable: true
        checks:
          type: array
          maxItems: 8
          items:
            type: object
            additionalProperties: false
            required:
              - id
              - title
            properties:
              id:
                type: string
              title:
                type: string
        message:
          type: string
    NativeTaskValidationOutput:
      type: object
      additionalProperties: false
      required:
        - checkId
        - outputEventId
        - payloadSha256
        - status
        - text
        - truncated
        - redacted
        - bytes
      properties:
        checkId:
          type: string
        outputEventId:
          type: string
        payloadSha256:
          type: string
          pattern: ^[a-f0-9]{64}$
        status:
          type: string
          enum:
            - available
            - unavailable
            - pruned
        text:
          type: string
          nullable: true
        truncated:
          type: boolean
        redacted:
          type: boolean
        bytes:
          type: integer
          minimum: 0
          nullable: true
      description: Text from the exact authenticated check-result payload after its complete bytes match
        payloadSha256. The display is redacted and capped at 16 KiB; payloadSha256 describes the original bytes,
        not transformed display text. Reads over 2 MiB are withheld.
    NativeTaskEvent:
      type: object
      additionalProperties: false
      required:
        - cursor
        - kind
        - text
        - evidence
      properties:
        cursor:
          type: integer
          minimum: 0
        kind:
          type: string
          enum:
            - user
            - assistant
            - tool
            - tool-update
            - plan
        text:
          type: string
        toolCallId:
          type: string
        status:
          type: string
        evidence:
          type: string
          enum:
            - committed
        attachment:
          type: object
          additionalProperties: false
          required:
            - type
            - mimeType
            - byteLength
            - sha256
          properties:
            type:
              type: string
              enum:
                - image
                - audio
            mimeType:
              type: string
            byteLength:
              type: integer
              minimum: 0
            sha256:
              type: string
              pattern: ^[a-f0-9]{64}$
    NativeTaskInputCapabilities:
      type: object
      additionalProperties: false
      required:
        - formats
        - imageMimeTypes
        - audioMimeTypes
        - maxParts
        - maxImages
        - maxAudios
        - maxTextBytes
        - maxSerializedPartsBytes
        - maxPromptFrameBytes
        - modelSupport
      properties:
        formats:
          type: array
          items:
            type: string
            enum:
              - text
              - amc-image-input@2
              - amc-audio-input@1
        imageMimeTypes:
          type: array
          items:
            type: string
        audioMimeTypes:
          type: array
          items:
            type: string
        maxParts:
          type: integer
          minimum: 0
        maxImages:
          type: integer
          minimum: 0
        maxAudios:
          type: integer
          minimum: 0
        maxTextBytes:
          type: integer
          minimum: 0
        maxSerializedPartsBytes:
          type: integer
          minimum: 0
        maxPromptFrameBytes:
          type: integer
          minimum: 0
        modelSupport:
          type: string
          enum:
            - not-probed
      description: Native input bindings and local admission bounds, not live model qualification. Dispatch
        separately requires the running client's exact input contract.
    NativeTaskToolScope:
      type: object
      additionalProperties: false
      required:
        - ready
        - digest
        - approvalRequired
        - tools
        - message
      properties:
        ready:
          type: boolean
        digest:
          type: string
          pattern: ^[a-f0-9]{64}$
          nullable: true
        approvalRequired:
          type: boolean
          enum:
            - true
        tools:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - name
              - actionClass
              - paths
              - deniedPaths
              - hosts
              - binaries
              - nativeSandbox
            properties:
              name:
                type: string
              actionClass:
                type: string
              paths:
                type: array
                items:
                  type: string
              deniedPaths:
                type: array
                items:
                  type: string
              hosts:
                type: array
                items:
                  type: string
              binaries:
                type: array
                items:
                  type: string
              nativeSandbox:
                type: object
                additionalProperties: false
                required:
                  - kind
                  - writableDirectories
                properties:
                  kind:
                    type: string
                    enum:
                      - linux-bwrap
                  writableDirectories:
                    type: array
                    items:
                      type: string
                nullable: true
        message:
          type: string
    NativeTaskOptions:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - agentId
        - demo
        - providers
        - scope
        - validation
        - limits
        - boundary
        - nativeCsrfToken
        - executionBlocked
      properties:
        schemaVersion:
          type: string
          enum:
            - 2026-09-08
        agentId:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[a-z0-9][a-z0-9_-]*$
        demo:
          type: boolean
        providers:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - id
              - local
              - model
              - credential
            properties:
              id:
                type: string
                enum:
                  - stub
                  - openai
                  - openai-responses
                  - anthropic
                  - deepseek
                  - gemini
                  - gemini-audio
                  - ollama
              local:
                type: boolean
              model:
                type: string
                enum:
                  - fixed
                  - required
              credential:
                type: object
                additionalProperties: false
                required:
                  - ref
                  - configured
                  - source
                properties:
                  ref:
                    type: string
                  configured:
                    type: boolean
                  source:
                    type: string
                    enum:
                      - env
                      - file
                      - null
                    nullable: true
                nullable: true
              input:
                $ref: "#/components/schemas/NativeTaskInputCapabilities"
        scope:
          $ref: "#/components/schemas/NativeTaskToolScope"
        validation:
          $ref: "#/components/schemas/NativeTaskValidationConfiguration"
        limits:
          type: object
          additionalProperties: false
          required:
            - maxActive
            - maxSteps
            - maxTokens
            - turnTimeoutMs
            - idleTimeoutMs
            - lifetimeMs
            - maxEvents
            - maxEventBytes
            - maxPromptBytes
          properties:
            maxActive:
              type: integer
              minimum: 0
            maxSteps:
              type: integer
              minimum: 0
            maxTokens:
              type: integer
              minimum: 0
            turnTimeoutMs:
              type: integer
              minimum: 0
            idleTimeoutMs:
              type: integer
              minimum: 0
            lifetimeMs:
              type: integer
              minimum: 0
            maxEvents:
              type: integer
              minimum: 0
            maxEventBytes:
              type: integer
              minimum: 0
            maxPromptBytes:
              type: integer
              minimum: 0
        boundary:
          type: string
        nativeCsrfToken:
          type: string
          nullable: true
        executionBlocked:
          type: boolean
    NativeTaskResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - data
      properties:
        ok:
          type: boolean
          enum:
            - true
        data:
          $ref: "#/components/schemas/NativeTask"
    NativeTaskOptionsResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - data
      properties:
        ok:
          type: boolean
          enum:
            - true
        data:
          $ref: "#/components/schemas/NativeTaskOptions"
    NativeTaskListResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - data
      properties:
        ok:
          type: boolean
          enum:
            - true
        data:
          type: object
          additionalProperties: false
          required:
            - tasks
          properties:
            tasks:
              type: array
              items:
                $ref: "#/components/schemas/NativeTask"
    NativeTaskPollResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - data
      properties:
        ok:
          type: boolean
          enum:
            - true
        data:
          type: object
          additionalProperties: false
          required:
            - task
            - events
            - truncated
          properties:
            task:
              $ref: "#/components/schemas/NativeTask"
            events:
              type: array
              items:
                $ref: "#/components/schemas/NativeTaskEvent"
            truncated:
              type: boolean
    # END GENERATED NATIVE TASK SCHEMAS

tags:
  - name: health
    description: Health and readiness checks
  - name: score
    description: Scoring, diagnostics, quickscore, and session-based assessment
  - name: fleet
    description: Fleet and agent management
  - name: governor
    description: Governor, oversight, and autonomy mode
  - name: compliance
    description: Compliance frameworks, policy packs, waivers, and regulatory scoring
  - name: evidence
    description: Evidence lifecycle — ingest, list, gaps, bundles, attestation
  - name: proof
    description: Domain Proof Lane — source-to-rule correctness checks with amcproof artifacts
  - name: imports
    description: Framework-neutral importers for traces, runs, graphs, configs, memory, evals, and benchmarks
  - name: strategy
    description: Inference strategy comparison, route receipts, and rollback
  - name: fixer
    description: Fixer RCA reports, regression tests, and governed Enforce proposals
  - name: crypto
    description: Notary, certificates, Merkle transparency, receipts chain
  - name: drift
    description: Drift detection, freeze management, and alerts
  - name: enforce
    description: Policy firewall and action evaluation
  - name: export
    description: Export, badge generation, and attestation
  - name: canary
    description: Canary deployments — policy canary, micro-canary, policy-mode
  - name: ci
    description: CI/CD gate — init, steps, gate evaluation, policy signing
  - name: config
    description: Runtime config, logs, doctor, version, and status
  - name: gateway
    description: Gateway/LLM proxy — config, init, bind, sign, verify, providers
  - name: firewall
    description: Runtime Firewall decisions, policy mode, event log, and SIEM export
  - name: runtime
    description: Connected-agent runtime run state and redacted event streams
  - name: identity
    description: Identity, SCIM tokens, OIDC/SAML providers, group mapping
  - name: adapters
    description: Adapter management — init, verify, list, detect, configure, and portable signed capability receipts
  - name: assurance
    description: Assurance packs — list, run, cert issue/verify, scheduler, waivers, false-positive tracking
  - name: benchmark
    description: Benchmark import/export and statistics
  - name: bom
    description: BOM generation, signing, verification, SBOM, and bundles
  - name: incidents
    description: Incident creation, listing, and state transitions
  - name: memory
    description: Memory maturity, correction memory, governed reasoning memory, lessons, advisories
  - name: metrics
    description: Metrics status, SLO, and failure-risk indices
  - name: security
    description: ATO detection, secret blinding, taint tracking, threat intel, injection detection, insider risk
  - name: shield
    description: Shield — skill scan, injection detection, input sanitization
  - name: vault
    description: Vault — secrets, DLP scan, key management, redaction, classification
  - name: tools
    description: ToolHub, guardrails, and plugin management
  - name: watch
    description: Watch/observability — guard, attest, safety test, explainability, oversight
  - name: observe
    description: Observe CLI parity — timelines and anomaly read APIs
  - name: workflow
    description: Work orders, execution tickets, and lifecycle management
  - name: sandbox
    description: Hardened Docker sandbox execution
  - name: product
    description: Batch processor and portal
  - name: value
    description: Value realization and KPI ingestion
  - name: passport
    description: Agent passport — public profile, verification, revocation
  - name: timeline
    description: Agent timeline data
  - name: agentTimeline
    description: Agent timeline events
  - name: hooks
    description: Lease-scoped provider action observation and explicit loopback control
  - name: approvals
    description: Signed quorum approvals and privacy-safe lifecycle delivery
  - name: onboarding
    description: Read-only first-run activation outcomes backed by signed runtime evidence

paths:
  # ── Outcome-based activation ──────────────────────────────────
  /onboarding/status:
    get:
      tags: [onboarding, watch, enforce]
      summary: Read setup detail and verified first-run activation outcomes
      description: Signed connection configuration can report READY, but only verified agent-bound runtime receipts complete activation milestones. Inspection creates no traffic, lease, evidence, or onboarding record.
      servers:
        - url: http://localhost:3000
          description: Local AMC Studio instance
        - url: https://{host}
          description: Self-hosted AMC Studio root
          variables:
            host: { default: amc.example.com }
      security:
        - amcSessionCookie: []
        - amcAdminToken: []
        - leaseToken: []
      parameters:
        - { name: agentId, in: query, required: false, schema: { type: string } }
      responses:
        '200':
          description: Existing setup state and read-only four-milestone activation projection
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OnboardingStatusResponse' }
        '400': { description: Invalid agent ID }
        '401': { description: Unauthorized }
        '403': { description: Agent scope does not include the requested agent }

  # ── Canonical approval inbox ──────────────────────────────────
  /approvals/requests:
    get:
      tags: [approvals, enforce]
      summary: Search canonical signed approval activity
      description: Audits the complete signed request, decision, consumption, and detached-signature inventory before applying privacy-safe filters. An untrusted inventory returns no rows. Only stable request IDs are searched; tool names, intent/work-order IDs, reviewer identities, reasons, commands, MCP servers, prompts, payloads, credentials, Vault refs, tokens, local paths, and destination URLs are omitted.
      servers:
        - url: http://localhost:3000
          description: Local AMC Studio instance
        - url: https://{host}
          description: Self-hosted AMC Studio root
          variables:
            host: { default: amc.example.com }
      parameters:
        - { name: agentId, in: query, required: false, schema: { type: string } }
        - { name: query, in: query, required: false, description: Case-insensitive stable request-ID substring, schema: { type: string, maxLength: 128, pattern: '^[A-Za-z0-9_-]+$' } }
        - { name: status, in: query, required: false, schema: { type: string, enum: [PENDING, QUORUM_MET, DENIED, EXPIRED, CANCELLED, CONSUMED] } }
        - { name: actionClass, in: query, required: false, schema: { type: string, enum: [READ_ONLY, WRITE_LOW, WRITE_HIGH, DEPLOY, SECURITY, FINANCIAL, NETWORK_EXTERNAL, DATA_EXPORT, IDENTITY] } }
        - { name: riskTier, in: query, required: false, schema: { type: string, enum: [low, medium, high, critical] } }
        - { name: effectiveMode, in: query, required: false, schema: { type: string, enum: [SIMULATE, EXECUTE] } }
        - { name: createdAfter, in: query, required: false, description: Inclusive RFC3339 or epoch-millisecond lower bound, schema: { type: string } }
        - { name: createdBefore, in: query, required: false, description: Inclusive RFC3339 or epoch-millisecond upper bound, schema: { type: string } }
        - { name: order, in: query, required: false, schema: { type: string, enum: [newest, oldest], default: newest } }
        - { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
      responses:
        '200':
          description: Fail-closed derived approval activity view
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [schemaVersion, agentId, filters, integrity, totalMatched, returned, truncated, requests, derivedView, recorded, proofEligible, claimBoundary]
                properties:
                  schemaVersion: { type: string, enum: ['2026-07-13'] }
                  agentId: { type: string }
                  filters: { $ref: '#/components/schemas/ApprovalActivityFilters' }
                  integrity: { $ref: '#/components/schemas/ApprovalActivityIntegrity' }
                  totalMatched: { type: integer, minimum: 0 }
                  returned: { type: integer, minimum: 0 }
                  truncated: { type: boolean }
                  requests: { type: array, items: { $ref: '#/components/schemas/ApprovalInboxSummary' } }
                  derivedView: { type: boolean, enum: [true] }
                  recorded: { type: boolean, enum: [false] }
                  proofEligible: { type: boolean, enum: [false] }
                  claimBoundary: { type: string }
        '400': { description: Invalid approval activity filters }
        '401': { description: Unauthorized }

  /approvals/requests/{id}:
    get:
      tags: [approvals, enforce]
      summary: Read signed approval detail for authenticated review
      servers:
        - url: http://localhost:3000
          description: Local AMC Studio instance
        - url: https://{host}
          description: Self-hosted AMC Studio root
          variables:
            host: { default: amc.example.com }
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Signed request, decisions, quorum, integrity, and execution-readiness detail }
        '401': { description: Unauthorized }
        '404': { description: Approval request not found }

  /approvals/requests/{id}/decide:
    post:
      tags: [approvals, enforce]
      summary: Record one signed approval decision
      servers:
        - url: http://localhost:3000
          description: Local AMC Studio instance
        - url: https://{host}
          description: Self-hosted AMC Studio root
          variables:
            host: { default: amc.example.com }
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
        # BEGIN GENERATED NATIVE TASK APPROVAL DECIDE HEADERS
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
        # END GENERATED NATIVE TASK APPROVAL DECIDE HEADERS
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ApprovalDecisionRequest' }
      responses:
        '200':
          description: Decision and bounded non-authoritative delivery summary
        '400': { description: Invalid decision }
        '401': { description: Unauthorized }
        '403': { description: 'Reviewer role, browser proof, demo or read-only policy refused the decision' }
        '409': { description: Request is no longer pending }

  /approvals/requests/{id}/cancel:
    post:
      tags: [approvals, enforce]
      summary: Cancel one pending approval request
      servers:
        - url: http://localhost:3000
          description: Local AMC Studio instance
        - url: https://{host}
          description: Self-hosted AMC Studio root
          variables:
            host: { default: amc.example.com }
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
        # BEGIN GENERATED NATIVE TASK APPROVAL CANCEL HEADERS
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
        # END GENERATED NATIVE TASK APPROVAL CANCEL HEADERS
      responses:
        '200': { description: Cancelled request and bounded delivery summary }
        '401': { description: Unauthorized }
        '403': { description: 'Owner role, browser proof, demo or read-only policy refused cancellation' }
        '404': { description: Approval request not found }
        '409': { description: Request is no longer pending }

  # ── Provider-neutral hook observation ─────────────────────────
  /bridge/hooks/aep/0.1/events:
    post:
      tags: [hooks, watch]
      summary: Observe a pinned provider-neutral action event
      description: |
        Accepts AMC's strict observed subset of four AEP 0.1 action events pinned to
        commit 2583cff9380f8f0a459d52c7112b6105c46496ed. AMC does not claim AEP conformance,
        does not retain the raw body, and does not return a control decision.
      servers:
        - url: http://127.0.0.1:3212
          description: Local AMC Bridge
        - url: https://{host}
          description: Self-hosted AMC Bridge
          variables:
            host:
              default: amc.example.com
      security:
        - leaseToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObservedAepActionEvent'
      responses:
        '200':
          description: Previously observed byte-identical event and original signed receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservedHookReceipt'
        '201':
          description: Observed event and signed receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservedHookReceipt'
        '400': { description: Malformed or unsupported observed event }
        '401': { description: Missing or invalid lease }
        '403': { description: Lease lacks hook scope or route }
        '409': { description: Source event ID conflicts with previously observed bytes }
        '413': { description: Payload exceeds 256 KiB }
        '422': { description: Source timestamp is stale or too far in the future }
        '429': { description: Signed lease request budget exceeded }
        '503': { description: Hook quota or evidence ledger unavailable }

  /bridge/hooks/aep/0.1/correlation:
    post:
      tags: [hooks, watch]
      summary: Resolve one unmatched privacy-safe hook request correlation
      description: |
        Internal managed-hook lookup for providers without a stable tool-call ID. Accepts only
        provider and a SHA-256 correlation digest. Zero or multiple unmatched requests fail closed;
        raw provider input is neither accepted nor retained.
      security:
        - leaseToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [provider, correlationSha256]
              properties:
                provider:
                  type: string
                  enum: [claude-code, gemini-cli]
                correlationSha256:
                  type: string
                  pattern: '^[a-f0-9]{64}$'
      responses:
        '200': { description: Exactly one unmatched request resolved }
        '400': { description: Malformed correlation request }
        '401': { description: Missing or invalid lease }
        '403': { description: Lease lacks hook scope or route }
        '409': { description: No unique unmatched request exists }
        '429': { description: Signed lease request budget exceeded }
        '503': { description: Evidence integrity verification unavailable }

  # ── Provider-native signed hook control ───────────────────────
  /bridge/hooks/control/v1:
    post:
      tags: [hooks, enforce]
      summary: Return a provider-native signed pre-tool control response
      description: |
        Loopback-only AMC control route for an explicitly installed control hook. Raw provider
        input is evaluated in memory and not retained. Existing signed ToolHub, Action Policy,
        Approval Policy, budget, freeze, maturity, and assurance state remains authoritative.
        Supported shell input receives a compound-command blast-radius review across every
        bounded segment, and the most restrictive outcome determines the response. Unsupported
        expansion, malformed syntax, excess bounds, or untrusted authority fails closed before
        partial policy output. The exact provider-native response and privacy-safe review are
        bound to a signed guard_check receipt; the raw command and argument values are not retained.
      servers:
        - url: http://127.0.0.1:3212
          description: Local AMC Bridge only
      security:
        - leaseToken: []
      parameters:
        - in: header
          name: x-amc-hook-provider
          required: true
          schema:
            type: string
            enum: [claude-code, gemini-cli]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            description: Native provider PreToolUse or BeforeTool input. Evaluated transiently and never retained.
      responses:
        '200': { description: Previously evaluated byte-identical action and original signed response }
        '201': { description: Provider-native decision and signed receipt }
        '400': { description: Malformed, ambiguous, or unsupported provider input }
        '401': { description: Missing or invalid lease }
        '403': { description: Non-loopback request or lease lacks hook:control }
        '409': { description: Stable action ID conflicts with different input bytes }
        '413': { description: Payload exceeds 256 KiB }
        '429': { description: Signed lease request budget exceeded }
        '503': { description: Control evaluation or signed receipt unavailable }

  # ── Health ─────────────────────────────────────────────────────
  /v1/health:
    get:
      tags: [health]
      summary: Health check
      description: Returns service health, version, uptime, and database status.
      security: []
      responses:
        '200':
          description: Health payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok, degraded]
                  version:
                    type: string
                  uptime:
                    type: number
                  dbStatus:
                    type: string

  # ── Domain Proof Lane ──────────────────────────────────────────
  /v1/proof/status:
    get:
      tags: [proof]
      summary: Domain Proof Lane status
      description: Returns supported proof classes, correctness statuses, supported domains, and the non-claim boundary for source-to-rule proof checks.
      responses:
        '200':
          description: Domain Proof Lane status
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DomainProofStatus'

  /v1/proof/check:
    post:
      tags: [proof]
      summary: Run source-to-rule proof check
      description: Checks inline manifest and input objects and returns a fail-closed amcproof artifact without reading or writing arbitrary server paths. Unsupported correctness never raises the AMC maturity score. Built-in fixture path strings remain temporarily available as a deprecated compatibility mode.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainProofCheckRequest'
      responses:
        '200':
          description: Domain proof check result, artifact, and request mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Invalid input, rejected legacy path, prohibited output-file request, or failed proof check

  # ── Score ──────────────────────────────────────────────────────
  /v1/score/status:
    get:
      tags: [score]
      summary: Score module status
      responses:
        '200':
          description: Status and active session count

  /v1/score/question-sets:
    get:
      tags: [score]
      summary: List supported assessment question sets
      description: Returns the default question set and the explicit lifecycle-expanded set with surface/layer mappings.
      responses:
        '200':
          description: Question set metadata

  /v1/score/run:
    post:
      tags: [score]
      summary: Run full diagnostic
      description: Trigger a full diagnostic run (CLI equivalent of `amc run`). Defaults to the current default question set unless `questionSetVersion` is explicitly set to `amc-lifecycle-2026-v1` or `lifecycle`.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                window:
                  type: string
                  default: '14d'
                targetName:
                  type: string
                claimMode:
                  type: string
                  enum: [auto, owner, harness]
                questionSetVersion:
                  type: string
                  enum: [amc-legacy-240-v1, amc-lifecycle-2026-v1, legacy, lifecycle]
                applyIndustryPackWeights:
                  type: boolean
                  description: Applies Industry Pack weighting only when the workspace has an active Industry Packs entitlement.
      responses:
        '200':
          description: Diagnostic report with separate artifact validity and evidence readiness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticReportResponse'

  /v1/score/quickscore:
    post:
      tags: [score]
      summary: Rapid 5-question quickscore
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [answers]
              properties:
                answers:
                  type: object
                  additionalProperties:
                    type: integer
      responses:
        '200':
          description: Rapid score result

  /v1/score/quickscore/questions:
    get:
      tags: [score]
      summary: Get rapid quickscore questions
      responses:
        '200':
          description: List of 5 rapid questions

  /v1/score/quick:
    post:
      tags: [score]
      summary: Tiered quick score
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [answers]
              properties:
                answers:
                  type: object
                  additionalProperties:
                    type: integer
                tier:
                  type: string
                  enum: [quick, standard, deep]
      responses:
        '200':
          description: Quick score result

  /v1/score/quick/questions:
    get:
      tags: [score]
      summary: Get questions for a tier
      parameters:
        - name: tier
          in: query
          schema:
            type: string
            enum: [quick, standard, deep]
      responses:
        '200':
          description: Questions for tier

  /v1/score/latest:
    get:
      tags: [score]
      summary: Get latest run report
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Latest run report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticReportResponse'

  /v1/score/history:
    get:
      tags: [score]
      summary: List run history from ledger
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Run history

  /v1/score/compare:
    get:
      tags: [score]
      summary: Compare two runs (GET)
      parameters:
        - name: runA
          in: query
          required: true
          schema:
            type: string
        - name: runB
          in: query
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Comparison result
    post:
      tags: [score]
      summary: Compare two runs (POST)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runA, runB]
              properties:
                runA:
                  type: string
                runB:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Comparison result

  /v1/score/formal-spec:
    post:
      tags: [score]
      summary: Full formal-spec diagnostic score
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                window:
                  type: string
      responses:
        '200':
          description: Full diagnostic result

  /v1/score/adversarial:
    post:
      tags: [score]
      summary: Test gaming resistance
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
      responses:
        '200':
          description: Adversarial test result

  /v1/score/runs:
    get:
      tags: [score]
      summary: List all runs for agent
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Run ID list

  /v1/score/run/{runId}:
    get:
      tags: [score]
      summary: Get specific run report
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Run report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticReportResponse'

  /v1/score/report/{runId}:
    get:
      tags: [score]
      summary: Generate report for a run
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Report (JSON or Markdown)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticReportResponse'
            text/markdown:
              schema:
                type: string

  /v1/score/report:
    get:
      tags: [score]
      summary: Generate report (query param)
      parameters:
        - name: runId
          in: query
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticReportResponse'
            text/markdown:
              schema:
                type: string

  /v1/score/session:
    post:
      tags: [score]
      summary: Create interactive scoring session
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId]
              properties:
                agentId:
                  type: string
      responses:
        '201':
          description: Session created

  /v1/score/question/{sessionId}:
    get:
      tags: [score]
      summary: Get next question for session
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Next question or completion status

  /v1/score/answer:
    post:
      tags: [score]
      summary: Record answer for session
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [sessionId, questionId, value]
              properties:
                sessionId:
                  type: string
                questionId:
                  type: string
                value:
                  type: integer
                notes:
                  type: string
      responses:
        '200':
          description: Answer recorded

  /v1/score/result/{sessionId}:
    get:
      tags: [score]
      summary: Get session result
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session score result

  # ── Fleet ──────────────────────────────────────────────────────
  /v1/fleet/health:
    get:
      tags: [fleet]
      summary: Fleet health dashboard
      responses:
        '200':
          description: Fleet health overview

  /v1/fleet/agents:
    get:
      tags: [fleet]
      summary: List all agents
      responses:
        '200':
          description: Agent list
    post:
      tags: [fleet]
      summary: Add agent
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId]
              properties:
                agentId:
                  type: string
                agentName:
                  type: string
                role:
                  type: string
                domain:
                  type: string
                templateId:
                  type: string
                riskTier:
                  type: string
                  enum: [low, med, high, critical]
      responses:
        '201':
          description: Agent created

  /v1/fleet/agents/{agentId}:
    get:
      tags: [fleet]
      summary: Get agent config
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Agent configuration
    delete:
      tags: [fleet]
      summary: Remove agent
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Agent removed

  /v1/fleet/report:
    get:
      tags: [fleet]
      summary: Fleet maturity report
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
        - name: window
          in: query
          schema:
            type: string
            default: '30d'
      responses:
        '200':
          description: Fleet report

  /v1/fleet/graph:
    get:
      tags: [fleet]
      summary: Inspect latest typed multi-agent graph
      description: Returns the latest graph, canonical digest, node/edge counts, and validation findings used by fleet scoring and lifecycle evidence.
      responses:
        '200':
          description: Typed graph inspection payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  graph:
                    $ref: '#/components/schemas/TypedMultiAgentGraph'
                  ref:
                    $ref: '#/components/schemas/TypedMultiAgentGraphRef'
    post:
      tags: [fleet]
      summary: Write latest typed multi-agent graph
      description: Stores a graph under `.amc/fleet/typed-graphs/`, computes its canonical digest, and returns actionable validation findings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [graph]
              properties:
                graph:
                  $ref: '#/components/schemas/TypedMultiAgentGraph'
      responses:
        '201':
          description: Typed graph written

  /v1/fleet/graph/validate:
    get:
      tags: [fleet]
      summary: Validate latest typed multi-agent graph
      description: Checks node contracts, handoff contracts, unsafe permissions, circular dependencies, and fan-out limits before fleet assessment.
      responses:
        '200':
          description: Typed graph validation payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  graph:
                    $ref: '#/components/schemas/TypedMultiAgentGraph'
                  ref:
                    $ref: '#/components/schemas/TypedMultiAgentGraphRef'
                  validation:
                    $ref: '#/components/schemas/TypedGraphValidation'

  /v1/fleet/lifecycle:
    get:
      tags: [fleet]
      summary: List parent fleet lifecycle artifacts
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: redacted
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Fleet lifecycle artifact list

  /v1/fleet/lifecycle/{selector}:
    get:
      tags: [fleet]
      summary: Inspect a parent fleet lifecycle artifact
      parameters:
        - name: selector
          in: path
          required: true
          schema:
            type: string
        - name: redacted
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Fleet lifecycle artifact

  /v1/fleet/init:
    post:
      tags: [fleet]
      summary: Initialize fleet
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                org:
                  type: string
      responses:
        '200':
          description: Fleet initialized

  /v1/fleet/config:
    get:
      tags: [fleet]
      summary: Fleet configuration
      responses:
        '200':
          description: Fleet config

  /v1/fleet/freeze/status:
    get:
      tags: [fleet]
      summary: Execution freeze status
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Freeze status

  /v1/fleet/freeze/lift:
    post:
      tags: [fleet]
      summary: Lift execution freeze
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId, incidentId, reason]
              properties:
                agentId:
                  type: string
                incidentId:
                  type: string
                reason:
                  type: string
      responses:
        '200':
          description: Freeze lifted

  # ── Governor ───────────────────────────────────────────────────
  /v1/governor/check:
    post:
      tags: [governor]
      summary: Evaluate action permission
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [action, risk, mode]
              properties:
                action:
                  type: string
                risk:
                  type: string
                mode:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Governor decision

  /v1/governor/explain:
    post:
      tags: [governor]
      summary: Explain policy for action class
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [action]
              properties:
                action:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Explanation

  /v1/governor/report:
    get:
      tags: [governor]
      summary: Governor matrix report
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Governor report

  /v1/governor/policy/init:
    post:
      tags: [governor]
      summary: Initialize action policy
      responses:
        '200':
          description: Policy initialized

  /v1/governor/policy/verify:
    post:
      tags: [governor]
      summary: Verify action policy signature
      responses:
        '200':
          description: Verification result

  /v1/oversight/assess:
    get:
      tags: [governor]
      summary: Assess human oversight quality
      parameters:
        - name: agentId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Oversight assessment

  /v1/mode:
    get:
      tags: [governor]
      summary: Get current mode
      responses:
        '200':
          description: Current mode (owner/agent)
    put:
      tags: [governor]
      summary: Set mode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [mode]
              properties:
                mode:
                  type: string
                  enum: [owner, agent]
      responses:
        '200':
          description: Mode set

  # ── Compliance ─────────────────────────────────────────────────
  /v1/compliance/init:
    post:
      tags: [compliance]
      summary: Create and sign compliance maps
      responses:
        '201':
          description: Compliance maps initialized

  /v1/compliance/verify:
    get:
      tags: [compliance]
      summary: Verify compliance maps signature
      responses:
        '200':
          description: Verification result

  /v1/compliance/report:
    post:
      tags: [compliance]
      summary: Generate evidence-linked compliance report
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [framework, window, outFile]
              properties:
                framework:
                  type: string
                window:
                  type: string
                outFile:
                  type: string
                format:
                  type: string
                agentId:
                  type: string
      responses:
        '201':
          description: Report generated

  /v1/compliance/fleet:
    post:
      tags: [compliance]
      summary: Fleet compliance summary
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [framework, window]
              properties:
                framework:
                  type: string
                window:
                  type: string
      responses:
        '200':
          description: Fleet compliance report

  /v1/compliance/diff:
    post:
      tags: [compliance]
      summary: Diff two compliance report JSON files
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [reportA, reportB]
              properties:
                reportA:
                  type: string
                reportB:
                  type: string
      responses:
        '200':
          description: Diff result

  /v1/enforce/resources/status:
    get:
      tags: [enforce]
      summary: Read signed active, previous, rollback, drift, and integrity state
      parameters:
        - name: agentId
          in: query
          schema: { type: string, default: default }
      responses:
        '200':
          description: Bounded signed resource lifecycle status
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EnforceResourceLifecycleStatusResponse' }
        '401': { description: Unauthorized }

  /v1/enforce/resources/verify:
    get:
      tags: [enforce]
      summary: Verify a canonical signed resource manifest against current state
      parameters:
        - name: agentId
          in: query
          schema: { type: string, default: default }
        - name: manifestPath
          in: query
          description: Workspace-relative canonical manifest reference
          schema: { type: string }
      responses:
        '200':
          description: Manifest and workspace state match
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EnforceResourceVerificationResponse' }
        '401': { description: Unauthorized }
        '409': { description: Manifest integrity failed or drift was detected }

  /v1/enforce/resources/apply:
    post:
      tags: [enforce]
      summary: Preview or activate current resource state; dry-run by default
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EnforceResourceApplyRequest' }
      responses:
        '200': { description: Activation preview }
        '201': { description: Signed resource version activated }
        '400': { description: Exact activation manifest confirmation required }
        '401': { description: Unauthorized }
        '403': { description: Owner role required }
        '409': { description: Resource integrity or lifecycle gate failed }

  /v1/enforce/resources/rollback:
    post:
      tags: [enforce]
      summary: Preview or activate a canonical signed rollback target; dry-run by default
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EnforceResourceRollbackRequest' }
      responses:
        '200': { description: Rollback preview or signed rollback result }
        '400': { description: Exact rollback manifest confirmation required }
        '401': { description: Unauthorized }
        '403': { description: Owner role required }
        '409': { description: Manifest, snapshot, resource digest, or race integrity failed }

  /v1/policy/controls:
    get:
      tags: [policy, enforce]
      summary: Project existing signed controls as Scope, When, Then, and Status
      responses:
        '200':
          description: Read-only verified control projection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlProjectionResponse'
        '401':
          description: Unauthorized
        '500':
          description: Control projection failed

  /v1/policy/action/evidence-logic:
    get:
      tags: [policy, enforce]
      summary: Inspect declared Action Policy evidence gates and effective logic
      parameters:
        - name: actionClass
          in: query
          required: true
          schema: { $ref: '#/components/schemas/ActionClass' }
      responses:
        '200':
          description: Read-only evidence-logic inspection
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ActionEvidenceLogicInspectionResponse' }
        '400': { description: Unknown Action Policy rule }
        '401': { description: Unauthorized }
        '409': { description: Current signed Action Policy baseline is untrusted or changed }
        '500': { description: Evidence-logic inspection failed }

  /v1/policy/action/evidence-logic/compile:
    post:
      tags: [policy, enforce]
      summary: Compile bounded Action Policy evidence logic without writing
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ActionEvidenceLogicCompileRequest' }
      responses:
        '200':
          description: Deterministic read-only evidence-logic preview
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ActionEvidenceLogicCompilationResponse' }
        '400': { description: Invalid tree, gate coverage, or Action Policy rule }
        '401': { description: Unauthorized }
        '409': { description: Current signed Action Policy baseline is untrusted or changed }
        '500': { description: Evidence-logic compilation failed }

  /v1/policy/action/evidence-logic/apply:
    post:
      tags: [policy, enforce]
      summary: Apply Action Policy evidence logic after exact confirmation
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ActionEvidenceLogicApplyRequest' }
      responses:
        '200':
          description: No-op or signed evidence-logic apply result
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ActionEvidenceLogicApplyResponse' }
        '400': { description: Invalid tree, gate coverage, or Action Policy rule }
        '401': { description: Unauthorized }
        '403': { description: Owner role required or read-only mode active }
        '409': { description: Exact confirmation, acknowledgement, or trusted baseline unavailable }
        '423': { description: Another Action Policy evidence-logic operation holds the writer lock }
        '500': { description: Policy write, sign, or post-verification failed }

  /v1/policy/scope-templates:
    get:
      tags: [policy, enforce, fleet]
      summary: List immutable AMC action-class scope templates
      responses:
        '200':
          description: Bounded scope template catalog
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ScopeTemplateCatalogResponse' }
        '401': { description: Unauthorized }
        '500': { description: Scope template catalog unavailable }

  /v1/policy/scope-templates/compile:
    post:
      tags: [policy, enforce, fleet]
      summary: Compile a selected action-class scope without writing policy
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ScopeTemplateCompileRequest' }
      responses:
        '200':
          description: Deterministic read-only scope preview
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ScopeTemplateCompilationResponse' }
        '400': { description: Unknown template, Policy Pack, or invalid policy schema }
        '401': { description: Unauthorized }
        '409': { description: Current signed policy baseline is untrusted or changed }
        '500': { description: Scope template compilation failed }

  /v1/policy/scope-templates/apply:
    post:
      tags: [policy, enforce, fleet]
      summary: Apply a scope preview after exact compile-ID confirmation
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ScopeTemplateApplyRequest' }
      responses:
        '200':
          description: No-op or signed scope apply result
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ScopeTemplateApplyResponse' }
        '400': { description: Unknown template, Policy Pack, or invalid policy schema }
        '401': { description: Unauthorized }
        '403': { description: Owner role required or read-only mode active }
        '409': { description: Exact compile confirmation or trusted baseline is unavailable }
        '423': { description: Another policy scope operation holds the writer lock }
        '500': { description: Policy write, sign, or post-verification failed }

  /v1/policy/simulate:
    post:
      tags: [policy, enforce]
      summary: Simulate one projected control through its production evaluator without recording
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlSimulationRequest'
      responses:
        '200':
          description: Read-only evaluator-backed control simulation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlSimulationResponse'
        '400':
          description: Invalid control simulation request
        '401':
          description: Unauthorized
        '500':
          description: Control simulation failed

  /v1/policy/action/init:
    post:
      tags: [compliance]
      summary: Create and sign action policy
      responses:
        '201':
          description: Action policy created

  /v1/policy/action/verify:
    get:
      tags: [compliance]
      summary: Verify action policy signature
      responses:
        '200':
          description: Verification result

  /v1/policy/approval/init:
    post:
      tags: [compliance]
      summary: Create and sign approval policy
      responses:
        '201':
          description: Approval policy created

  /v1/policy/approval/verify:
    get:
      tags: [compliance]
      summary: Verify approval policy signature
      responses:
        '200':
          description: Verification result

  /v1/policy/pack/list:
    get:
      tags: [compliance]
      summary: List built-in policy packs
      responses:
        '200':
          description: Policy pack list

  /v1/policy/pack/describe/{packId}:
    get:
      tags: [compliance]
      summary: Describe a policy pack
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Policy pack details

  /v1/policy/pack/diff:
    post:
      tags: [compliance]
      summary: Show diff for applying a policy pack
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [packId]
              properties:
                packId:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Diff result

  /v1/policy/pack/apply:
    post:
      tags: [compliance]
      summary: Apply policy pack
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [packId]
              properties:
                packId:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Policy pack applied

  /v1/policy/debt/add:
    post:
      tags: [compliance]
      summary: Register policy debt
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [requirement, justification, expires]
              properties:
                agentId:
                  type: string
                requirement:
                  type: string
                justification:
                  type: string
                expires:
                  type: string
                createdBy:
                  type: string
      responses:
        '201':
          description: Policy debt registered

  /v1/policy/debt/list:
    get:
      tags: [compliance]
      summary: List active policy debt
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: all
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Active and expired policy debt

  /v1/policy/ops/init:
    post:
      tags: [compliance]
      summary: Create and sign ops policy
      responses:
        '201':
          description: Ops policy created

  /v1/policy/ops/verify:
    get:
      tags: [compliance]
      summary: Verify ops policy signature
      responses:
        '200':
          description: Verification result

  /v1/policy/ops/print:
    get:
      tags: [compliance]
      summary: Print effective ops policy
      responses:
        '200':
          description: Ops policy

  /v1/waiver/request:
    post:
      tags: [compliance]
      summary: Request time-limited readiness waiver
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hours, reason]
              properties:
                hours:
                  type: integer
                reason:
                  type: string
                agentId:
                  type: string
      responses:
        '201':
          description: Waiver granted

  /v1/waiver/status:
    get:
      tags: [compliance]
      summary: Show waiver status
      responses:
        '200':
          description: Waiver status

  /v1/waiver/revoke:
    post:
      tags: [compliance]
      summary: Revoke active waiver
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                waiverId:
                  type: string
      responses:
        '200':
          description: Waiver revoked

  /v1/regulatory/eu-ai-act:
    get:
      tags: [compliance]
      summary: Score EU AI Act compliance
      responses:
        '200':
          description: EU AI Act score

  /v1/regulatory/owasp-llm:
    get:
      tags: [compliance]
      summary: Score OWASP LLM Top 10 coverage
      responses:
        '200':
          description: OWASP LLM score

  /v1/regulatory/readiness:
    get:
      tags: [compliance]
      summary: Weighted regulatory readiness score
      parameters:
        - name: agentId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Regulatory readiness result

  # ── Evidence ───────────────────────────────────────────────────
  /v1/evidence/status:
    get:
      tags: [evidence]
      summary: Evidence module status
      responses:
        '200':
          description: Status

  /v1/evidence/list:
    get:
      tags: [evidence]
      summary: List evidence files for agent
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Evidence file list

  /v1/evidence/gaps:
    get:
      tags: [evidence]
      summary: Evidence gaps for agent
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: runId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Evidence gaps

  /v1/evidence/ingest:
    post:
      tags: [evidence]
      summary: Ingest evidence from content string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [type, content]
              properties:
                agentId:
                  type: string
                type:
                  type: string
                content:
                  type: string
                filename:
                  type: string
      responses:
        '201':
          description: Evidence ingested

  /v1/evidence/collect:
    post:
      tags: [evidence]
      summary: Collect evidence from a path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputPath, type]
              properties:
                agentId:
                  type: string
                inputPath:
                  type: string
                type:
                  type: string
      responses:
        '201':
          description: Evidence collected

  /v1/evidence/export:
    get:
      tags: [evidence]
      summary: Export evidence bundle
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, csv]
      responses:
        '200':
          description: Evidence export

  # ── Neutral Imports ─────────────────────────────────────────────
  /v1/imports:
    get:
      tags: [imports]
      summary: List neutral import runs
      responses:
        '200':
          description: Neutral import list
    post:
      tags: [imports]
      summary: Import neutral artifacts into AMC evidence
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputPath]
              properties:
                inputPath:
                  type: string
                agentId:
                  type: string
      responses:
        '201':
          description: Import written
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NeutralImportResult'

  /v1/imports/dry-run:
    post:
      tags: [imports]
      summary: Detect neutral artifacts without writing files
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputPath]
              properties:
                inputPath:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Dry-run import plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NeutralImportResult'

  /v1/imports/validate:
    post:
      tags: [imports]
      summary: Validate neutral import support
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputPath]
              properties:
                inputPath:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Import validation plan

  /v1/imports/{importId}/rollback:
    post:
      tags: [imports]
      summary: Roll back files written by a neutral import
      parameters:
        - name: importId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rollback receipt

  # ── Inference Strategy ──────────────────────────────────────────
  /v1/strategy/runs:
    get:
      tags: [strategy]
      summary: List inference strategy comparison runs
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Strategy run list

  /v1/strategy/compare:
    post:
      tags: [strategy]
      summary: Compare inference strategies and optionally commit a route
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [strategies]
              properties:
                agentId:
                  type: string
                objective:
                  type: string
                  enum: [balanced, quality, cost, latency, safety]
                applyRoute:
                  type: boolean
                policyApproval:
                  type: boolean
                strategies:
                  type: array
                  items:
                    type: object
      responses:
        '201':
          description: Strategy comparison result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceStrategyRun'

  /v1/strategy/runs/{selector}:
    get:
      tags: [strategy]
      summary: Inspect a strategy comparison run
      parameters:
        - name: selector
          in: path
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Strategy comparison run

  /v1/strategy/runs/{selector}/rollback:
    post:
      tags: [strategy]
      summary: Roll back an accepted strategy route change
      parameters:
        - name: selector
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Strategy rollback receipt

  /v1/evidence/attest:
    post:
      tags: [evidence]
      summary: Attest an ingest session
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [ingestSessionId]
              properties:
                agentId:
                  type: string
                ingestSessionId:
                  type: string
      responses:
        '200':
          description: Attestation result

  /v1/evidence/bundle:
    post:
      tags: [evidence]
      summary: Create portable evidence bundle
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runId]
              properties:
                agentId:
                  type: string
                runId:
                  type: string
      responses:
        '200':
          description: Bundle created

  /v1/evidence/trace-indexes:
    get:
      tags: [evidence]
      summary: List distilled trace failure indexes
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: redacted
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Trace failure index list

  /v1/evidence/trace-indexes/{selector}:
    get:
      tags: [evidence]
      summary: Inspect a trace failure index
      parameters:
        - name: selector
          in: path
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
        - name: redacted
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Trace failure index

  /v1/evidence/failure-clusters:
    get:
      tags: [evidence]
      summary: List top recurring failure clusters
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: redacted
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Ranked failure clusters

  # ── Crypto ─────────────────────────────────────────────────────
  /v1/crypto/notary/status:
    get:
      tags: [crypto]
      summary: Notary backend and log status
      parameters:
        - name: notaryDir
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Notary status

  /v1/crypto/notary/pubkey:
    get:
      tags: [crypto]
      summary: Notary public key and fingerprint
      responses:
        '200':
          description: Public key info

  /v1/crypto/notary/attest:
    post:
      tags: [crypto]
      summary: Generate signed attestation bundle
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [outFile]
              properties:
                outFile:
                  type: string
                notaryDir:
                  type: string
      responses:
        '201':
          description: Attestation bundle

  /v1/crypto/notary/verify-attest:
    post:
      tags: [crypto]
      summary: Verify .amcattest bundle
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
      responses:
        '200':
          description: Verification result

  /v1/crypto/notary/sign:
    post:
      tags: [crypto]
      summary: Sign a payload file using Notary
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [kind, inFile, outFile]
              properties:
                kind:
                  type: string
                inFile:
                  type: string
                outFile:
                  type: string
      responses:
        '201':
          description: Signed payload

  /v1/crypto/notary/log-verify:
    get:
      tags: [crypto]
      summary: Verify notary append-only log
      responses:
        '200':
          description: Log verification result

  /v1/crypto/cert/generate:
    post:
      tags: [crypto]
      summary: Generate trust certificate
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId, outputPath]
              properties:
                agentId:
                  type: string
                outputPath:
                  type: string
                validityDays:
                  type: integer
      responses:
        '201':
          description: Certificate generated

  /v1/crypto/cert/issue:
    post:
      tags: [crypto]
      summary: Issue signed certificate bundle
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runId, policyPath, outFile]
              properties:
                runId:
                  type: string
                policyPath:
                  type: string
                outFile:
                  type: string
                agentId:
                  type: string
      responses:
        '201':
          description: Certificate issued

  /v1/crypto/cert/verify:
    post:
      tags: [crypto]
      summary: Verify certificate bundle offline
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [certFile]
              properties:
                certFile:
                  type: string
      responses:
        '200':
          description: Verification result

  /v1/crypto/cert/inspect:
    post:
      tags: [crypto]
      summary: Inspect certificate bundle contents
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [certFile]
              properties:
                certFile:
                  type: string
      responses:
        '200':
          description: Certificate details

  /v1/crypto/cert/revoke:
    post:
      tags: [crypto]
      summary: Create signed revocation file
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [certFile, reason, outFile]
              properties:
                certFile:
                  type: string
                reason:
                  type: string
                outFile:
                  type: string
      responses:
        '201':
          description: Revocation file created

  /v1/crypto/cert/verify-revocation:
    post:
      tags: [crypto]
      summary: Verify revocation file
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
      responses:
        '200':
          description: Revocation verification

  /v1/crypto/merkle/rebuild:
    post:
      tags: [crypto]
      summary: Rebuild Merkle leaves/roots
      responses:
        '200':
          description: Merkle rebuilt

  /v1/crypto/merkle/root:
    get:
      tags: [crypto]
      summary: Current Merkle root and history
      responses:
        '200':
          description: Merkle root

  /v1/crypto/merkle/prove:
    post:
      tags: [crypto]
      summary: Export signed inclusion proof
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [entryHash, outFile]
              properties:
                entryHash:
                  type: string
                outFile:
                  type: string
      responses:
        '201':
          description: Proof exported

  /v1/crypto/merkle/verify-proof:
    post:
      tags: [crypto]
      summary: Verify signed inclusion proof
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
      responses:
        '200':
          description: Proof verification

  /v1/crypto/receipts-chain/{receiptId}:
    get:
      tags: [crypto]
      summary: Delegation chain for a receipt
      parameters:
        - name: receiptId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Chain result

  # ── Drift ──────────────────────────────────────────────────────
  /v1/drift/check:
    post:
      tags: [drift]
      summary: Run drift detection
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                against:
                  type: string
                  default: previous
      responses:
        '200':
          description: Drift check result

  /v1/drift/report:
    get:
      tags: [drift]
      summary: Drift/regression markdown report
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Drift report

  /v1/drift/summary:
    get:
      tags: [drift]
      summary: Last drift check summary
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Drift summary

  /v1/drift/freeze/status:
    get:
      tags: [drift]
      summary: Execution freeze status
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Freeze status

  /v1/drift/freeze/lift:
    post:
      tags: [drift]
      summary: Lift execution freeze
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId, incidentId, reason]
              properties:
                agentId:
                  type: string
                incidentId:
                  type: string
                reason:
                  type: string
      responses:
        '200':
          description: Freeze lifted

  /v1/drift/alerts/init:
    post:
      tags: [drift]
      summary: Initialize alerts config
      responses:
        '200':
          description: Alerts initialized

  /v1/drift/alerts/verify:
    get:
      tags: [drift]
      summary: Verify alerts config signature
      responses:
        '200':
          description: Verification result

  /v1/drift/alerts/test:
    post:
      tags: [drift]
      summary: Send test alert
      responses:
        '200':
          description: Test alert sent

  # ── Enforce ────────────────────────────────────────────────────
  /v1/enforce/status:
    get:
      tags: [enforce]
      summary: Enforce module status
      responses:
        '200':
          description: Enforce status

  /v1/enforce/evaluate:
    post:
      tags: [enforce]
      summary: Evaluate action against policy firewall
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [action]
              properties:
                action:
                  type: string
                tool:
                  type: string
                agentId:
                  type: string
                context:
                  type: object
      responses:
        '200':
          description: Policy decision (allow/deny/stepup/sanitize/quarantine)

  # ── Export ─────────────────────────────────────────────────────
  /v1/export/policy:
    post:
      tags: [export]
      summary: Export policy pack
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [target, outDir]
              properties:
                target:
                  type: string
                outDir:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Policy exported

  /v1/export/badge:
    post:
      tags: [export]
      summary: Export maturity badge SVG
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runId, outFile]
              properties:
                runId:
                  type: string
                outFile:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Badge exported

  /v1/export/badge/url:
    get:
      tags: [export]
      summary: Generate badge URL
      parameters:
        - name: level
          in: query
          required: true
          schema:
            type: integer
        - name: label
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [markdown, html, url]
      responses:
        '200':
          description: Badge URL

  /v1/export/badge/generate:
    get:
      tags: [export]
      summary: Generate badge markup
      parameters:
        - name: level
          in: query
          required: true
          schema:
            type: integer
        - name: label
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [markdown, html, url]
      responses:
        '200':
          description: Badge and formatted output

  /v1/attest/notary:
    post:
      tags: [export]
      summary: Generate signed notary attestation bundle
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [outFile]
              properties:
                outFile:
                  type: string
                notaryDir:
                  type: string
      responses:
        '200':
          description: Attestation

  /v1/attest/notary/verify:
    post:
      tags: [export]
      summary: Verify .amcattest bundle
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
      responses:
        '200':
          description: Verification

  /v1/attest/outcome:
    post:
      tags: [export]
      summary: Record manual attested outcome signal
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [metricId, value, reason]
              properties:
                metricId:
                  type: string
                value:
                  type: string
                reason:
                  type: string
                workOrderId:
                  type: string
                unit:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Outcome attested

  # ── Canary ─────────────────────────────────────────────────────
  /v1/canary/start:
    post:
      tags: [canary]
      summary: Start a policy canary
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [candidateSha, stableSha]
              properties:
                candidateSha:
                  type: string
                stableSha:
                  type: string
                enforcePct:
                  type: integer
                duration:
                  type: integer
                failureThreshold:
                  type: number
                autoPromote:
                  type: boolean
      responses:
        '201':
          description: Canary started

  /v1/canary/status:
    get:
      tags: [canary]
      summary: Current canary status and stats
      responses:
        '200':
          description: Canary status

  /v1/canary/stop:
    post:
      tags: [canary]
      summary: Stop the active canary
      responses:
        '200':
          description: Canary stopped

  /v1/canary/report:
    get:
      tags: [canary]
      summary: Full policy canary report
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Canary report

  /v1/canary/micro/run:
    post:
      tags: [canary]
      summary: Run all micro-canary probes
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
      responses:
        '200':
          description: Probe results

  /v1/canary/micro/report:
    get:
      tags: [canary]
      summary: Micro-canary status report
      parameters:
        - name: window
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Micro-canary report

  /v1/canary/micro/alerts:
    get:
      tags: [canary]
      summary: Active micro-canary alerts
      responses:
        '200':
          description: Alert list

  /v1/canary/micro/alerts/ack:
    post:
      tags: [canary]
      summary: Acknowledge all micro-canary alerts
      responses:
        '200':
          description: Alerts acknowledged

  /v1/canary/policy-mode/start:
    post:
      tags: [canary]
      summary: Start policy canary observation mode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [packId]
              properties:
                agentId:
                  type: string
                packId:
                  type: string
                duration:
                  type: string
      responses:
        '201':
          description: Policy canary mode started

  /v1/canary/policy-mode/report:
    get:
      tags: [canary]
      summary: Policy canary mode report
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Policy canary mode report

  # ── CI ─────────────────────────────────────────────────────────
  /v1/ci/init:
    post:
      tags: [ci]
      summary: Initialize CI for an agent
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
      responses:
        '201':
          description: CI initialized

  /v1/ci/steps:
    get:
      tags: [ci]
      summary: List CI steps for an agent
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: CI steps

  /v1/ci/gate:
    post:
      tags: [ci]
      summary: Run bundle gate evaluation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [bundlePath, policyPath]
              properties:
                bundlePath:
                  type: string
                policyPath:
                  type: string
      responses:
        '200':
          description: Gate result

  /v1/ci/policy/default:
    get:
      tags: [ci]
      summary: Get default gate policy
      responses:
        '200':
          description: Default policy

  /v1/ci/policy/sign:
    post:
      tags: [ci]
      summary: Write and sign a gate policy
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [policyPath, policy]
              properties:
                policyPath:
                  type: string
                policy:
                  type: object
      responses:
        '200':
          description: Policy signed

  /v1/ci/policy/verify:
    post:
      tags: [ci]
      summary: Verify gate policy signature
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [policyPath]
              properties:
                policyPath:
                  type: string
      responses:
        '200':
          description: Verification result

  /v1/ci/predict:
    post:
      tags: [ci]
      summary: Predict CI gate outcome (what-if)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId, runId]
              properties:
                agentId:
                  type: string
                runId:
                  type: string
      responses:
        '200':
          description: Prediction result

  # ── Config ─────────────────────────────────────────────────────
  /v1/config:
    get:
      tags: [config]
      summary: Resolved runtime config (secrets redacted)
      responses:
        '200':
          description: Config

  /v1/config/logs:
    get:
      tags: [config]
      summary: Latest studio logs
      parameters:
        - name: lines
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Log entries

  /v1/config/doctor:
    get:
      tags: [config]
      summary: Run doctor checks
      parameters:
        - name: strict
          in: query
          description: Require an initialized, healthy AMC workspace
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Doctor result

  /v1/config/version:
    get:
      tags: [config]
      summary: Version info
      responses:
        '200':
          description: Version

  /v1/config/status:
    get:
      tags: [config]
      summary: Workspace status overview
      responses:
        '200':
          description: Status overview

  # ── Gateway ────────────────────────────────────────────────────
  /v1/gateway/status:
    get:
      tags: [gateway]
      summary: Gateway status
      responses:
        '200':
          description: Gateway status

  /v1/gateway/config:
    get:
      tags: [gateway]
      summary: Get gateway config (redacted)
      responses:
        '200':
          description: Gateway config

  /v1/gateway/init:
    post:
      tags: [gateway]
      summary: Initialize gateway with defaults
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                provider:
                  type: string
      responses:
        '200':
          description: Gateway initialized

  /v1/gateway/bind:
    post:
      tags: [gateway]
      summary: Bind agent to a route
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId]
              properties:
                agentId:
                  type: string
                routePrefix:
                  type: string
      responses:
        '200':
          description: Agent bound

  /v1/gateway/sign:
    post:
      tags: [gateway]
      summary: Sign gateway config
      responses:
        '200':
          description: Config signed

  /v1/gateway/verify:
    get:
      tags: [gateway]
      summary: Verify gateway config signature
      responses:
        '200':
          description: Verification

  /v1/gateway/providers:
    get:
      tags: [gateway]
      summary: List available provider templates
      responses:
        '200':
          description: Provider list

  # ── Runtime Firewall ───────────────────────────────────────────
  /v1/firewall/status:
    get:
      tags: [firewall]
      summary: Runtime Firewall status
      responses:
        '200':
          description: Runtime Firewall mode, canonical policyCommitted/journal/checkpoint state, separate mirrorExists/policyPath compatibility state, integrity, and exact-policy signed rollout counters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeFirewallStatusResponse'

  /v1/firewall/enable:
    post:
      tags: [firewall]
      summary: Enable or disable Runtime Firewall policy
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                mode:
                  type: string
                  enum: [observe, warn, block]
                enabled:
                  type: boolean
                failClosedOnMissingPolicy:
                  type: boolean
      responses:
        '201':
          description: Runtime Firewall policy committed to its signed journal and separate host-local checkpoint
        '400':
          description: Invalid policy request
        '409':
          description: Existing policy or journal failed integrity verification or requires explicit legacy migration
        '413':
          description: JSON request body exceeds 1 MiB
        '423':
          description: Runtime Firewall policy writer is busy; retry the operation

  /v1/firewall/migrate-signature:
    post:
      tags: [firewall]
      summary: Verify and preserve legacy Runtime Firewall policy semantics in the signed control journal
      description: OWNER-only in Studio. Captures and verifies one immutable policy/sidecar snapshot, validates the policy, commits its canonical semantics, and signs source and committed digests in migration metadata. Byte-for-byte preservation is not claimed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [approveLegacyArtifactKind]
              properties:
                approveLegacyArtifactKind:
                  type: boolean
                  const: true
      responses:
        '201':
          description: Exact verified policy semantics committed without default reconstruction
        '400':
          description: Malformed or non-boolean acknowledgement body
        '403':
          description: Studio session lacks the OWNER role
        '409':
          description: Legacy digest/signature invalid or an existing journal failed integrity verification
        '413':
          description: JSON request body exceeds 1 MiB
        '423':
          description: Runtime Firewall policy writer is busy; retry the operation

  /v1/firewall/check:
    post:
      tags: [firewall]
      summary: Evaluate request or response payload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
                direction:
                  type: string
                  enum: [request, response]
                agentId:
                  type: string
                requirePolicy:
                  type: boolean
      responses:
        '201':
          description: Allow, warn, or block decision with candidate-versus-actual rollout binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeFirewallDecisionResponse'

  /v1/firewall/events:
    get:
      tags: [firewall]
      summary: List Runtime Firewall decision events
      responses:
        '200':
          description: Runtime Firewall decisions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeFirewallEventsResponse'

  /v1/firewall/export:
    post:
      tags: [firewall]
      summary: Export redacted Runtime Firewall decisions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                outputPath:
                  type: string
                format:
                  type: string
                  enum: [json, jsonl, splunk]
                redacted:
                  type: boolean
                limit:
                  type: integer
      responses:
        '201':
          description: Export written

  # ── Runtime Run Manager ───────────────────────────────────────
  /v1/runtime/status:
    get:
      tags: [runtime]
      summary: Runtime run-manager status
      parameters:
        - in: query
          name: agentId
          schema:
            type: string
      responses:
        '200':
          description: Runtime run counts and latest run

  /v1/runtime/runs:
    get:
      tags: [runtime]
      summary: List runtime runs
      parameters:
        - in: query
          name: agentId
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: redacted
          schema:
            type: boolean
      responses:
        '200':
          description: Runtime run list
    post:
      tags: [runtime]
      summary: Create a runtime run
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                runId:
                  type: string
                episodeId:
                  type: string
                lifecycleRunId:
                  type: string
                source:
                  type: string
                stage:
                  type: string
      responses:
        '201':
          description: Runtime run created

  /v1/runtime/runs/{runId}:
    get:
      tags: [runtime]
      summary: Inspect runtime run state and events
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
        - in: query
          name: agentId
          schema:
            type: string
        - in: query
          name: redacted
          schema:
            type: boolean
      responses:
        '200':
          description: Runtime run inspection

  /v1/runtime/runs/{runId}/events:
    post:
      tags: [runtime]
      summary: Append a runtime event
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                stage:
                  type: string
                severity:
                  type: string
                  enum: [info, low, medium, high, critical]
                message:
                  type: string
                payload:
                  type: object
                links:
                  type: object
      responses:
        '201':
          description: Runtime event appended

  /v1/runtime/runs/{runId}/resume:
    post:
      tags: [runtime]
      summary: Resume a runtime run
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Runtime run resumed

  /v1/runtime/runs/{runId}/cancel:
    post:
      tags: [runtime]
      summary: Cancel a runtime run
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Runtime run canceled

  /v1/runtime/runs/{runId}/degrade:
    post:
      tags: [runtime]
      summary: Mark a runtime run degraded
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Runtime run degraded

  /v1/runtime/runs/{runId}/complete:
    post:
      tags: [runtime]
      summary: Complete a runtime run
      parameters:
        - in: path
          name: runId
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Runtime run completed

  /v1/runtime/events/export:
    post:
      tags: [runtime]
      summary: Export runtime run events
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runId]
              properties:
                runId:
                  type: string
                agentId:
                  type: string
                outputPath:
                  type: string
                format:
                  type: string
                  enum: [json, jsonl]
                redacted:
                  type: boolean
                limit:
                  type: integer
      responses:
        '201':
          description: Runtime event export written

  # ── Fixer RCA ─────────────────────────────────────────────────
  /v1/fixer/rca:
    get:
      tags: [fixer]
      summary: List Fixer RCA reports
      parameters:
        - in: query
          name: agentId
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
        - in: query
          name: redacted
          schema:
            type: boolean
      responses:
        '200':
          description: Fixer RCA report list
    post:
      tags: [fixer]
      summary: Generate Fixer RCA from a trace failure index
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [selector]
              properties:
                agentId:
                  type: string
                selector:
                  type: string
                  description: Run id, episode id, or trace-index id
                runId:
                  type: string
                  description: Backward-compatible alias for selector
      responses:
        '201':
          description: Fixer RCA report generated

  /v1/fixer/rca/{selector}:
    get:
      tags: [fixer]
      summary: Inspect one Fixer RCA report
      parameters:
        - in: path
          name: selector
          required: true
          schema:
            type: string
        - in: query
          name: agentId
          schema:
            type: string
        - in: query
          name: redacted
          schema:
            type: boolean
      responses:
        '200':
          description: Fixer RCA report

  # ── Identity ───────────────────────────────────────────────────
  /v1/identity/init:
    post:
      tags: [identity]
      summary: Create and sign host-level identity.yaml
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hostDir]
              properties:
                hostDir:
                  type: string
      responses:
        '201':
          description: Identity created

  /v1/identity/verify:
    post:
      tags: [identity]
      summary: Verify identity.yaml signature
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hostDir]
              properties:
                hostDir:
                  type: string
      responses:
        '200':
          description: Verification

  /v1/identity/provider/add-oidc:
    post:
      tags: [identity]
      summary: Add OIDC identity provider
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hostDir, providerId, issuer, clientId, clientSecretFile, redirectUri]
              properties:
                hostDir:
                  type: string
                providerId:
                  type: string
                issuer:
                  type: string
                clientId:
                  type: string
                clientSecretFile:
                  type: string
                redirectUri:
                  type: string
      responses:
        '201':
          description: OIDC provider added

  /v1/identity/provider/add-saml:
    post:
      tags: [identity]
      summary: Add SAML identity provider
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hostDir, providerId, entryPoint, issuer, idpCertFile, spEntityId, acsUrl]
              properties:
                hostDir:
                  type: string
                providerId:
                  type: string
                entryPoint:
                  type: string
                issuer:
                  type: string
                idpCertFile:
                  type: string
                spEntityId:
                  type: string
                acsUrl:
                  type: string
      responses:
        '201':
          description: SAML provider added

  /v1/identity/mapping/add:
    post:
      tags: [identity]
      summary: Add group-to-role mapping rule
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hostDir, group]
              properties:
                hostDir:
                  type: string
                group:
                  type: string
                providerId:
                  type: string
                roles:
                  type: array
                  items:
                    type: string
                    enum: [OWNER, OPERATOR, AUDITOR, VIEWER]
      responses:
        '201':
          description: Mapping added

  /v1/identity/scim/token/create:
    post:
      tags: [identity]
      summary: Create SCIM bearer token
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [hostDir, name]
              properties:
                hostDir:
                  type: string
                name:
                  type: string
                outFile:
                  type: string
      responses:
        '201':
          description: Token created

  # ── Adapters ───────────────────────────────────────────────────
  /v1/adapters/init:
    post:
      tags: [adapters]
      summary: Create signed adapters.yaml defaults
      responses:
        '201':
          description: Adapters initialized

  /v1/adapters/verify:
    get:
      tags: [adapters]
      summary: Verify adapters.yaml signature
      responses:
        '200':
          description: Verification

  /v1/adapters/list:
    get:
      tags: [adapters]
      summary: List built-in adapters and per-agent preferences
      responses:
        '200':
          description: Adapter list

  /v1/adapters/detect:
    get:
      tags: [adapters]
      summary: Detect installed adapter runtimes
      parameters:
        - name: timeoutMs
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Detected adapters

  /v1/adapters/capability-receipts:
    post:
      tags: [adapters, passport]
      summary: Issue a signed adapter capability receipt
      description: Returns declared and effective events/controls, version-probe semantics, current signed configuration and hook state, explicit lossiness, verification result, receipt hash, and auditor signature. Raw prompts, tool arguments, outputs, paths, tokens, and secrets are excluded.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [adapterId]
              properties:
                agentId:
                  type: string
                adapterId:
                  type: string
      responses:
        '201':
          description: Signed adapter capability receipt
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [ok, data]
                properties:
                  ok:
                    type: boolean
                    enum: [true]
                  data:
                    type: object
                    additionalProperties: false
                    required: [receipt]
                    properties:
                      receipt:
                        $ref: '#/components/schemas/AdapterCapabilityReceipt'
        '400': { description: Invalid or unknown request field }
        '401': { description: Missing or invalid Studio authorization }
        '404': { description: Adapter not found }
        '500': { description: Receipt issuance failed closed }

  /v1/adapters/configure:
    post:
      tags: [adapters]
      summary: Set adapter profile for an agent
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [adapterId, route, model, mode]
              properties:
                agentId:
                  type: string
                adapterId:
                  type: string
                route:
                  type: string
                model:
                  type: string
                mode:
                  type: string
                  enum: [SUPERVISE, SANDBOX]
      responses:
        '200':
          description: Adapter configured

  # ── Assurance ──────────────────────────────────────────────────
  /v1/assurance/packs:
    get:
      tags: [assurance]
      summary: List assurance packs
      responses:
        '200':
          description: Pack list

  /v1/assurance/packs/{packId}:
    get:
      tags: [assurance]
      summary: Describe assurance pack
      parameters:
        - name: packId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Pack details

  /v1/assurance/run:
    post:
      tags: [assurance]
      summary: Run assurance pack
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                scopeType:
                  type: string
                  enum: [WORKSPACE, NODE, AGENT]
                scope:
                  type: string
                pack:
                  type: string
                windowDays:
                  type: integer
      responses:
        '200':
          description: Assurance run result

  /v1/assurance/runs:
    get:
      tags: [assurance]
      summary: List assurance runs
      responses:
        '200':
          description: Run history

  /v1/assurance/init:
    post:
      tags: [assurance]
      summary: Initialize assurance workspace
      responses:
        '200':
          description: Assurance initialized

  /v1/assurance/readiness:
    get:
      tags: [assurance]
      summary: Readiness gate check
      responses:
        '200':
          description: Readiness status

  # ── Benchmark ──────────────────────────────────────────────────
  /v1/benchmarks:
    get:
      tags: [benchmark]
      summary: List imported benchmarks
      responses:
        '200':
          description: Benchmark list

  /v1/benchmarks/stats:
    get:
      tags: [benchmark]
      summary: Benchmark statistics
      parameters:
        - name: groupBy
          in: query
          schema:
            type: string
            enum: [archetype, riskTier, trustLabel]
      responses:
        '200':
          description: Stats

  /v1/benchmarks/export:
    post:
      tags: [benchmark]
      summary: Export benchmark artifact
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runId, outFile]
              properties:
                runId:
                  type: string
                outFile:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Benchmark exported

  /v1/benchmarks/import:
    post:
      tags: [benchmark]
      summary: Import benchmark artifact(s)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [path]
              properties:
                path:
                  type: string
      responses:
        '200':
          description: Benchmark imported

  # ── BOM ────────────────────────────────────────────────────────
  /v1/bom/generate:
    post:
      tags: [bom]
      summary: Generate maturity BOM
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runId, outFile]
              properties:
                runId:
                  type: string
                outFile:
                  type: string
                agentId:
                  type: string
      responses:
        '201':
          description: BOM generated

  /v1/bom/sign:
    post:
      tags: [bom]
      summary: Sign a BOM file
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputFile]
              properties:
                inputFile:
                  type: string
                outputSigFile:
                  type: string
      responses:
        '200':
          description: BOM signed

  # ── Incidents ──────────────────────────────────────────────────
  /v1/incidents:
    get:
      tags: [incidents]
      summary: List incidents
      parameters:
        - name: agent
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [open, closed]
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Incident list
    post:
      tags: [incidents]
      summary: Create incident
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                agentId:
                  type: string
                title:
                  type: string
                severity:
                  type: string
                  enum: [INFO, WARN, CRITICAL]
                description:
                  type: string
      responses:
        '201':
          description: Incident created

  /v1/incidents/{id}:
    get:
      tags: [incidents]
      summary: Get incident details
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Incident with transitions and causal edges
    patch:
      tags: [incidents]
      summary: Update incident (resolve or add evidence)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resolution:
                  type: string
                evidenceId:
                  type: string
      responses:
        '200':
          description: Incident updated

  # ── Memory ─────────────────────────────────────────────────────
  /v1/memory/assess/{agentId}:
    get:
      tags: [memory]
      summary: Full memory maturity assessment
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Memory maturity assessment

  /v1/memory/integrity:
    get:
      tags: [memory]
      summary: Score memory integrity (default)
      responses:
        '200':
          description: Integrity score
    post:
      tags: [memory]
      summary: Score memory integrity with provided events
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    type: object
                sessionCount:
                  type: integer
                totalDurationMs:
                  type: integer
      responses:
        '200':
          description: Integrity score

  /v1/memory/reasoning/writeback:
    post:
      tags: [memory]
      summary: Write governed reasoning memory from an EpisodeRecord
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                episodeSelector:
                  type: string
                episode:
                  type: string
                runId:
                  type: string
                allowedConsumers:
                  type: array
                  items:
                    type: string
                    enum: [score, recommendation, fixer, studio]
                ttlDays:
                  type: integer
                reviewDays:
                  type: integer
                summary:
                  type: string
      responses:
        '201':
          description: Reasoning memory writeback result with item and receipt decisions

  /v1/memory/reasoning:
    get:
      tags: [memory]
      summary: Retrieve active governed reasoning memory for a consumer
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: consumer
          in: query
          schema:
            type: string
            enum: [score, recommendation, fixer, studio]
        - name: query
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: redacted
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Active reasoning memory items and citation-ready refs

  /v1/memory/reasoning/receipts:
    get:
      tags: [memory]
      summary: List governed reasoning memory writeback receipts
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Writeback receipts

  /v1/memory/reasoning/{selector}:
    get:
      tags: [memory]
      summary: Inspect one governed reasoning memory item
      parameters:
        - name: selector
          in: path
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
        - name: redacted
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Reasoning memory item

  /v1/memory/extract:
    post:
      tags: [memory]
      summary: Extract lessons from corrections
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                minEffectiveness:
                  type: number
      responses:
        '200':
          description: Extracted lessons

  /v1/memory/advisories:
    get:
      tags: [memory]
      summary: Get lesson advisories
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Advisories

  /v1/memory/report:
    get:
      tags: [memory]
      summary: Correction memory report
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: window
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Memory report

  /v1/memory/expire:
    post:
      tags: [memory]
      summary: Expire stale lessons
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
      responses:
        '200':
          description: Expired lessons

  # ── Metrics ────────────────────────────────────────────────────
  /v1/metrics/status:
    get:
      tags: [metrics]
      summary: Metrics endpoint config
      responses:
        '200':
          description: Metrics host/port

  /v1/slo/status:
    get:
      tags: [metrics]
      summary: Governance SLO dashboard
      parameters:
        - name: window
          in: query
          schema:
            type: number
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: SLO status

  /v1/slo/targets:
    get:
      tags: [metrics]
      summary: List SLO targets
      responses:
        '200':
          description: SLO targets
    put:
      tags: [metrics]
      summary: Update SLO targets
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [targets]
              properties:
                targets:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Targets updated

  /v1/indices/agent:
    get:
      tags: [metrics]
      summary: Failure-risk indices for agent run
      parameters:
        - name: runId
          in: query
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Agent indices

  /v1/indices/fleet:
    get:
      tags: [metrics]
      summary: Fleet failure-risk indices
      parameters:
        - name: window
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Fleet indices

  # ── Security ───────────────────────────────────────────────────
  /v1/security/ato-detect:
    post:
      tags: [security]
      summary: Detect account takeover attempts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId]
              properties:
                agentId:
                  type: string
                events:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: ATO detection result

  /v1/security/blind-secrets:
    post:
      tags: [security]
      summary: Redact secrets from text
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
      responses:
        '200':
          description: Blinded text

  /v1/security/taint:
    post:
      tags: [security]
      summary: Track tainted input
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input:
                  type: string
                source:
                  type: string
      responses:
        '200':
          description: Taint result

  /v1/security/threat-intel:
    post:
      tags: [security]
      summary: Check threat intelligence
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input:
                  type: string
      responses:
        '200':
          description: Threat intel result

  /v1/security/detect-injection:
    post:
      tags: [security]
      summary: Detect prompt injection
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
      responses:
        '200':
          description: Detection result

  /v1/security/sleeper-detection:
    get:
      tags: [security]
      summary: Detect behavioral inconsistencies
      responses:
        '200':
          description: Sleeper detection result

  /v1/security/gaming-resistance:
    get:
      tags: [security]
      summary: Test adversarial evidence injection
      responses:
        '200':
          description: Gaming resistance result

  /v1/security/insider/report:
    get:
      tags: [security]
      summary: Insider risk report
      parameters:
        - name: window
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum: [json, md]
      responses:
        '200':
          description: Insider risk report

  /v1/security/insider/alerts:
    get:
      tags: [security]
      summary: Insider risk alerts
      parameters:
        - name: actorId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Insider alerts

  /v1/security/insider/alerts/ack:
    post:
      tags: [security]
      summary: Acknowledge insider alert
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [alertId]
              properties:
                alertId:
                  type: string
      responses:
        '200':
          description: Alert acknowledged

  /v1/security/insider/scores:
    get:
      tags: [security]
      summary: Insider risk scores by actor
      responses:
        '200':
          description: Risk scores

  /v1/security/advanced-threats:
    post:
      tags: [security]
      summary: Run advanced threats pack
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId]
              properties:
                agentId:
                  type: string
      responses:
        '200':
          description: Advanced threats result

  /v1/security/compound-threats:
    post:
      tags: [security]
      summary: Run compound threat pack
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId]
              properties:
                agentId:
                  type: string
      responses:
        '200':
          description: Compound threats result

  /v1/security/adversarial:
    post:
      tags: [security]
      summary: Test gaming resistance of scoring
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [agentId]
              properties:
                agentId:
                  type: string
      responses:
        '200':
          description: Adversarial test result

  # ── Shield ─────────────────────────────────────────────────────
  /v1/shield/status:
    get:
      tags: [shield]
      summary: Shield module status
      responses:
        '200':
          description: Shield status

  /v1/shield/scan/skill:
    post:
      tags: [shield]
      summary: Scan skill code for vulnerabilities
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code:
                  type: string
                language:
                  type: string
      responses:
        '200':
          description: Scan result

  /v1/shield/detect/injection:
    post:
      tags: [shield]
      summary: Detect prompt injection in input
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input:
                  type: string
      responses:
        '200':
          description: Detection result

  /v1/shield/sanitize:
    post:
      tags: [shield]
      summary: Sanitize input
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input:
                  type: string
      responses:
        '200':
          description: Sanitized output

  /v1/shield/exploit-confirmation/scopes:
    get:
      tags: [shield]
      summary: List exploit-confirmation authorization scopes
      description: Returns signed scopes that permit controlled exploit confirmation under ownership, time-window, technique, and safe-mode constraints.
      responses:
        '200':
          description: Authorization scope list
    post:
      tags: [shield]
      summary: Write exploit-confirmation authorization scope
      description: Stores a signed fail-closed authorization scope. Confirmation cannot run without an active matching scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [scope]
              properties:
                scope:
                  $ref: '#/components/schemas/ExploitConfirmationScope'
      responses:
        '201':
          description: Authorization scope written

  /v1/shield/exploit-confirmation/run:
    post:
      tags: [shield]
      summary: Run controlled exploit confirmation
      description: Converts an authorized security finding into safe proof. Public artifacts include hashes, receipts, and signal refs, not exploit instructions or raw payloads.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [task]
              properties:
                scopeId:
                  type: string
                task:
                  $ref: '#/components/schemas/ExploitConfirmationTask'
                nowTs:
                  type: integer
      responses:
        '201':
          description: Confirmation completed with safe proof
        '200':
          description: Confirmation blocked by policy or scope gate

  /v1/shield/exploit-confirmation/proofs:
    get:
      tags: [shield]
      summary: List safe exploit-confirmation proofs
      responses:
        '200':
          description: Safe proof list

  /v1/shield/exploit-confirmation/proofs/{proofId}/export:
    post:
      tags: [shield]
      summary: Export safe exploit-confirmation proof
      description: Exports redacted proof suitable for Vault or Passport evidence bundles without exploit instructions.
      parameters:
        - name: proofId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                outPath:
                  type: string
                redacted:
                  type: boolean
      responses:
        '200':
          description: Safe proof exported

  # ── Vault ──────────────────────────────────────────────────────
  /v1/vault/status:
    get:
      tags: [vault]
      summary: Vault status
      responses:
        '200':
          description: Vault status

  /v1/vault/unlock:
    post:
      tags: [vault]
      summary: Unlock vault with passphrase
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                passphrase:
                  type: string
      responses:
        '200':
          description: Vault unlocked

  /v1/vault/seal:
    post:
      tags: [vault]
      summary: Lock vault
      responses:
        '200':
          description: Vault sealed

  /v1/vault/keys:
    get:
      tags: [vault]
      summary: List public key history
      parameters:
        - name: kind
          in: query
          schema:
            type: string
            enum: [monitor, auditor, lease, session]
      responses:
        '200':
          description: Key history

  /v1/vault/keys/rotate:
    post:
      tags: [vault]
      summary: Rotate vault keys
      responses:
        '200':
          description: Keys rotated

  /v1/vault/secret/set:
    post:
      tags: [vault]
      summary: Set a vault secret
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [key, value]
              properties:
                key:
                  type: string
                value:
                  type: string
      responses:
        '200':
          description: Secret set

  /v1/vault/redact:
    post:
      tags: [vault]
      summary: Redact PII from text
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
      responses:
        '200':
          description: Redacted text

  /v1/vault/classify:
    post:
      tags: [vault]
      summary: Classify content sensitivity
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
      responses:
        '200':
          description: Classification

  /v1/vault/dlp-scan:
    post:
      tags: [vault]
      summary: DLP scan content
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
      responses:
        '200':
          description: DLP scan result

  # ── Tools/Guardrails/Plugins ───────────────────────────────────
  /v1/tools/init:
    post:
      tags: [tools]
      summary: Create and sign tools.yaml
      responses:
        '201':
          description: Tools initialized

  /v1/tools/verify:
    get:
      tags: [tools]
      summary: Verify tools.yaml signature
      responses:
        '200':
          description: Verification

  /v1/tools/list:
    get:
      tags: [tools]
      summary: List signed ToolHub tools grouped by declared provider context
      responses:
        '200':
          description: Fail-closed read-only ToolHub context projection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolContextApiResponse'

  /v1/guardrails/list:
    get:
      tags: [tools]
      summary: List signed requested state and effective runtime guardrail bindings
      responses:
        '200':
          description: Guardrail catalog with requested, effective, binding, mutability, trust, source, and reason fields
        '409':
          description: Guardrail control state or Runtime Firewall policy failed integrity verification
        '423':
          description: Guardrail control state is busy; retry the operation

  /v1/guardrails/enable:
    post:
      tags: [tools]
      summary: Add a signed request for a runtime-bound guardrail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name]
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Guardrail ID. Runtime-bound IDs can be changed; known catalog-only IDs return 409 and unknown IDs return 404.
      responses:
        '200':
          description: Signed request persisted; statusError is populated only if post-commit status refresh raced
        '400':
          description: Malformed JSON or missing/invalid name
        '403':
          description: Local Dashboard mutation lacks its same-origin owner capability
        '404':
          description: Unknown guardrail
        '409':
          description: Catalog-only guardrail or failed artifact integrity
        '413':
          description: JSON request body exceeds 1 MiB
        '423':
          description: Guardrail control state is busy; retry the operation

  /v1/guardrails/disable:
    post:
      tags: [tools]
      summary: Remove an additive guardrail request without weakening signed policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name]
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Guardrail ID. Runtime-bound IDs can be changed; known catalog-only IDs return 409 and unknown IDs return 404.
      responses:
        '200':
          description: Signed request removed; statusError is populated only if post-commit status refresh raced
        '400':
          description: Malformed JSON or missing/invalid name
        '403':
          description: Local Dashboard mutation lacks its same-origin owner capability
        '404':
          description: Unknown guardrail
        '409':
          description: Catalog-only guardrail or failed artifact integrity
        '413':
          description: JSON request body exceeds 1 MiB
        '423':
          description: Guardrail control state is busy; retry the operation

  /v1/guardrails/profile:
    post:
      tags: [tools]
      summary: Apply the runtime-bound subset of a signed additive profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name]
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Profile ID. Known profiles are minimal, standard, strict, healthcare, and financial; unknown IDs return 404.
      responses:
        '200':
          description: Profile committed with bound requests, effective controls, catalog-only exclusions, and optional statusError
        '400':
          description: Malformed JSON or missing/invalid name
        '403':
          description: Local Dashboard mutation lacks its same-origin owner capability
        '404':
          description: Unknown profile
        '409':
          description: Guardrail control state or Runtime Firewall policy failed integrity verification
        '413':
          description: JSON request body exceeds 1 MiB
        '423':
          description: Guardrail control state is busy; retry the operation

  /v1/plugins/list:
    get:
      tags: [tools]
      summary: List installed plugins
      responses:
        '200':
          description: Plugin list

  /v1/plugins/keygen:
    post:
      tags: [tools]
      summary: Generate plugin publisher keypair
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [outDir]
              properties:
                outDir:
                  type: string
      responses:
        '201':
          description: Keypair generated

  /v1/plugins/verify:
    post:
      tags: [tools]
      summary: Verify plugin package signature
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
      responses:
        '200':
          description: Verification

  /v1/plugins/install:
    post:
      tags: [tools]
      summary: Install plugin from registry
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [registryId, pluginRef]
              properties:
                registryId:
                  type: string
                pluginRef:
                  type: string
                agentId:
                  type: string
      responses:
        '201':
          description: Plugin installed

  # ── Watch ──────────────────────────────────────────────────────
  /v1/watch/status:
    get:
      tags: [watch]
      summary: Watch module status
      responses:
        '200':
          description: Status

  /v1/watch/hooks/{provider}/health:
    get:
      tags: [watch, hooks]
      summary: Inspect signed hook setup and the latest verified provider event
      description: Joins the signed installation and lease state with the latest receipt-verified event. Last-observed time is historical evidence, not a current-liveness claim.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [claude-code, gemini-cli]
      responses:
        '200':
          description: Read-only hook health projection
          content:
            application/json:
              schema:
                type: object
                required: [ok, data]
                properties:
                  ok: { type: boolean, enum: [true] }
                  data:
                    $ref: '#/components/schemas/HookHealthDiagnostic'
        '400': { description: Unsupported provider }

  /v1/watch/hook-actions/{actionId}:
    get:
      tags: [watch, hooks]
      summary: Verify one provider hook action lifecycle
      description: Returns the receipt-verified requested, optional decision, and terminal lifecycle for one agent/action key. Missing, duplicate, conflicting, cross-agent, out-of-order, or tampered evidence fails closed.
      parameters:
        - name: actionId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - name: agentId
          in: query
          schema:
            type: string
            default: default
            minLength: 1
            maxLength: 160
      responses:
        '200':
          description: Verified action lifecycle projection
          content:
            application/json:
              schema:
                type: object
                required: [ok, data]
                properties:
                  ok: { type: boolean, enum: [true] }
                  data:
                    $ref: '#/components/schemas/HookActionLifecycle'
        '400': { description: Invalid agent or action identifier }

  /v1/watch/guard:
    post:
      tags: [watch]
      summary: Run guardrail check against proposed output
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [proposedOutput]
              properties:
                agentId:
                  type: string
                proposedOutput:
                  type: string
                riskTier:
                  type: string
                actionType:
                  type: string
      responses:
        '200':
          description: Guard check result

  /v1/watch/attest:
    post:
      tags: [watch]
      summary: Attest agent output via ledger
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [output]
              properties:
                agentId:
                  type: string
                output:
                  type: string
                sessionId:
                  type: string
      responses:
        '200':
          description: Attestation result

  /v1/watch/safety-test:
    post:
      tags: [watch]
      summary: Run safety assurance pack
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                packId:
                  type: string
                window:
                  type: string
      responses:
        '200':
          description: Safety test result

  /v1/watch/explain:
    post:
      tags: [watch]
      summary: Explainability packet for a run
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [runId]
              properties:
                agentId:
                  type: string
                runId:
                  type: string
      responses:
        '200':
          description: Explanation

  /v1/watch/governor:
    get:
      tags: [watch]
      summary: Autonomy governor status check
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
        - name: actionClass
          in: query
          schema:
            type: string
        - name: riskTier
          in: query
          schema:
            type: string
        - name: mode
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Governor check result

  /v1/watch/host-hardening:
    get:
      tags: [watch]
      summary: Host hardening status
      responses:
        '200':
          description: Hardening check result

  /v1/watch/oversight:
    post:
      tags: [watch]
      summary: Log an oversight event
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [event]
              properties:
                agentId:
                  type: string
                event:
                  type: string
                metadata:
                  type: object
      responses:
        '200':
          description: Oversight logged

  # ── Workflow ───────────────────────────────────────────────────
  /v1/workorders:
    post:
      tags: [workflow]
      summary: Create work order
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [title, description, riskTier, mode]
              properties:
                title:
                  type: string
                description:
                  type: string
                riskTier:
                  type: string
                mode:
                  type: string
                allowedActionClasses:
                  type: array
                  items:
                    type: string
                agentId:
                  type: string
      responses:
        '201':
          description: Work order created
    get:
      tags: [workflow]
      summary: List work orders
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Work order list

  /v1/workorders/{workOrderId}:
    get:
      tags: [workflow]
      summary: Show work order
      parameters:
        - name: workOrderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Work order details

  /v1/workorders/{workOrderId}/verify:
    post:
      tags: [workflow]
      summary: Verify work order signature
      parameters:
        - name: workOrderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Verification

  /v1/workorders/{workOrderId}/expire:
    post:
      tags: [workflow]
      summary: Expire/revoke work order
      parameters:
        - name: workOrderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                agentId:
                  type: string
      responses:
        '200':
          description: Work order expired

  /v1/tickets/issue:
    post:
      tags: [workflow]
      summary: Issue execution ticket
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [workOrderId, action]
              properties:
                workOrderId:
                  type: string
                action:
                  type: string
                tool:
                  type: string
                ttl:
                  type: string
                agentId:
                  type: string
      responses:
        '201':
          description: Ticket issued

  /v1/tickets/verify:
    post:
      tags: [workflow]
      summary: Verify execution ticket
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [ticket]
              properties:
                ticket:
                  type: string
      responses:
        '200':
          description: Verification result

  /v1/lifecycle/status:
    get:
      tags: [workflow]
      summary: Lifecycle status
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Lifecycle status

  /v1/lifecycle/advance:
    post:
      tags: [workflow]
      summary: Advance lifecycle stage
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [to]
              properties:
                to:
                  type: string
                agentId:
                  type: string
                actor:
                  type: string
                actorRole:
                  type: string
                controls:
                  type: array
                  items:
                    type: string
                note:
                  type: string
      responses:
        '200':
          description: Stage advanced

  # ── Sandbox ────────────────────────────────────────────────────
  /v1/sandbox/run:
    post:
      tags: [sandbox]
      summary: Run command in hardened Docker sandbox
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [command]
              properties:
                agentId:
                  type: string
                command:
                  type: string
                args:
                  type: array
                  items:
                    type: string
                image:
                  type: string
      responses:
        '200':
          description: Sandbox session

  /v1/sandbox/docker-args:
    post:
      tags: [sandbox]
      summary: Preview Docker args without executing
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [command]
              properties:
                command:
                  type: string
      responses:
        '200':
          description: Docker args preview

  # ── Product ────────────────────────────────────────────────────
  /v1/product/status:
    get:
      tags: [product]
      summary: Product module status
      responses:
        '200':
          description: Status

  /v1/product/batch/create:
    post:
      tags: [product]
      summary: Create batch
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, items]
              properties:
                name:
                  type: string
                items:
                  type: array
                  items:
                    type: object
      responses:
        '201':
          description: Batch created

  /v1/product/batch/{id}/start:
    post:
      tags: [product]
      summary: Start batch processing
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Batch started

  /v1/product/batch/{id}/progress:
    get:
      tags: [product]
      summary: Get batch progress
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Batch progress

  /value/ingest/webhook:
    post:
      tags: [value]
      summary: Ingest value KPI webhook payload
      description: |
        Studio-root value ingestion endpoint for owner systems. In single-workspace Studio mode call `/value/ingest/webhook`.
        In multi-workspace host mode call `/w/{workspaceId}/value/ingest/webhook`.

        Authentication accepts either an OWNER/OPERATOR Studio session, `x-amc-admin-token`, or the vault-backed
        `x-amc-webhook-token` stored under `value/webhook/token`. The webhook token is a bearer-style shared token
        compared with timing-safe equality; it is not an HMAC request signature and should not be sent in the query string
        or JSON body.
      servers:
        - url: http://localhost:3000
          description: Single-workspace local Studio root
        - url: https://{host}
          description: Single-workspace self-hosted Studio root
          variables:
            host:
              default: amc.example.com
              description: DNS name for your self-hosted AMC Studio deployment
        - url: https://{host}/w/{workspaceId}
          description: Multi-workspace host-mode Studio route prefix
          variables:
            host:
              default: amc.example.com
              description: DNS name for your self-hosted AMC host deployment
            workspaceId:
              default: default
              description: AMC host-mode workspace id
      security:
        - amcSessionCookie: []
        - amcAdminToken: []
        - valueWebhookToken: []
      parameters:
        - name: x-amc-webhook-token
          in: header
          required: false
          description: Vault-backed value webhook token. Required when the caller does not use an OWNER/OPERATOR Studio session or `x-amc-admin-token`.
          schema:
            type: string
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueWebhookPayload'
      responses:
        '200':
          description: Value events ingested and transparency entry appended
          content:
            application/json:
              schema:
                type: object
                required: [ingested, file, sha256, trustKind, transparencyHash]
                properties:
                  ingested:
                    type: integer
                    minimum: 1
                  file:
                    type: string
                  sha256:
                    type: string
                  trustKind:
                    type: string
                    enum: [ATTESTED]
                  transparencyHash:
                    type: string
        '400':
          description: Invalid JSON, schema violation, or suspicious string content in the value payload
        '401':
          description: Missing or invalid OWNER/OPERATOR session, `x-amc-admin-token`, or `x-amc-webhook-token`

  /v1/product/portal/submit:
    post:
      tags: [product]
      summary: Submit portal job
      description: >-
        The recorded submitter is taken from the authenticated caller. A
        `submittedBy` field in the request body is rejected with 400 rather than
        ignored, so attribution can never be self-asserted.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name, type]
              properties:
                name:
                  type: string
                type:
                  type: string
                payload:
                  oneOf:
                    - $ref: '#/components/schemas/PortalWebhookPayload'
                    - $ref: '#/components/schemas/OutcomeWebhookPayload'
                    - $ref: '#/components/schemas/ValueWebhookPayload'
                    - $ref: '#/components/schemas/WebhookEventEnvelope'
            examples:
              valueSignal:
                summary: Value KPI webhook payload
                value:
                  name: Support SLA value signal
                  type: value.signal
                  payload:
                    v: 1
                    sourceId: support.sla.webhook
                    scope:
                      type: AGENT
                      id: support-agent
                    events:
                      - kpiId: ticket.resolve.minutes
                        value: 12
                        unit: minutes
                        labels:
                          domain: customer-support
              outcomeSignal:
                summary: Outcome signal webhook payload
                value:
                  name: Brand lift outcome
                  type: outcome.signal
                  payload:
                    agentId: sales-agent
                    signalId: demo.followup.rate
                    category: Economic
                    value: 0.18
                    unit: ratio
              genericEnvelope:
                summary: Generic AMC webhook envelope
                value:
                  name: Generic routed event
                  type: integration.event
                  payload:
                    eventType: integration.delivery.failed
                    source: amc.integrations
                    data:
                      channelId: pagerduty-primary
                      reason: timeout
      responses:
        '201':
          description: Job submitted
        '400':
          description: Invalid body, including a body that supplies `submittedBy`
        '401':
          description: No authenticated caller to attribute the job to

  /v1/product/portal/{jobId}:
    get:
      tags: [product]
      summary: Get portal job
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job details

  # ── Passport ───────────────────────────────────────────────────
  /v1/passports:
    get:
      tags: [passport]
      summary: List passports
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: pageSize
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Passport registry

  /v1/passport/{id}:
    get:
      tags: [passport]
      summary: Get public passport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Public passport data

  /v1/passport/{id}/verify:
    get:
      tags: [passport]
      summary: Verify passport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Verification result

  /v1/passport/{id}/revoke:
    post:
      tags: [passport]
      summary: Revoke passport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                revokedBy:
                  type: string
      responses:
        '200':
          description: Passport revoked

  # ── Agent Timeline ─────────────────────────────────────────────
  /v1/agents/{id}/timeline:
    get:
      tags: [agentTimeline]
      summary: Agent timeline data
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: maxRuns
          in: query
          schema:
            type: integer
        - name: maxEvidenceEvents
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Timeline data

  # ── Observe ────────────────────────────────────────────────────
  /v1/observe/status:
    get:
      tags: [observe]
      summary: Observe API status
      responses:
        '200':
          description: Observe module status

  /v1/observe/timeline:
    get:
      tags: [observe]
      summary: CLI-parity observe timeline
      description: Returns the same score series, evidence series, timeline events, and anomaly summary used by `amc observe timeline --json`.
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
            default: default
        - name: limit
          in: query
          description: Alias for maxRuns, matching the CLI --limit flag.
          schema:
            type: integer
            minimum: 1
            maximum: 5000
        - name: maxRuns
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 5000
        - name: maxEvidenceEvents
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 20000
      responses:
        '200':
          description: Observe timeline payload

  /v1/observe/anomalies:
    get:
      tags: [observe]
      summary: CLI-parity observe anomalies
      description: Returns anomaly records derived from the same timeline builder used by `amc observe anomalies --json`.
      parameters:
        - name: agentId
          in: query
          schema:
            type: string
            default: default
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
        - name: maxRuns
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 5000
        - name: maxEvidenceEvents
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 20000
      responses:
        '200':
          description: Observe anomalies payload
  # BEGIN GENERATED NATIVE TASK PATHS
  /v1/native-tasks/options:
    get:
      summary: Inspect native task setup without executing a model or tool
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
      responses:
        "200":
          description: Current owned task state; no-store.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskOptionsResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks:
    get:
      summary: List native tasks owned by the caller and selected agent
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: includeArchived
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Set to true to inspect archived closed tasks as well. Only the literal true or false is accepted;
            archived history keeps its request identities and cannot resume.
      responses:
        "200":
          description: Current owned task state; no-store.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskListResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
    post:
      summary: Admit a bounded native AMC task using an owner-scoped request ID
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NativeTaskStart"
      responses:
        "202":
          description: Admission recorded; inspect the task for its actual outcome.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks/{taskId}:
    get:
      summary: Read committed native updates and actual task state
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{64}$
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: cursor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 999999999999999
          description: Exclusive event cursor. Retention may truncate earlier updates; this is not a complete evidence
            verification.
      responses:
        "200":
          description: Current owned task state; no-store.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskPollResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks/{taskId}/turn:
    post:
      summary: Admit a follow-up with an explicit revision and unique request ID
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{64}$
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NativeTaskTurn"
      responses:
        "202":
          description: Admission recorded; inspect the task for its actual outcome.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks/{taskId}/cancel:
    post:
      summary: Request cancellation of this task revision; cancellation is not successful completion
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{64}$
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NativeTaskControl"
      responses:
        "202":
          description: Admission recorded; inspect the task for its actual outcome.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks/{taskId}/release:
    post:
      summary: Release the native writer while keeping an eligible session resumable
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{64}$
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NativeTaskControl"
      responses:
        "200":
          description: Current owned task state; no-store.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks/{taskId}/resume:
    post:
      summary: Resume an owned signed session without replaying a pending prompt
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{64}$
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NativeTaskControl"
      responses:
        "200":
          description: Current owned task state; no-store.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks/{taskId}/verify:
    post:
      summary: Close an active idle writer and verify native evidence; a sealed session cannot resume
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{64}$
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NativeTaskControl"
      responses:
        "200":
          description: Current owned task state; no-store.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  /v1/native-tasks/{taskId}/archive:
    post:
      summary: Archive an owned closed task after authenticating its sealed history; retain evidence and request
        identities
      tags:
        - Studio
        - Native Tasks
      security:
        - amcAdminToken: []
        - amcSessionCookie: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{64}$
        - name: agentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[a-z0-9][a-z0-9_-]*$
          description: Selected agent; defaults to the workspace selection. A task remains pinned to its original owner
            and agent.
        - name: x-amc-native-intent
          in: header
          required: true
          schema:
            type: string
            enum:
              - task-workspace-v1
          description: Explicit native task/approval mutation intent.
        - name: x-amc-native-csrf
          in: header
          required: false
          schema:
            type: string
          description: Required with a human session cookie; obtain from options or /auth/me. Never use in a URL.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
          description: Required for cookie mutations; must match a configured browser origin and the request Host.
            Admin-token clients may omit it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NativeTaskControl"
      responses:
        "200":
          description: Current owned task state; no-store.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskResponse"
        "400":
          description: Invalid request, unknown or repeated query fields, or bounds exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "401":
          description: A verified human session or bootstrap admin token is required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "403":
          description: Identity, role, origin, CSRF, demo or read-only policy refused the operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "404":
          description: Unknown task or task belongs to another owner/agent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "409":
          description: Revision, request ID, signed scope or task state conflict. Refresh; do not automatically replay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "413":
          description: Request body exceeds the server's JSON limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "429":
          description: Active task or retained task capacity reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "500":
          description: Task status is uncertain. Inspect recorded state before another submission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
        "503":
          description: Native task service is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativeTaskError"
  # END GENERATED NATIVE TASK PATHS