openapi: 3.1.0
info:
  title: StellaOps Aggregate API
  version: 0.0.1
  description: Composed OpenAPI from per-service specs. This file is generated by
    compose.mjs.
  contact:
    name: StellaOps API Guild
    email: api@stella-ops.local
servers:
  - url: https://authority.stellaops.local
    description: Example Authority deployment
    x-service: authority
  - url: https://export.stellaops.local
    description: Example Export Center endpoint
    x-service: export-center
  - url: https://graph.stellaops.local
    description: Example Graph endpoint
    x-service: graph
  - url: https://orchestrator.stellaops.local
    description: Example Orchestrator endpoint
    x-service: orchestrator
  - url: https://policy.stellaops.local
    description: Example Policy Engine endpoint
    x-service: policy
  - url: https://scanner.stellaops.local/api/v1
    description: Example Scanner endpoint
    x-service: scanner
  - url: https://scheduler.stellaops.local
    description: Example Scheduler endpoint
    x-service: scheduler
tags:
  - name: Authentication
    description: OAuth 2.1 token exchange, introspection, and revocation flows.
  - name: Keys
    description: JSON Web Key Set discovery.
  - name: Health
    description: Liveness endpoints
  - name: Meta
    description: Readiness/metadata endpoints
  - name: Bundles
    description: Export bundle access
  - name: Graphs
    description: Graph build status and traversal APIs
  - name: Jobs
    description: Job submission and status APIs
  - name: Evaluation
    description: Policy evaluation APIs
  - name: Policies
    description: Policy management APIs
  - name: Queues
    description: Queue metrics APIs
  - name: Scans
    description: Scan lifecycle management
  - name: CallGraphs
    description: Call graph ingestion
  - name: RuntimeEvidence
    description: Runtime evidence collection
  - name: Reachability
    description: Reachability analysis and queries
  - name: Exports
    description: Report exports
  - name: ProofSpines
    description: Verifiable audit trails
paths:
  /authority/introspect:
    post:
      tags:
        - Authentication
      summary: Introspect token state
      description: Returns the active status and claims for a given token. Requires a
        privileged client.
      operationId: authorityIntrospectToken
      security:
        - ClientSecretBasic: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/authority.IntrospectionRequest"
            examples:
              introspectToken:
                summary: Validate an access token issued to Orchestrator
                value:
                  token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
                  token_type_hint: access_token
      responses:
        "200":
          description: Token state evaluated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.IntrospectionResponse"
              examples:
                activeToken:
                  summary: Active token response
                  value:
                    active: true
                    scope: orch:operate orch:read
                    client_id: orch-control
                    sub: operator-7f12
                    username: ops.engineer@tenant.example
                    token_type: Bearer
                    exp: 1761628800
                    iat: 1761625200
                    nbf: 1761625200
                    iss: https://authority.stellaops.local
                    aud:
                      - https://orch.stellaops.local
                    jti: 01J8KYRAMG7FWBPRRV5XG20T7S
                    tenant: tenant-alpha
                    confirmation:
                      mtls_thumbprint: 079871b8c9a0f2e6
                inactiveToken:
                  summary: Revoked token response
                  value:
                    active: false
        "400":
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.OAuthErrorResponse"
              examples:
                missingToken:
                  summary: Token missing
                  value:
                    error: invalid_request
                    error_description: token parameter is required.
        "401":
          description: Client authentication failed or client lacks introspection
            permission.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.OAuthErrorResponse"
              examples:
                unauthorizedClient:
                  summary: Client not allowed to introspect tokens
                  value:
                    error: invalid_client
                    error_description: Client authentication failed.
      x-service: authority
      x-original-path: /introspect
  /authority/jwks:
    get:
      tags:
        - Keys
      summary: Retrieve signing keys
      description: Returns the JSON Web Key Set used to validate Authority-issued tokens.
      operationId: authorityGetJwks
      responses:
        "200":
          description: JWKS document.
          headers:
            Cache-Control:
              schema:
                type: string
              description: Standard caching headers apply; keys rotate infrequently.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.JwksDocument"
              examples:
                ecKeySet:
                  summary: EC signing keys
                  value:
                    keys:
                      - kid: auth-tokens-es384-202510
                        kty: EC
                        use: sig
                        alg: ES384
                        crv: P-384
                        x: 7UchU5R77LtChrJx6uWg9mYjFvV6RIpSgZPDIj7d1q0
                        y: v98nHe8a7mGZ9Fn1t4Jp9PTJv1ma35QPmhUrE4pH7H0
                        status: active
                      - kid: auth-tokens-es384-202409
                        kty: EC
                        use: sig
                        alg: ES384
                        crv: P-384
                        x: hjdKc0r8jvVHJ7S9mP0y0mU9bqN7v5PxS21SwclTzfc
                        y: yk6J3pz4TUpymN4mG-6th3dYvJ5N1lQvDK0PLuFv3Pg
                        status: retiring
      x-service: authority
      x-original-path: /jwks
  /authority/revoke:
    post:
      tags:
        - Authentication
      summary: Revoke an access or refresh token
      description: Revokes an access or refresh token; idempotent.
      operationId: authorityRevokeToken
      security:
        - ClientSecretBasic: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/authority.RevocationRequest"
            examples:
              revokeRefreshToken:
                summary: Revoke refresh token after logout
                value:
                  token: 0.rg9pVlsGzXE8Q
                  token_type_hint: refresh_token
      responses:
        "200":
          description: Token revoked or already invalid. The response body is
            intentionally blank.
        "400":
          description: Malformed request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.OAuthErrorResponse"
              examples:
                missingToken:
                  summary: Token parameter omitted
                  value:
                    error: invalid_request
                    error_description: The revocation request is missing the token parameter.
        "401":
          description: Client authentication failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.OAuthErrorResponse"
              examples:
                badClientSecret:
                  summary: Invalid client credentials
                  value:
                    error: invalid_client
                    error_description: Client authentication failed.
      x-service: authority
      x-original-path: /revoke
  /authority/token:
    post:
      tags:
        - Authentication
      summary: Exchange credentials for tokens
      description: >
        Issues OAuth 2.1 bearer tokens for StellaOps clients. Supports password,
        client credentials,

        authorization-code, device, and refresh token grants. Confidential
        clients must authenticate using

        HTTP Basic auth or `client_secret` form fields.
      operationId: authorityTokenExchange
      security:
        - ClientSecretBasic: []
        - {}
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: "#/components/schemas/authority.PasswordGrantRequest"
                - $ref: "#/components/schemas/authority.ClientCredentialsGrantRequest"
                - $ref: "#/components/schemas/authority.RefreshTokenGrantRequest"
                - $ref: "#/components/schemas/authority.AuthorizationCodeGrantRequest"
            encoding:
              authority_provider:
                style: form
                explode: false
            examples:
              passwordGrant:
                summary: Password grant for tenant-scoped ingestion bot
                value:
                  grant_type: password
                  client_id: ingest-cli
                  client_secret: s3cr3t
                  username: ingest-bot
                  password: pa55w0rd!
                  scope: advisory:ingest vex:ingest
                  authority_provider: primary-directory
              authorizationCode:
                summary: Authorization code exchange for Console UI session
                value:
                  grant_type: authorization_code
                  client_id: console-ui
                  code: 2Lba1WtwPLfZ2b0Z9uPrsQ
                  redirect_uri: https://console.stellaops.local/auth/callback
                  code_verifier: g3ZnL91QJ6i4zO_86oI4CDnZ7gS0bSeK
              clientCredentials:
                summary: Client credentials exchange for Policy Engine
                value:
                  grant_type: client_credentials
                  client_id: policy-engine
                  client_secret: 9c39f602-2f2b-4f29
                  scope: effective:write findings:read
                  operator_reason: Deploying policy change 1234
                  operator_ticket: CHG-004211
              refreshToken:
                summary: Refresh token rotation for console session
                value:
                  grant_type: refresh_token
                  client_id: console-ui
                  refresh_token: 0.rg9pVlsGzXE8Q
      responses:
        "200":
          description: Token exchange succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.TokenResponse"
              examples:
                passwordGrant:
                  summary: Password grant success response
                  value:
                    access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
                    token_type: Bearer
                    expires_in: 3600
                    refresh_token: OxGdVtZJ-mk49cFd38uRUw
                    scope: advisory:ingest vex:ingest
                clientCredentials:
                  summary: Client credentials success response
                  value:
                    access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
                    token_type: Bearer
                    expires_in: 900
                    scope: effective:write findings:read
                authorizationCode:
                  summary: Authorization code success response
                  value:
                    access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
                    token_type: Bearer
                    expires_in: 900
                    refresh_token: VxKpc9Vj9QjYV6gLrhQHTw
                    scope: ui.read authority:tenants.read
                    id_token: eyJhbGciOiJFUzM4NCIsImtpZCI6ImNvbnNvbGUifQ...
        "400":
          description: Malformed request, unsupported grant type, or invalid credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.OAuthErrorResponse"
              examples:
                invalidProvider:
                  summary: Unknown identity provider hint
                  value:
                    error: invalid_request
                    error_description: Unknown identity provider 'legacy-directory'.
                invalidScope:
                  summary: Scope not permitted for client
                  value:
                    error: invalid_scope
                    error_description: Scope 'effective:write' is not permitted for this client.
        "401":
          description: Client authentication failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/authority.OAuthErrorResponse"
              examples:
                badClientSecret:
                  summary: Invalid client secret
                  value:
                    error: invalid_client
                    error_description: Client authentication failed.
      x-service: authority
      x-original-path: /token
  /export-center/bundles:
    get:
      tags:
        - Bundles
      summary: List export bundles
      operationId: exportListBundles
      description: Returns paginated export bundles for the tenant.
      parameters:
        - $ref: "#/components/parameters/TenantParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      security:
        - OAuthClientCredentials: []
        - BearerAuth: []
      responses:
        "200":
          description: Bundle page
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/export-center.BundleSummary"
                  metadata:
                    $ref: "#/components/schemas/PageMetadata"
              examples:
                page:
                  summary: First page of bundles
                  value:
                    items:
                      - bundleId: bundle-2025-11-18-001
                        createdAt: 2025-11-18T12:00:00Z
                        status: ready
                        sizeBytes: 1048576
                        sha256: sha256:abc123
                      - bundleId: bundle-2025-11-18-000
                        createdAt: 2025-11-18T10:00:00Z
                        status: ready
                        sizeBytes: 2048
                        sha256: sha256:def456
                    metadata:
                      hasMore: true
                      nextCursor: eyJyIjoiMjAyNS0xMS0xOC0wMDIifQ
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                invalidTenant:
                  summary: Tenant missing
                  value:
                    code: export.invalid_tenant
                    message: tenant query parameter is required.
                    traceId: 01JF04ERR3
      x-service: export-center
      x-original-path: /bundles
  /export-center/bundles/{bundleId}:
    get:
      tags:
        - Bundles
      summary: Download export bundle by id
      operationId: exportGetBundle
      description: Streams an export bundle archive.
      parameters:
        - name: bundleId
          in: path
          required: true
          schema:
            type: string
          example: bundle-2025-11-18-001
      security:
        - OAuthClientCredentials: []
        - BearerAuth: []
      responses:
        "200":
          description: Bundle stream
          content:
            application/zip:
              examples:
                download:
                  summary: Zip payload
                  value: binary data
                checksumMismatch:
                  summary: Expected sha256 mismatch example
                  value: binary data
        "404":
          description: Bundle not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                notFound:
                  summary: Bundle missing
                  value:
                    code: export.bundle_not_found
                    message: Bundle bundle-2025-11-18-001 not found.
                    traceId: 01JF04NF
      x-service: export-center
      x-original-path: /bundles/{bundleId}
  /export-center/bundles/{bundleId}/manifest:
    get:
      tags:
        - Bundles
      summary: Fetch bundle manifest metadata
      description: Returns manifest metadata for a bundle id.
      operationId: exportGetBundleManifest
      parameters:
        - name: bundleId
          in: path
          required: true
          schema:
            type: string
      security:
        - OAuthClientCredentials: []
        - BearerAuth: []
      responses:
        "200":
          description: Manifest metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/export-center.BundleManifest"
              examples:
                manifest:
                  value:
                    bundleId: bundle-2025-11-18-001
                    contents:
                      - type: advisory
                        digest: sha256:abc123
                      - type: vex
                        digest: sha256:def456
                    sizeBytes: 1048576
                    sha256: sha256:fedcba
                    createdAt: 2025-11-18T12:00:00Z
        "404":
          description: Bundle not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
      x-service: export-center
      x-original-path: /bundles/{bundleId}/manifest
  /export-center/health:
    get:
      tags:
        - Health
      summary: Liveness probe
      description: Returns OK when Export Center is reachable.
      operationId: exportHealth
      responses:
        "200":
          description: Service is up
          content:
            application/json:
              examples:
                ok:
                  value:
                    status: ok
                    service: export-center
                    timestamp: 2025-11-18T00:00:00Z
        "503":
          description: Service unhealthy or dependencies unavailable.
          content:
            application/json:
              examples:
                unhealthy:
                  value:
                    status: degraded
                    service: export-center
                    reason: object store unreachable
                    timestamp: 2025-11-18T00:00:00Z
      x-service: export-center
      x-original-path: /health
  /export-center/healthz:
    get:
      summary: Service health
      tags:
        - Meta
      description: Readiness probe for Export Center dependencies.
      operationId: exportHealthz
      responses:
        "200":
          description: Service healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/export-center.HealthResponse"
              examples:
                ok:
                  summary: Healthy response
                  value:
                    status: ok
                    service: export-center
        "503":
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                unavailable:
                  summary: Unhealthy response
                  value:
                    code: service_unavailable
                    message: mirror bundle backlog exceeds SLA
                    traceId: "3"
      x-service: export-center
      x-original-path: /healthz
  /graph/graphs/{graphId}/nodes:
    get:
      summary: List graph nodes
      tags:
        - Graphs
      operationId: graphListNodes
      description: Lists nodes for a graph with paging.
      parameters:
        - name: graphId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
      responses:
        "200":
          description: Graph nodes page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/graph.GraphNodePage"
              examples:
                sample:
                  value:
                    nodes:
                      - id: node-1
                        kind: artifact
                        label: registry.stella-ops.local/runtime/api
                        tenant: tenant-alpha
                      - id: node-2
                        kind: policy
                        label: policy:baseline
                        tenant: tenant-alpha
                    metadata:
                      hasMore: true
                      nextCursor: eyJuIjoiMjAyNS0xMS0xOCJ9
                filtered:
                  summary: Policy nodes only
                  value:
                    nodes:
                      - id: node-99
                        kind: policy
                        label: policy:runtime-allowlist
                        tenant: tenant-beta
                    metadata:
                      hasMore: false
                      nextCursor: ""
        "404":
          description: Graph not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
      x-service: graph
      x-original-path: /graphs/{graphId}/nodes
  /graph/graphs/{graphId}/status:
    get:
      summary: Get graph build status
      tags:
        - Graphs
      operationId: graphGetStatus
      description: Returns build status for a graph id.
      parameters:
        - name: graphId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/TenantParam"
      responses:
        "200":
          description: Graph status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/graph.GraphStatus"
              examples:
                ready:
                  value:
                    graphId: graph-01JF0XYZ
                    status: ready
                    builtAt: 2025-11-18T12:00:00Z
                    tenant: tenant-alpha
                building:
                  value:
                    graphId: graph-01JF0BUILD
                    status: building
                    builtAt: 2025-11-18T12:05:00Z
                    tenant: tenant-alpha
        "404":
          description: Graph not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/graph.ErrorEnvelope"
      x-service: graph
      x-original-path: /graphs/{graphId}/status
  /graph/healthz:
    get:
      summary: Service health
      tags:
        - Meta
      description: Readiness probe for Graph API.
      operationId: graphHealthz
      responses:
        "200":
          description: Service healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/graph.HealthEnvelope"
              examples:
                ok:
                  summary: Healthy response
                  value:
                    status: ok
                    service: graph
        "503":
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/graph.ErrorEnvelope"
              examples:
                unavailable:
                  summary: Unhealthy response
                  value:
                    code: service_unavailable
                    message: indexer lag exceeds threshold
                    traceId: "5"
      x-service: graph
      x-original-path: /healthz
  /orchestrator/health:
    get:
      tags:
        - Health
      summary: Liveness probe
      description: Returns OK when Orchestrator is reachable.
      operationId: orchestratorHealth
      responses:
        "200":
          description: Service is up
          content:
            application/json:
              examples:
                ok:
                  value:
                    status: ok
                    service: orchestrator
                    timestamp: 2025-11-18T00:00:00Z
        "503":
          description: Service unhealthy or dependencies unavailable.
          content:
            application/json:
              examples:
                unhealthy:
                  value:
                    status: degraded
                    service: orchestrator
                    reason: scheduler queue unreachable
                    timestamp: 2025-11-18T00:00:00Z
      x-service: orchestrator
      x-original-path: /health
  /orchestrator/healthz:
    get:
      summary: Service health
      tags:
        - Meta
      description: Readiness probe for orchestrator dependencies.
      operationId: orchestratorHealthz
      responses:
        "200":
          description: Service healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthEnvelope"
              examples:
                ok:
                  summary: Healthy response
                  value:
                    status: ok
                    service: orchestrator
        "503":
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                unavailable:
                  summary: Unhealthy response
                  value:
                    code: service_unavailable
                    message: outbound queue lag exceeds threshold
                    traceId: "1"
      x-service: orchestrator
      x-original-path: /healthz
  /orchestrator/jobs:
    get:
      tags:
        - Jobs
      summary: List jobs
      operationId: orchestratorListJobs
      description: Returns jobs for the tenant with optional status filter.
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum:
              - queued
              - running
              - failed
              - completed
          description: Optional status filter
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/TenantParam"
      responses:
        "200":
          description: Jobs page
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/orchestrator.JobSummary"
              examples:
                default:
                  summary: Mixed queues
                  value:
                    - jobId: job_01JF04ABCD
                      status: queued
                      queue: scan
                      tenant: tenant-alpha
                      enqueuedAt: 2025-11-18T12:00:00Z
                    - jobId: job_01JF04EFGH
                      status: running
                      queue: policy-eval
                      tenant: tenant-alpha
                      enqueuedAt: 2025-11-18T11:55:00Z
                      startedAt: 2025-11-18T11:56:10Z
                queuedOnly:
                  summary: Filtered by status=queued with page limit
                  value:
                    - jobId: job_01JF0500QUE
                      status: queued
                      queue: export
                      tenant: tenant-beta
                      enqueuedAt: 2025-11-18T12:05:00Z
                    - jobId: job_01JF0501QUE
                      status: queued
                      queue: scan
                      tenant: tenant-beta
                      enqueuedAt: 2025-11-18T12:04:10Z
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                invalidStatus:
                  summary: Bad status filter
                  value:
                    code: orch.invalid_request
                    message: status must be one of queued,running,failed,completed.
                    traceId: 01JF04ERR1
      x-service: orchestrator
      x-original-path: /jobs
    post:
      tags:
        - Jobs
      summary: Submit a job to the orchestrator queue
      operationId: orchestratorSubmitJob
      description: Enqueue a job for asynchronous execution.
      parameters:
        - in: header
          name: Idempotency-Key
          description: Optional idempotency key to safely retry job submissions.
          required: false
          schema:
            type: string
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/orchestrator.JobCreateRequest"
            examples:
              scanJob:
                summary: Submit scan job
                value:
                  kind: scan
                  payload:
                    artifactId: registry.stella-ops.local/runtime/api
                    policyVersion: 2025.10.1
                  priority: high
                  tenant: tenant-alpha
      security:
        - OAuthClientCredentials: []
        - BearerAuth: []
      responses:
        "202":
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/orchestrator.JobCreateResponse"
              examples:
                accepted:
                  summary: Job enqueued
                  value:
                    jobId: job_01JF04ABCD
                    status: queued
                    queue: scan
                    enqueuedAt: 2025-11-18T12:00:00Z
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                missingType:
                  summary: Missing jobType
                  value:
                    code: orch.invalid_request
                    message: jobType is required.
                    traceId: 01JF04ERR1
      x-service: orchestrator
      x-original-path: /jobs
  /orchestrator/jobs/{jobId}:
    get:
      tags:
        - Jobs
      summary: Get job status
      operationId: orchestratorGetJob
      description: Fetch the current status of a job by id.
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Job status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/orchestrator.JobSummary"
              examples:
                sample:
                  value:
                    jobId: job_01JF04ABCD
                    status: queued
                    queue: scan
                    enqueuedAt: 2025-11-18T12:00:00Z
        "404":
          description: Job not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/orchestrator.ErrorEnvelope"
      x-service: orchestrator
      x-original-path: /jobs/{jobId}
  /policy/evaluate:
    post:
      tags:
        - Evaluation
      summary: Evaluate policy for an artifact
      description: Evaluate the active policy version for an artifact and return
        allow/deny decision.
      operationId: policyEvaluate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/policy.EvaluationRequest"
            examples:
              default:
                summary: Evaluate current policy for an artifact
                value:
                  artifactId: registry.stella-ops.local/runtime/api
                  policyVersion: 2025.10.1
                  inputs:
                    tenant: acme
                    branch: main
                    environment: prod
      responses:
        "200":
          description: Evaluation succeeded
          content:
            application/json:
              examples:
                allow:
                  summary: Allow decision with reasons
                  value:
                    decision: allow
                    policyVersion: 2025.10.1
                    traceId: 01JF040XYZ
                    reasons:
                      - signed
                      - within SLO
                    metadata:
                      latencyMs: 42
                    obligations:
                      - record: evidence
                deny:
                  summary: Deny decision with obligations
                  value:
                    decision: deny
                    policyVersion: 2025.10.1
                    traceId: 01JF040DENY
                    reasons:
                      - missing attestation
                      - vulnerable runtime package
                    metadata:
                      latencyMs: 55
                    obligations:
                      - quarantine: true
                      - notify: security-team
              schema:
                $ref: "#/components/schemas/policy.EvaluationResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                missingArtifact:
                  summary: Missing artifactId
                  value:
                    code: policy.invalid_request
                    message: artifactId is required.
                    traceId: 01JF041ERR
      security:
        - OAuthClientCredentials: []
        - BearerAuth: []
      x-service: policy
      x-original-path: /evaluate
  /policy/health:
    get:
      tags:
        - Health
      summary: Liveness probe
      description: Returns OK when the Policy Engine is reachable.
      operationId: policyHealth
      responses:
        "200":
          description: Service is up
          content:
            application/json:
              examples:
                ok:
                  value:
                    status: ok
                    service: policy
                    timestamp: 2025-11-18T00:00:00Z
        "503":
          description: Service unhealthy or dependencies unavailable.
          content:
            application/json:
              examples:
                unhealthy:
                  value:
                    status: degraded
                    service: policy
                    reason: database unavailable
                    timestamp: 2025-11-18T00:00:00Z
      x-service: policy
      x-original-path: /health
  /policy/healthz:
    get:
      summary: Service health
      tags:
        - Meta
      description: Readiness probe for orchestrators.
      operationId: policyHealthz
      responses:
        "200":
          description: Service healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthEnvelope"
              examples:
                ok:
                  summary: Healthy response
                  value:
                    status: ok
                    service: policy
        "503":
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
              examples:
                unavailable:
                  summary: Unhealthy response
                  value:
                    code: service_unavailable
                    message: projector backlog exceeds SLA
                    traceId: "2"
      x-service: policy
      x-original-path: /healthz
  /policy/policies:
    get:
      tags:
        - Policies
      summary: List policies
      description: Returns a paginated list of policy documents filtered by tenant and
        status.
      operationId: policyList
      parameters:
        - $ref: "#/components/parameters/TenantParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/CursorParam"
        - in: query
          name: status
          description: Optional status filter (draft, active, retired)
          schema:
            type: string
            enum:
              - draft
              - active
              - retired
      responses:
        "200":
          description: Policy list page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/policy.PolicyListResponse"
              examples:
                default:
                  summary: First page of active policies
                  value:
                    items:
                      - id: pol-1234
                        name: Critical CVE blocker
                        status: active
                        version: 5
                        tenant: tenant-alpha
                        updatedAt: 2025-11-20T12:00:00Z
                      - id: pol-5678
                        name: Runtime Allowlist
                        status: active
                        version: 2
                        tenant: tenant-alpha
                        updatedAt: 2025-11-18T09:14:00Z
                    pageSize: 50
                    nextPageToken: eyJvZmZzZXQiOiIxMDAifQ==
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
      x-service: policy
      x-original-path: /policies
  /scanner/scans:
    post:
      tags:
        - Scans
      operationId: createScan
      summary: Create a new scan
      description: |
        Initiates a new scan context. Returns a scanId for subsequent
        call graph and evidence submissions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/scanner.CreateScanRequest"
      responses:
        "201":
          description: Scan created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.CreateScanResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
      x-service: scanner
      x-original-path: /scans
  /scanner/scans/{scanId}:
    get:
      tags:
        - Scans
      operationId: getScan
      summary: Get scan status
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      responses:
        "200":
          description: Scan details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.ScanDetails"
        "404":
          $ref: "#/components/responses/NotFound"
      x-service: scanner
      x-original-path: /scans/{scanId}
  /scanner/scans/{scanId}/callgraphs:
    post:
      tags:
        - CallGraphs
      operationId: submitCallGraph
      summary: Submit a call graph
      description: |
        Submits a language-specific call graph for reachability analysis.
        Idempotent: duplicate submissions with same Content-Digest are ignored.
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
        - name: Content-Digest
          in: header
          required: true
          description: SHA-256 digest for idempotency (RFC 9530)
          schema:
            type: string
            example: "sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/scanner.CallGraphV1"
          application/x-ndjson:
            schema:
              type: string
              description: Streaming NDJSON for large graphs
      responses:
        "202":
          description: Call graph accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.CallGraphAcceptedResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          description: Duplicate submission (idempotent success)
        "413":
          description: Call graph too large
      x-service: scanner
      x-original-path: /scans/{scanId}/callgraphs
  /scanner/scans/{scanId}/compute-reachability:
    post:
      tags:
        - Reachability
      operationId: computeReachability
      summary: Trigger reachability computation
      description: |
        Triggers reachability analysis for the scan. Idempotent.
        Computation is asynchronous; poll scan status for completion.
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/scanner.ComputeReachabilityRequest"
      responses:
        "202":
          description: Computation started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.ComputeReachabilityResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          description: Computation already in progress
      x-service: scanner
      x-original-path: /scans/{scanId}/compute-reachability
  /scanner/scans/{scanId}/exports/cdxr:
    get:
      tags:
        - Exports
      operationId: exportCycloneDxReachability
      summary: Export as CycloneDX with reachability extension
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      responses:
        "200":
          description: CycloneDX with reachability
          content:
            application/vnd.cyclonedx+json:
              schema:
                type: object
      x-service: scanner
      x-original-path: /scans/{scanId}/exports/cdxr
  /scanner/scans/{scanId}/exports/openvex:
    get:
      tags:
        - Exports
      operationId: exportOpenVex
      summary: Export as OpenVEX
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      responses:
        "200":
          description: OpenVEX document
          content:
            application/json:
              schema:
                type: object
      x-service: scanner
      x-original-path: /scans/{scanId}/exports/openvex
  /scanner/scans/{scanId}/exports/sarif:
    get:
      tags:
        - Exports
      operationId: exportSarif
      summary: Export findings as SARIF
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      responses:
        "200":
          description: SARIF report
          content:
            application/sarif+json:
              schema:
                type: object
      x-service: scanner
      x-original-path: /scans/{scanId}/exports/sarif
  /scanner/scans/{scanId}/reachability/components:
    get:
      tags:
        - Reachability
      operationId: getReachabilityByComponent
      summary: Get reachability status by component
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
        - name: purl
          in: query
          description: Filter by Package URL
          schema:
            type: string
        - name: status
          in: query
          description: Filter by reachability status
          schema:
            type: string
            enum:
              - reachable
              - unreachable
              - possibly_reachable
              - unknown
      responses:
        "200":
          description: Component reachability results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.ComponentReachabilityList"
      x-service: scanner
      x-original-path: /scans/{scanId}/reachability/components
  /scanner/scans/{scanId}/reachability/explain:
    get:
      tags:
        - Reachability
      operationId: explainReachability
      summary: Explain reachability for CVE/component
      description: |
        Returns detailed explanation of why a CVE affects a component,
        including path witness, evidence chain, and contributing factors.
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
        - name: cve
          in: query
          required: true
          schema:
            type: string
        - name: purl
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Reachability explanation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.ReachabilityExplanation"
        "404":
          description: CVE/component combination not found
      x-service: scanner
      x-original-path: /scans/{scanId}/reachability/explain
  /scanner/scans/{scanId}/reachability/findings:
    get:
      tags:
        - Reachability
      operationId: getReachabilityFindings
      summary: Get vulnerability findings with reachability
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
        - name: cve
          in: query
          description: Filter by CVE ID
          schema:
            type: string
        - name: status
          in: query
          description: Filter by reachability status
          schema:
            type: string
            enum:
              - reachable
              - unreachable
              - possibly_reachable
              - unknown
      responses:
        "200":
          description: Vulnerability findings with reachability
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.ReachabilityFindingList"
      x-service: scanner
      x-original-path: /scans/{scanId}/reachability/findings
  /scanner/scans/{scanId}/runtimeevidence:
    post:
      tags:
        - RuntimeEvidence
      operationId: submitRuntimeEvidence
      summary: Submit runtime evidence
      description: |
        Submits runtime execution evidence (stack traces, loaded modules).
        Merges with existing evidence for the scan.
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/scanner.RuntimeEvidenceV1"
      responses:
        "202":
          description: Evidence accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.RuntimeEvidenceAcceptedResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
      x-service: scanner
      x-original-path: /scans/{scanId}/runtimeevidence
  /scanner/scans/{scanId}/sbom:
    post:
      tags:
        - Scans
      operationId: submitSbom
      summary: Submit SBOM for scan
      description: |
        Associates an SBOM (CycloneDX or SPDX) with the scan.
        Required before reachability computation.
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      requestBody:
        required: true
        content:
          application/vnd.cyclonedx+json:
            schema:
              type: object
          application/spdx+json:
            schema:
              type: object
      responses:
        "202":
          description: SBOM accepted
        "400":
          $ref: "#/components/responses/BadRequest"
      x-service: scanner
      x-original-path: /scans/{scanId}/sbom
  /scanner/scans/{scanId}/spines:
    get:
      tags:
        - ProofSpines
      operationId: getSpinesByScan
      summary: List proof spines for a scan
      parameters:
        - $ref: "#/components/parameters/ScanIdPath"
      responses:
        "200":
          description: Proof spines for scan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.ProofSpineList"
      x-service: scanner
      x-original-path: /scans/{scanId}/spines
  /scanner/spines/{spineId}:
    get:
      tags:
        - ProofSpines
      operationId: getSpine
      summary: Get a proof spine
      description: Returns full spine with all segments and verification status.
      parameters:
        - name: spineId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Proof spine details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scanner.ProofSpine"
        "404":
          $ref: "#/components/responses/NotFound"
      x-service: scanner
      x-original-path: /spines/{spineId}
  /scheduler/health:
    get:
      tags:
        - Health
      summary: Liveness probe
      description: Returns OK when Scheduler is reachable.
      operationId: schedulerHealth
      responses:
        "200":
          description: Service is up
          content:
            application/json:
              examples:
                ok:
                  value:
                    status: ok
                    service: scheduler
                    timestamp: 2025-11-18T00:00:00Z
        "503":
          description: Service unhealthy or dependencies unavailable.
          content:
            application/json:
              examples:
                unhealthy:
                  value:
                    status: degraded
                    service: scheduler
                    reason: queue not reachable
                    timestamp: 2025-11-18T00:00:00Z
      x-service: scheduler
      x-original-path: /health
  /scheduler/healthz:
    get:
      summary: Service health
      tags:
        - Meta
      description: Readiness probe for queue connectivity.
      operationId: schedulerHealthz
      responses:
        "200":
          description: Service healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scheduler.HealthEnvelope"
              examples:
                ok:
                  summary: Healthy response
                  value:
                    status: ok
                    service: scheduler
        "503":
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scheduler.ErrorEnvelope"
              examples:
                unavailable:
                  summary: Unhealthy response
                  value:
                    code: service_unavailable
                    message: queue backlog exceeds threshold
                    traceId: "4"
      x-service: scheduler
      x-original-path: /healthz
  /scheduler/queues/{name}:
    get:
      tags:
        - Queues
      summary: Get queue status
      description: Returns depth, inflight, and age metrics for a queue.
      operationId: schedulerGetQueueStatus
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          example: default
      responses:
        "200":
          description: Queue status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scheduler.QueueStatus"
              examples:
                status:
                  summary: Queue depth snapshot
                  value:
                    name: default
                    depth: 12
                    inflight: 2
                    oldestAgeSeconds: 45
                    updatedAt: 2025-11-18T12:00:00Z
                empty:
                  summary: Empty queue
                  value:
                    name: export
                    depth: 0
                    inflight: 0
                    oldestAgeSeconds: 0
                    updatedAt: 2025-11-18T12:05:00Z
        "404":
          description: Queue not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/scheduler.ErrorEnvelope"
              examples:
                notFound:
                  summary: Queue missing
                  value:
                    code: scheduler.queue_not_found
                    message: Queue default not found.
                    traceId: 01JF04NF2
      x-service: scheduler
      x-original-path: /queues/{name}
components:
  schemas:
    BreakingChange:
      type: object
      description: Description of a breaking change between deprecated and successor
        endpoints.
      required:
        - type
        - description
      properties:
        type:
          type: string
          enum:
            - parameter-removed
            - parameter-renamed
            - parameter-type-changed
            - response-schema-changed
            - header-removed
            - header-renamed
            - status-code-changed
            - content-type-changed
            - authentication-changed
          description: Category of the breaking change.
        path:
          type: string
          description: JSON path to the affected element.
          example: $.parameters[0].name
        description:
          type: string
          description: Human-readable description of the change.
          example: Parameter 'page' renamed to 'cursor'
        migrationAction:
          type: string
          description: Recommended action for consumers.
          example: Replace 'page' parameter with 'cursor' using the nextCursor value from
            previous response.
    DeprecationMetadata:
      type: object
      description: >
        Deprecation metadata for API endpoints. Applied as x-deprecation
        extension

        on operation objects. Used by Spectral rules, changelog generation, and

        notification templates.
      required:
        - deprecatedAt
        - sunsetAt
        - successorPath
        - reason
      properties:
        deprecatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the endpoint was marked deprecated.
          example: 2025-01-15T00:00:00Z
        sunsetAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the endpoint will be removed.
          example: 2025-07-15T00:00:00Z
        successorPath:
          type: string
          description: Path to the replacement endpoint (if available).
          example: /v2/resources
        successorOperationId:
          type: string
          description: Operation ID of the replacement endpoint.
          example: getResourcesV2
        reason:
          type: string
          description: Human-readable explanation for the deprecation.
          example: Replaced by paginated v2 endpoint with cursor-based pagination.
        migrationGuide:
          type: string
          format: uri
          description: URL to migration documentation.
          example: https://docs.stella-ops.org/migration/resources-v2
        notificationChannels:
          type: array
          description: Notification channels for deprecation announcements.
          items:
            type: string
            enum:
              - slack
              - teams
              - email
              - webhook
          default:
            - email
        affectedConsumerHints:
          type: array
          description: Hints about affected consumers (e.g., SDK names, client IDs).
          items:
            type: string
        breakingChanges:
          type: array
          description: List of breaking changes in the successor endpoint.
          items:
            $ref: "#/schemas/BreakingChange"
    DeprecationNotificationEvent:
      type: object
      description: Event payload for deprecation notifications sent to Notify service.
      required:
        - eventId
        - eventType
        - timestamp
        - tenantId
        - deprecation
      properties:
        eventId:
          type: string
          format: uuid
          description: Unique identifier for this notification event.
        eventType:
          type: string
          const: api.deprecation.announced
          description: Event type for routing in Notify service.
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event was generated.
        tenantId:
          type: string
          description: Tenant scope for the notification.
        deprecation:
          $ref: "#/schemas/DeprecationSummary"
    DeprecationReport:
      type: object
      description: Aggregated report of all deprecations for changelog/SDK publishing.
      required:
        - generatedAt
        - schemaVersion
        - deprecations
      properties:
        generatedAt:
          type: string
          format: date-time
          description: When this report was generated.
        schemaVersion:
          type: string
          const: api.deprecation.report@1
        totalCount:
          type: integer
          description: Total number of deprecated endpoints.
        upcomingSunsets:
          type: integer
          description: Number of endpoints with sunset within 90 days.
        deprecations:
          type: array
          items:
            $ref: "#/schemas/DeprecationSummary"
    DeprecationSummary:
      type: object
      description: Summary of a deprecated endpoint for notification purposes.
      required:
        - service
        - path
        - method
        - deprecatedAt
        - sunsetAt
      properties:
        service:
          type: string
          description: Service name owning the deprecated endpoint.
          example: authority
        path:
          type: string
          description: API path of the deprecated endpoint.
          example: /v1/tokens
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
            - HEAD
            - OPTIONS
          description: HTTP method of the deprecated endpoint.
        operationId:
          type: string
          description: OpenAPI operation ID.
          example: createToken
        deprecatedAt:
          type: string
          format: date-time
        sunsetAt:
          type: string
          format: date-time
        daysUntilSunset:
          type: integer
          description: Computed days remaining until sunset.
          example: 180
        successorPath:
          type: string
          description: Path to the replacement endpoint.
        reason:
          type: string
          description: Deprecation reason.
        migrationGuide:
          type: string
          format: uri
        changelogUrl:
          type: string
          format: uri
          description: URL to the API changelog entry for this deprecation.
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: service_unavailable
        message:
          type: string
        traceId:
          type: string
          description: Correlation identifier for troubleshooting
    HealthEnvelope:
      type: object
      required:
        - status
        - service
      properties:
        status:
          type: string
          example: ok
        service:
          type: string
          example: any-service
    PageMetadata:
      type: object
      required:
        - hasMore
      properties:
        hasMore:
          type: boolean
          description: Indicates if additional pages are available.
        nextCursor:
          type: string
          description: Cursor to fetch the next page.
        previousCursor:
          type: string
          description: Cursor to fetch the previous page.
    authority.AuthorizationCodeGrantRequest:
      type: object
      description: Form-encoded payload for authorization code exchange.
      required:
        - grant_type
        - code
        - redirect_uri
        - code_verifier
      properties:
        grant_type:
          type: string
          const: authorization_code
        client_id:
          type: string
        client_secret:
          type: string
          description: Optional when HTTP Basic auth is used.
        code:
          type: string
        redirect_uri:
          type: string
          format: uri
        code_verifier:
          type: string
    authority.ClientCredentialsGrantRequest:
      type: object
      required:
        - grant_type
        - client_id
      properties:
        grant_type:
          type: string
          const: client_credentials
        client_id:
          type: string
          description: Registered client identifier. May also be supplied via HTTP Basic
            auth.
        client_secret:
          type: string
          description: Client secret. Required for confidential clients when not using
            HTTP Basic auth.
        scope:
          type: string
          description: Space-delimited scopes being requested.
        authority_provider:
          type: string
          description: Optional identity provider hint for plugin-backed clients.
        operator_reason:
          type: string
          description: Required when requesting `orch:operate`; explains the operator
            action.
          maxLength: 256
        operator_ticket:
          type: string
          description: Required when requesting `orch:operate`; tracks the external change
            ticket or incident.
          maxLength: 128
      description: Form-encoded payload for client credentials exchange.
    authority.IntrospectionRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: Token value whose state should be introspected.
        token_type_hint:
          type: string
          description: Optional token type hint (`access_token` or `refresh_token`).
      description: Form-encoded payload for token introspection.
    authority.IntrospectionResponse:
      type: object
      description: Active token descriptor compliant with RFC 7662.
      properties:
        active:
          type: boolean
          description: Indicates whether the token is currently active.
        scope:
          type: string
          description: Space-delimited list of scopes granted to the token.
        client_id:
          type: string
          description: Client identifier associated with the token.
        sub:
          type: string
          description: Subject identifier when the token represents an end-user.
        username:
          type: string
          description: Preferred username associated with the subject.
        token_type:
          type: string
          description: Type of the token (e.g., `Bearer`).
        exp:
          type: integer
          description: Expiration timestamp (seconds since UNIX epoch).
        iat:
          type: integer
          description: Issued-at timestamp (seconds since UNIX epoch).
        nbf:
          type: integer
          description: Not-before timestamp (seconds since UNIX epoch).
        aud:
          type: array
          description: Audience values associated with the token.
          items:
            type: string
        iss:
          type: string
          description: Issuer identifier.
        jti:
          type: string
          description: JWT identifier corresponding to the token.
        tenant:
          type: string
          description: Tenant associated with the token, when assigned.
        confirmation:
          type: object
          description: Sender-constrained confirmation data (e.g., mTLS thumbprint, DPoP
            JWK thumbprint).
      required:
        - active
    authority.Jwk:
      type: object
      description: Public key material for token signature validation.
      properties:
        kid:
          type: string
          description: Key identifier.
        kty:
          type: string
          description: Key type (e.g., `EC`, `RSA`).
        use:
          type: string
          description: Intended key use (`sig`).
        alg:
          type: string
          description: Signing algorithm (e.g., `ES384`).
        crv:
          type: string
          description: Elliptic curve identifier when applicable.
        x:
          type: string
          description: X coordinate for EC keys.
        y:
          type: string
          description: Y coordinate for EC keys.
        status:
          type: string
          description: Operational status metadata for the key (e.g., `active`, `retiring`).
    authority.JwksDocument:
      type: object
      description: JSON Web Key Set published by the Authority.
      properties:
        keys:
          type: array
          items:
            $ref: "#/components/schemas/authority.Jwk"
      required:
        - keys
    authority.OAuthErrorResponse:
      type: object
      description: RFC 6749 compliant error envelope.
      properties:
        error:
          type: string
          description: Machine-readable error code.
        error_description:
          type: string
          description: Human-readable error description.
        error_uri:
          type: string
          format: uri
          description: Link to documentation about the error.
      required:
        - error
    authority.PasswordGrantRequest:
      type: object
      required:
        - grant_type
        - client_id
        - username
        - password
      properties:
        grant_type:
          type: string
          const: password
        client_id:
          type: string
          description: Registered client identifier. May also be supplied via HTTP Basic
            auth.
        client_secret:
          type: string
          description: Client secret. Required for confidential clients when not using
            HTTP Basic auth.
        scope:
          type: string
          description: Space-delimited scopes being requested.
        username:
          type: string
          description: Resource owner username.
        password:
          type: string
          description: Resource owner password.
        authority_provider:
          type: string
          description: Optional identity provider hint. Required when multiple
            password-capable providers are registered.
      description: Form-encoded payload for password grant exchange.
    authority.RefreshTokenGrantRequest:
      type: object
      required:
        - grant_type
        - refresh_token
      properties:
        grant_type:
          type: string
          const: refresh_token
        client_id:
          type: string
          description: Registered client identifier. May also be supplied via HTTP Basic
            auth.
        client_secret:
          type: string
          description: Client secret. Required for confidential clients when not using
            HTTP Basic auth.
        refresh_token:
          type: string
          description: Previously issued refresh token.
        scope:
          type: string
          description: Optional scope list to narrow the requested access.
      description: Form-encoded payload for refresh token exchange.
    authority.RevocationRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: Token value or token identifier to revoke.
        token_type_hint:
          type: string
          description: Optional token type hint (`access_token` or `refresh_token`).
      description: Form-encoded payload for token revocation.
    authority.TokenResponse:
      type: object
      description: OAuth 2.1 bearer token response.
      properties:
        access_token:
          type: string
          description: Access token encoded as JWT.
        token_type:
          type: string
          description: Token type indicator. Always `Bearer`.
        expires_in:
          type: integer
          description: Lifetime of the access token, in seconds.
          minimum: 1
        refresh_token:
          type: string
          description: Refresh token issued when the grant allows offline access.
        scope:
          type: string
          description: Space-delimited scopes granted in the response.
        id_token:
          type: string
          description: ID token issued for authorization-code flows.
      required:
        - access_token
        - token_type
        - expires_in
    export-center.BundleManifest:
      type: object
      required:
        - bundleId
        - contents
      properties:
        bundleId:
          type: string
        contents:
          type: array
          items:
            type: object
            required:
              - type
              - digest
            properties:
              type:
                type: string
                example: advisory
              digest:
                type: string
                example: sha256:abc123
        createdAt:
          type: string
          format: date-time
    export-center.BundleSummary:
      type: object
      required:
        - bundleId
        - createdAt
        - status
      properties:
        bundleId:
          type: string
        createdAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - ready
            - building
            - failed
        sizeBytes:
          type: integer
    export-center.HealthResponse:
      $ref: "#/components/schemas/HealthEnvelope"
    graph.ErrorEnvelope:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        traceId:
          type: string
      required:
        - code
        - message
    graph.GraphNodePage:
      type: object
      required:
        - nodes
        - metadata
      properties:
        nodes:
          type: array
          items:
            type: object
            required:
              - id
              - kind
              - label
            properties:
              id:
                type: string
              kind:
                type: string
              label:
                type: string
        metadata:
          $ref: "#/components/schemas/PageMetadata"
    graph.GraphStatus:
      type: object
      required:
        - graphId
        - status
      properties:
        graphId:
          type: string
        status:
          type: string
          enum:
            - building
            - ready
            - failed
        builtAt:
          type: string
          format: date-time
    graph.HealthEnvelope:
      type: object
      properties:
        status:
          type: string
        service:
          type: string
      required:
        - status
        - service
    orchestrator.ErrorEnvelope:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        traceId:
          type: string
      required:
        - code
        - message
    orchestrator.JobCreateRequest:
      type: object
      required:
        - kind
        - payload
      properties:
        kind:
          type: string
          description: Job kind identifier.
        payload:
          type: object
          description: Job payload (kind-specific fields).
        priority:
          type: string
          enum:
            - low
            - normal
            - high
        tenant:
          type: string
    orchestrator.JobCreateResponse:
      type: object
      required:
        - jobId
        - status
      properties:
        jobId:
          type: string
        status:
          type: string
        queue:
          type: string
        enqueuedAt:
          type: string
          format: date-time
    orchestrator.JobSummary:
      type: object
      required:
        - jobId
        - status
        - queue
        - enqueuedAt
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - failed
            - completed
        queue:
          type: string
        enqueuedAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        tenant:
          type: string
    policy.EvaluationRequest:
      type: object
      required:
        - artifactId
      properties:
        artifactId:
          type: string
          example: registry.stella-ops.local/runtime/api
        policyVersion:
          type: string
          example: 2025.10.1
        inputs:
          type: object
    policy.EvaluationResponse:
      type: object
      required:
        - decision
      properties:
        decision:
          type: string
          enum:
            - allow
            - deny
        policyVersion:
          type: string
        traceId:
          type: string
        reasons:
          type: array
          items:
            type: string
        obligations:
          type: array
          items:
            type: object
        cacheHit:
          type: boolean
          description: Whether the decision was served from cache.
        cacheSource:
          type: string
          enum:
            - none
            - inMemory
            - redis
          description: Source of cached data (none for fresh computation, inMemory for L1 cache, redis for Provcache L2).
        executionTimeMs:
          type: integer
          description: Time taken to evaluate the policy in milliseconds.
    provcache.TrustScoreComponent:
      type: object
      required:
        - score
        - weight
      properties:
        score:
          type: integer
          minimum: 0
          maximum: 100
          description: Component score (0-100).
        weight:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Weight of this component in the total score (0.0-1.0).
    provcache.TrustScoreBreakdown:
      type: object
      required:
        - reachability
        - sbomCompleteness
        - vexCoverage
        - policyFreshness
        - signerTrust
      properties:
        reachability:
          $ref: '#/components/schemas/provcache.TrustScoreComponent'
          description: Reachability evidence contribution (weight 25%).
        sbomCompleteness:
          $ref: '#/components/schemas/provcache.TrustScoreComponent'
          description: SBOM completeness contribution (weight 20%).
        vexCoverage:
          $ref: '#/components/schemas/provcache.TrustScoreComponent'
          description: VEX statement coverage contribution (weight 20%).
        policyFreshness:
          $ref: '#/components/schemas/provcache.TrustScoreComponent'
          description: Policy freshness contribution (weight 15%).
        signerTrust:
          $ref: '#/components/schemas/provcache.TrustScoreComponent'
          description: Signer trust contribution (weight 20%).
    provcache.ReplaySeed:
      type: object
      required:
        - feedIds
        - ruleIds
      properties:
        feedIds:
          type: array
          items:
            type: string
          description: Advisory feed identifiers used in evaluation.
        ruleIds:
          type: array
          items:
            type: string
          description: Policy rule identifiers used in evaluation.
        frozenEpoch:
          type: string
          format: date-time
          description: Optional frozen epoch timestamp for deterministic replay.
    provcache.DecisionDigest:
      type: object
      required:
        - digestVersion
        - veriKey
        - verdictHash
        - proofRoot
        - replaySeed
        - createdAt
        - expiresAt
        - trustScore
      properties:
        digestVersion:
          type: string
          description: Schema version of this digest format.
          example: v1
        veriKey:
          type: string
          description: Composite cache key that uniquely identifies the provenance decision context.
          example: sha256:abc123...
        verdictHash:
          type: string
          description: Hash of sorted dispositions from the evaluation result.
        proofRoot:
          type: string
          description: Merkle root of all evidence chunks used in this decision.
        replaySeed:
          $ref: '#/components/schemas/provcache.ReplaySeed'
        createdAt:
          type: string
          format: date-time
          description: UTC timestamp when this digest was created.
        expiresAt:
          type: string
          format: date-time
          description: UTC timestamp when this digest expires.
        trustScore:
          type: integer
          minimum: 0
          maximum: 100
          description: Composite trust score (0-100) indicating decision confidence.
        trustScoreBreakdown:
          $ref: '#/components/schemas/provcache.TrustScoreBreakdown'
          description: Breakdown of trust score by component.
    policy.PolicyListResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              status:
                type: string
              version:
                type: integer
              tenant:
                type: string
              updatedAt:
                type: string
                format: date-time
        pageSize:
          type: integer
        nextPageToken:
          type: string
    scanner.CallGraphAcceptedResponse:
      type: object
      properties:
        callgraphId:
          type: string
        nodeCount:
          type: integer
        edgeCount:
          type: integer
        digest:
          type: string
    scanner.CallGraphArtifact:
      type: object
      properties:
        artifactKey:
          type: string
        kind:
          type: string
          enum:
            - assembly
            - jar
            - module
            - binary
        sha256:
          type: string
        purl:
          type: string
    scanner.CallGraphEdge:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          description: Source node ID
        to:
          type: string
          description: Target node ID
        kind:
          type: string
          enum:
            - static
            - heuristic
          default: static
        reason:
          type: string
          enum:
            - direct_call
            - virtual_call
            - reflection_string
            - di_binding
            - dynamic_import
            - unknown
        weight:
          type: number
          default: 1
    scanner.CallGraphEntrypoint:
      type: object
      required:
        - nodeId
        - kind
      properties:
        nodeId:
          type: string
        kind:
          type: string
          enum:
            - http
            - grpc
            - cli
            - job
            - event
            - unknown
        route:
          type: string
          description: HTTP route pattern (e.g., /api/orders/{id})
        framework:
          type: string
          enum:
            - aspnetcore
            - minimalapi
            - spring
            - express
            - fastapi
            - unknown
    scanner.CallGraphNode:
      type: object
      required:
        - nodeId
        - symbolKey
      properties:
        nodeId:
          type: string
        artifactKey:
          type: string
        symbolKey:
          type: string
          description: Canonical symbol key (Namespace.Type::Method(signature))
        visibility:
          type: string
          enum:
            - public
            - internal
            - private
            - unknown
        isEntrypointCandidate:
          type: boolean
          default: false
    scanner.CallGraphV1:
      type: object
      required:
        - schema
        - scanKey
        - language
        - nodes
        - edges
      properties:
        schema:
          type: string
          const: stella.callgraph.v1
        scanKey:
          type: string
          format: uuid
        language:
          type: string
          enum:
            - dotnet
            - java
            - node
            - python
            - go
            - rust
            - binary
            - ruby
            - php
        artifacts:
          type: array
          items:
            $ref: "#/components/schemas/scanner.CallGraphArtifact"
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/scanner.CallGraphNode"
        edges:
          type: array
          items:
            $ref: "#/components/schemas/scanner.CallGraphEdge"
        entrypoints:
          type: array
          items:
            $ref: "#/components/schemas/scanner.CallGraphEntrypoint"
    scanner.ComponentReachability:
      type: object
      properties:
        purl:
          type: string
        status:
          type: string
          enum:
            - reachable
            - unreachable
            - possibly_reachable
            - unknown
        confidence:
          type: number
        latticeState:
          type: string
        why:
          type: array
          items:
            type: string
    scanner.ComponentReachabilityList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/scanner.ComponentReachability"
        total:
          type: integer
    scanner.ComputeReachabilityRequest:
      type: object
      properties:
        forceRecompute:
          type: boolean
          default: false
        entrypoints:
          type: array
          items:
            type: string
          description: Override auto-detected entrypoints
        targets:
          type: array
          items:
            type: string
          description: Specific symbols to analyze
    scanner.ComputeReachabilityResponse:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
            - queued
            - processing
        estimatedDuration:
          type: string
          description: ISO-8601 duration estimate
    scanner.CreateScanRequest:
      type: object
      required:
        - artifactDigest
      properties:
        artifactDigest:
          type: string
          description: Image or artifact digest (sha256:...)
        repoUri:
          type: string
        commitSha:
          type: string
        policyProfileId:
          type: string
        metadata:
          type: object
          additionalProperties: true
    scanner.CreateScanResponse:
      type: object
      properties:
        scanId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - created
            - pending
            - processing
            - completed
            - failed
        createdAt:
          type: string
          format: date-time
    scanner.ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: object
    scanner.EvidenceChain:
      type: object
      properties:
        staticAnalysis:
          type: object
          properties:
            callgraphDigest:
              type: string
            pathLength:
              type: integer
            edgeTypes:
              type: array
              items:
                type: string
        runtimeEvidence:
          type: object
          properties:
            observed:
              type: boolean
            hitCount:
              type: integer
            lastObserved:
              type: string
              format: date-time
        policyEvaluation:
          type: object
          properties:
            policyDigest:
              type: string
            verdict:
              type: string
            verdictReason:
              type: string
    scanner.ExplanationReason:
      type: object
      properties:
        code:
          type: string
        description:
          type: string
        impact:
          type: number
    scanner.LoadedArtifact:
      type: object
      properties:
        artifactKey:
          type: string
        evidence:
          type: string
          enum:
            - loaded_module
            - mapped_file
            - jar_loaded
    scanner.ProofSegment:
      type: object
      properties:
        segmentId:
          type: string
        segmentType:
          type: string
          enum:
            - SBOM_SLICE
            - MATCH
            - REACHABILITY
            - GUARD_ANALYSIS
            - RUNTIME_OBSERVATION
            - POLICY_EVAL
        index:
          type: integer
        inputHash:
          type: string
        resultHash:
          type: string
        prevSegmentHash:
          type: string
        toolId:
          type: string
        toolVersion:
          type: string
        status:
          type: string
          enum:
            - pending
            - verified
            - partial
            - invalid
            - untrusted
        createdAt:
          type: string
          format: date-time
    scanner.ProofSpine:
      type: object
      properties:
        spineId:
          type: string
        artifactId:
          type: string
        vulnerabilityId:
          type: string
        policyProfileId:
          type: string
        verdict:
          type: string
        verdictReason:
          type: string
        rootHash:
          type: string
        scanRunId:
          type: string
        segments:
          type: array
          items:
            $ref: "#/components/schemas/scanner.ProofSegment"
        createdAt:
          type: string
          format: date-time
        supersededBySpineId:
          type: string
    scanner.ProofSpineList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/scanner.ProofSpineSummary"
        total:
          type: integer
    scanner.ProofSpineSummary:
      type: object
      properties:
        spineId:
          type: string
        artifactId:
          type: string
        vulnerabilityId:
          type: string
        verdict:
          type: string
        segmentCount:
          type: integer
        createdAt:
          type: string
          format: date-time
    scanner.ReachabilityExplanation:
      type: object
      properties:
        cveId:
          type: string
        purl:
          type: string
        status:
          type: string
        confidence:
          type: number
        latticeState:
          type: string
        pathWitness:
          type: array
          items:
            type: string
          description: Symbol path from entrypoint to vulnerable code
        why:
          type: array
          items:
            $ref: "#/components/schemas/scanner.ExplanationReason"
        evidence:
          $ref: "#/components/schemas/scanner.EvidenceChain"
        spineId:
          type: string
          description: Reference to ProofSpine for full audit trail
    scanner.ReachabilityFinding:
      type: object
      properties:
        cveId:
          type: string
        purl:
          type: string
        status:
          type: string
        confidence:
          type: number
        latticeState:
          type: string
        severity:
          type: string
        affectedVersions:
          type: string
    scanner.ReachabilityFindingList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/scanner.ReachabilityFinding"
        total:
          type: integer
    scanner.RuntimeEnvironment:
      type: object
      properties:
        os:
          type: string
        k8s:
          type: object
          properties:
            namespace:
              type: string
            pod:
              type: string
            container:
              type: string
        imageDigest:
          type: string
        buildId:
          type: string
    scanner.RuntimeEvidenceAcceptedResponse:
      type: object
      properties:
        evidenceId:
          type: string
        sampleCount:
          type: integer
        loadedArtifactCount:
          type: integer
    scanner.RuntimeEvidenceV1:
      type: object
      required:
        - schema
        - scanKey
        - collectedAt
      properties:
        schema:
          type: string
          const: stella.runtimeevidence.v1
        scanKey:
          type: string
          format: uuid
        collectedAt:
          type: string
          format: date-time
        environment:
          $ref: "#/components/schemas/scanner.RuntimeEnvironment"
        samples:
          type: array
          items:
            $ref: "#/components/schemas/scanner.RuntimeSample"
        loadedArtifacts:
          type: array
          items:
            $ref: "#/components/schemas/scanner.LoadedArtifact"
    scanner.RuntimeSample:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        pid:
          type: integer
        threadId:
          type: integer
        frames:
          type: array
          items:
            type: string
          description: Array of node IDs representing call stack
        sampleWeight:
          type: number
          default: 1
    scanner.ScanDetails:
      type: object
      properties:
        scanId:
          type: string
        status:
          type: string
        artifactDigest:
          type: string
        callGraphCount:
          type: integer
        runtimeEvidenceCount:
          type: integer
        reachabilityStatus:
          type: string
          enum:
            - pending
            - computing
            - completed
            - failed
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
    scheduler.ErrorEnvelope:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        traceId:
          type: string
      required:
        - code
        - message
    scheduler.HealthEnvelope:
      type: object
      properties:
        status:
          type: string
        service:
          type: string
      required:
        - status
        - service
    scheduler.QueueStatus:
      type: object
      required:
        - name
        - depth
        - inflight
        - updatedAt
      properties:
        name:
          type: string
        depth:
          type: integer
        inflight:
          type: integer
        oldestAgeSeconds:
          type: integer
        updatedAt:
          type: string
          format: date-time
  parameters:
    CursorParam:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      example: eyJyIjoiMjAyNS0xMS0xOC0wMDIifQ
    LimitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
      example: 50
    TenantParam:
      name: tenant
      in: query
      required: false
      schema:
        type: string
      description: Filter results to a specific tenant identifier.
      example: acme
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ClientSecretBasic:
      type: http
      scheme: basic
      description: HTTP Basic authentication with `client_id` and `client_secret`.
    OAuthClientCredentials:
      type: oauth2
      description: OAuth 2.1 client credentials flow scoped per service.
      flows:
        clientCredentials:
          tokenUrl: /token
          scopes: {}
    OAuthPassword:
      type: oauth2
      description: Resource owner password exchange for Authority-managed identities.
      flows:
        password:
          tokenUrl: /token
          refreshUrl: /token
          scopes:
            attestor.write: Submit attestation bundles and Rekor entries.
            attestor.verify: Invoke attestation verification APIs.
            attestor.read: Fetch attestation entries and proofs.
            advisory:ingest: Submit advisory ingestion payloads.
            advisory:read: Read advisory ingestion data.
            advisory-ai:view: View Advisory AI artefacts and cached outputs.
            advisory-ai:operate: Submit Advisory AI inference and remediation requests.
            advisory-ai:admin: Administer Advisory AI configuration, profiles, and remote
              execution.
            aoc:verify: Execute Aggregation-Only Contract verification workflows.
            airgap:seal: Seal or unseal an air-gapped installation.
            airgap:import: Import offline bundles and mirror artifacts while air-gapped.
            airgap:status:read: Read air-gap sealing status and staleness indicators.
            obs:read: Read observability dashboards, SLO digests, and incident overlays.
            timeline:read: Read incident timeline entries and annotations.
            timeline:write: Append deterministic incident timeline events and annotations.
            evidence:create: Create evidence items, upload artefacts, and link attestations.
            evidence:read: Read evidence items, artefacts, and linkage metadata.
            evidence:hold: Apply or release legal holds on evidence items.
            attest:read: Read attestation records, DSSE bundles, and verification proofs.
            obs:incident: Toggle incident mode, extend retention, enable emergency telemetry.
            authority.audit.read: Read Authority audit logs.
            authority.clients.manage: Manage Authority client registrations.
            authority.users.manage: Manage Authority users.
            authority:tenants.read: Read the Authority tenant catalog.
            concelier.jobs.trigger: Trigger Concelier aggregation jobs.
            concelier.merge: Manage Concelier merge operations.
            effective:write: Write effective findings (Policy Engine service identity only).
            email: Access email claim data.
            exceptions:approve: Approve exception workflows.
            findings:read: Read effective findings emitted by Policy Engine.
            graph:export: Export graph artefacts.
            graph:read: Read graph explorer data.
            graph:simulate: Run graph what-if simulations.
            graph:write: Enqueue or mutate graph build jobs.
            offline_access: Request refresh tokens for offline access.
            openid: Request OpenID Connect identity tokens.
            orch:operate: Execute privileged Orchestrator control actions.
            orch:read: Read Orchestrator job state.
            packs.read: Read Task Pack definitions and execution history.
            packs.write: Publish or update Task Packs in the registry.
            packs.run: Execute Task Packs via Task Runner workflows.
            packs.approve: Approve Task Pack gates and resume pending runs.
            policy:author: Author Policy Studio drafts and workspaces.
            policy:activate: Activate policy revisions.
            policy:approve: Approve or reject policy drafts.
            policy:audit: Inspect Policy Studio audit history.
            policy:edit: Edit policy definitions.
            policy:operate: Operate Policy Studio promotions and runs.
            policy:read: Read policy definitions and metadata.
            policy:run: Trigger policy executions.
            policy:submit: Submit policy drafts for review.
            policy:review: Review Policy Studio drafts and leave feedback.
            policy:simulate: Execute Policy Studio simulations.
            policy:write: Create or update policy drafts.
            profile: Access profile claim data.
            signals:admin: Administer Signals ingestion and routing settings.
            signals:read: Read Signals events and state.
            signals:write: Publish Signals events or mutate state.
            stellaops.bypass: Bypass trust boundary protections (restricted identities only).
            ui.read: Read Console UX resources.
            vex:ingest: Submit VEX ingestion payloads.
            vex:read: Read VEX ingestion data.
            vuln:view: Read vulnerability overlays and issue permalinks.
            vuln:investigate: Perform vulnerability triage actions (assign, comment, annotate).
            vuln:operate: Execute vulnerability workflow transitions and remediation tasks.
            vuln:audit: Access vulnerability audit ledgers and exports.
            vuln:read: Read vulnerability permalinks and overlays. (legacy compatibility;
              prefer vuln:view)
        authorizationCode:
          authorizationUrl: /authorize
          tokenUrl: /token
          refreshUrl: /token
          scopes:
            attestor.write: Submit attestation bundles and Rekor entries.
            attestor.verify: Invoke attestation verification APIs.
            attestor.read: Fetch attestation entries and proofs.
            advisory:ingest: Submit advisory ingestion payloads.
            advisory:read: Read advisory ingestion data.
            advisory-ai:view: View Advisory AI artefacts and cached outputs.
            advisory-ai:operate: Submit Advisory AI inference and remediation requests.
            advisory-ai:admin: Administer Advisory AI configuration, profiles, and remote
              execution.
            aoc:verify: Execute Aggregation-Only Contract verification workflows.
            airgap:seal: Seal or unseal an air-gapped installation.
            airgap:import: Import offline bundles and mirror artifacts while air-gapped.
            airgap:status:read: Read air-gap sealing status and staleness indicators.
            obs:read: Read observability dashboards, SLO digests, and incident overlays.
            timeline:read: Read incident timeline entries and annotations.
            timeline:write: Append deterministic incident timeline events and annotations.
            evidence:create: Create evidence items, upload artefacts, and link attestations.
            evidence:read: Read evidence items, artefacts, and linkage metadata.
            evidence:hold: Apply or release legal holds on evidence items.
            attest:read: Read attestation records, DSSE bundles, and verification proofs.
            obs:incident: Toggle incident mode, extend retention, enable emergency telemetry.
            authority.audit.read: Read Authority audit logs.
            authority.clients.manage: Manage Authority client registrations.
            authority.users.manage: Manage Authority users.
            authority:tenants.read: Read the Authority tenant catalog.
            concelier.jobs.trigger: Trigger Concelier aggregation jobs.
            concelier.merge: Manage Concelier merge operations.
            effective:write: Write effective findings (Policy Engine service identity only).
            email: Access email claim data.
            exceptions:approve: Approve exception workflows.
            findings:read: Read effective findings emitted by Policy Engine.
            graph:export: Export graph artefacts.
            graph:read: Read graph explorer data.
            graph:simulate: Run graph what-if simulations.
            graph:write: Enqueue or mutate graph build jobs.
            offline_access: Request refresh tokens for offline access.
            openid: Request OpenID Connect identity tokens.
            orch:operate: Execute privileged Orchestrator control actions.
            orch:read: Read Orchestrator job state.
            policy:author: Author Policy Studio drafts and workspaces.
            policy:activate: Activate policy revisions.
            policy:approve: Approve or reject policy drafts.
            policy:audit: Inspect Policy Studio audit history.
            policy:edit: Edit policy definitions.
            policy:operate: Operate Policy Studio promotions and runs.
            policy:read: Read policy definitions and metadata.
            policy:run: Trigger policy executions.
            policy:submit: Submit policy drafts for review.
            policy:review: Review Policy Studio drafts and leave feedback.
            policy:simulate: Execute Policy Studio simulations.
            policy:write: Create or update policy drafts.
            profile: Access profile claim data.
            signals:admin: Administer Signals ingestion and routing settings.
            signals:read: Read Signals events and state.
            signals:write: Publish Signals events or mutate state.
            stellaops.bypass: Bypass trust boundary protections (restricted identities only).
            ui.read: Read Console UX resources.
            vex:ingest: Submit VEX ingestion payloads.
            vex:read: Read VEX ingestion data.
            vuln:view: Read vulnerability overlays and issue permalinks.
            vuln:investigate: Perform vulnerability triage actions (assign, comment, annotate).
            vuln:operate: Execute vulnerability workflow transitions and remediation tasks.
            vuln:audit: Access vulnerability audit ledgers and exports.
            vuln:read: Read vulnerability permalinks and overlays. (legacy compatibility;
              prefer vuln:view)
  responses:
    ErrorResponse:
      description: Error envelope
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - message
            properties:
              code:
                type: string
              message:
                type: string
              traceId:
                type: string