openapi: 3.1.0
info:
  title: Oak Chain Ops API
  version: 1.0.0
  summary: Canonical upstream `/ops/v1/*` contract published by `oak-chain-edge-worker`.
  description: |
    This spec documents the edge-owned `/ops/v1/*` contract exposed by `oak-chain-edge-worker`.
    The adapter composes or proxies governed validator source routes from `jackrabbit-oak`.
    It is the only canonical non-local upstream product contract.

    For validator-native source routes, use `/openapi-validator-source.yaml`.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://127.0.0.1:8787
    description: Local ops adapter or mock server.
tags:
  - name: Overview
    description: Top-level operational summaries.
  - name: Cluster
    description: Cluster and consensus projections.
  - name: Proposals
    description: Queue, release, and finality views.
  - name: Explorer
    description: Remote explorer read models.
  - name: Runtime
    description: Runtime-lane operator views.
  - name: Configuration
    description: Edge-published OSGi and blockchain configuration.
  - name: Events
    description: Event feeds and counters.
  - name: Storage
    description: Storage and TAR growth views.
  - name: GC
    description: GC and fragmentation publication.
  - name: Transactions
    description: Transaction summaries and detail.
components:
  schemas:
    FlexibleObject:
      type: object
      additionalProperties: true
    OpsEnvelope:
      type: object
      required:
        - version
        - generatedAt
        - data
      properties:
        version:
          type: string
          enum:
            - v1
        generatedAt:
          type: string
          format: date-time
        clusterId:
          type: string
        data:
          $ref: '#/components/schemas/FlexibleObject'
      additionalProperties: false
    OpsErrorEnvelope:
      type: object
      required:
        - version
        - generatedAt
        - error
      properties:
        version:
          type: string
          enum:
            - v1
        generatedAt:
          type: string
          format: date-time
        error:
          type: object
          required:
            - code
            - message
            - retryable
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          additionalProperties: true
      additionalProperties: false
  securitySchemes:
    ApiBearer:
      type: http
      scheme: bearer
      bearerFormat: opaque
  responses:
    OpsOk:
      description: Successful upstream ops response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpsEnvelope'
    Unauthorized:
      description: Bearer token required for this lane when edge auth is enabled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpsErrorEnvelope'
    Forbidden:
      description: Provided bearer token is not permitted for this lane.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpsErrorEnvelope'
    NotFound:
      description: Endpoint not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpsErrorEnvelope'
    UpstreamUnavailable:
      description: Source route unavailable or contract validation failed upstream.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpsErrorEnvelope'
security:
  - {}
  - ApiBearer: []
paths:
  /ops/v1/overview:
    get:
      tags: [Overview]
      summary: Remote operational overview.
      operationId: getOpsOverview
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/header:
    get:
      tags: [Overview]
      summary: Header card model for remote dashboards.
      operationId: getOpsHeader
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/network:
    get:
      tags: [Overview]
      summary: High-level network health projection.
      operationId: getOpsNetwork
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/cluster:
    get:
      tags: [Cluster]
      summary: Canonical upstream cluster view.
      operationId: getOpsCluster
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/raft:
    get:
      tags: [Cluster]
      summary: Edge-composed Raft metrics view.
      operationId: getOpsRaft
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/replication:
    get:
      tags: [Cluster]
      summary: Canonical upstream replication view.
      operationId: getOpsReplication
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/queue:
    get:
      tags: [Proposals]
      summary: Queue pressure summary.
      operationId: getOpsQueue
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/signals:
    get:
      tags: [Overview]
      summary: Derived health signals across source routes.
      operationId: getOpsSignals
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/durability:
    get:
      tags: [Proposals]
      summary: Durability acknowledgement projection.
      operationId: getOpsDurability
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/health:
    get:
      tags: [Overview]
      summary: Edge-owned remote health contract.
      operationId: getOpsHealth
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/proposals:
    get:
      tags: [Proposals]
      summary: Proposal state rollup.
      operationId: getOpsProposals
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/proposals/queue/stats:
    get:
      tags: [Proposals]
      summary: Queue and finality counters.
      operationId: getOpsProposalsQueueStats
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/proposals/release-flow:
    get:
      tags: [Proposals]
      summary: Canonical upstream release-flow view.
      operationId: getOpsProposalsReleaseFlow
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/proposals/epochs:
    get:
      tags: [Proposals]
      summary: Upstream epoch compatibility overlay.
      operationId: getOpsProposalsEpochs
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/explorer/summary:
    get:
      tags: [Explorer]
      summary: Explorer summary contract.
      operationId: getOpsExplorerSummary
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/explorer/release-flow:
    get:
      tags: [Explorer]
      summary: Explorer release-flow projection.
      operationId: getOpsExplorerReleaseFlow
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/explorer/proposal/{proposalId}:
    get:
      tags: [Explorer]
      summary: Explorer proposal detail projection.
      operationId: getOpsExplorerProposalDetail
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/explorer/wallets/{walletAddress}:
    get:
      tags: [Explorer]
      summary: Explorer wallet detail projection.
      operationId: getOpsExplorerWalletDetail
      parameters:
        - name: walletAddress
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/runtime/aeron:
    get:
      tags: [Runtime]
      summary: Runtime lane Aeron view.
      description: This route can require the stricter runtime bearer token when edge runtime auth is enabled.
      operationId: getOpsRuntimeAeron
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/runtime/media-driver:
    get:
      tags: [Runtime]
      summary: Runtime lane media-driver view.
      description: This route can require the stricter runtime bearer token when edge runtime auth is enabled.
      operationId: getOpsRuntimeMediaDriver
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/runtime/storage:
    get:
      tags: [Runtime]
      summary: Runtime lane storage view.
      description: This route can require the stricter runtime bearer token when edge runtime auth is enabled.
      operationId: getOpsRuntimeStorage
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/runtime/blobstore:
    get:
      tags: [Runtime]
      summary: Runtime lane blob-store view.
      description: This route can require the stricter runtime bearer token when edge runtime auth is enabled.
      operationId: getOpsRuntimeBlobstore
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/runtime/metrics:
    get:
      tags: [Runtime]
      summary: Runtime lane metrics view.
      description: This route can require the stricter runtime bearer token when edge runtime auth is enabled.
      operationId: getOpsRuntimeMetrics
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/config/osgi:
    get:
      tags: [Configuration]
      summary: Effective OSGi values.
      operationId: getOpsConfigOsgi
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/config/osgi/schema:
    get:
      tags: [Configuration]
      summary: OSGi metadata schema.
      operationId: getOpsConfigOsgiSchema
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/config/osgi/sources:
    get:
      tags: [Configuration]
      summary: OSGi source provenance.
      operationId: getOpsConfigOsgiSources
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/config/osgi/coverage:
    get:
      tags: [Configuration]
      summary: OSGi coverage and gaps.
      operationId: getOpsConfigOsgiCoverage
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/config/osgi/delta:
    get:
      tags: [Configuration]
      summary: OSGi delta from defaults.
      operationId: getOpsConfigOsgiDelta
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/events/recent:
    get:
      tags: [Events]
      summary: Recent edge-published events.
      operationId: getOpsEventsRecent
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum events to return.
          schema:
            type: integer
            minimum: 1
            maximum: 50
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/events/stats:
    get:
      tags: [Events]
      summary: Event totals and breakouts.
      operationId: getOpsEventsStats
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/transactions/summary:
    get:
      tags: [Transactions]
      summary: Transaction state rollup.
      operationId: getOpsTransactionsSummary
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/transactions/{transactionId}:
    get:
      tags: [Transactions]
      summary: Transaction detail projection.
      operationId: getOpsTransactionDetail
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/finality:
    get:
      tags: [Proposals]
      summary: Finality rollup.
      operationId: getOpsFinality
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/tarmk:
    get:
      tags: [Storage]
      summary: TAR growth rollup.
      operationId: getOpsTarmk
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/tar-chain:
    get:
      tags: [Storage]
      summary: TAR chain detail.
      operationId: getOpsTarChain
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/blockchain/config:
    get:
      tags: [Configuration]
      summary: Blockchain mode publication.
      operationId: getOpsBlockchainConfig
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/gc/status:
    get:
      tags: [GC]
      summary: GC status publication.
      operationId: getOpsGcStatus
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/gc/estimate:
    get:
      tags: [GC]
      summary: GC estimate publication.
      operationId: getOpsGcEstimate
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/compaction/proposals:
    get:
      tags: [GC]
      summary: Compaction proposal publication.
      operationId: getOpsCompactionProposals
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/fragmentation/metrics:
    get:
      tags: [GC]
      summary: Fragmentation metrics publication.
      operationId: getOpsFragmentationMetrics
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/fragmentation/metrics/{walletAddress}:
    get:
      tags: [GC]
      summary: Fragmentation metrics publication for one wallet.
      operationId: getOpsFragmentationMetricsByWallet
      parameters:
        - name: walletAddress
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /ops/v1/fragmentation/top:
    get:
      tags: [GC]
      summary: Top fragmented wallets publication.
      operationId: getOpsFragmentationTop
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          $ref: '#/components/responses/OpsOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'