openapi: 3.1.0
info:
  title: Inventory Coverage Truth Surfaces
  version: 0.1.0
  description: |
    Logical surface contract for Spec 177. These contracts describe the tenant-scoped
    coverage truth that inventory surfaces must render, even when the delivered transport
    is server-rendered Filament UI rather than a public JSON API.
paths:
  /admin/inventory-items:
    get:
      summary: Inventory items list with truthful coverage summary
      operationId: inventoryItemsCoverageSummary
      responses:
        '200':
          description: Tenant-scoped inventory items list surface
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - tenantId
                  - coverageSummary
                properties:
                  tenantId:
                    type: integer
                  coverageSummary:
                    $ref: '#/components/schemas/CoverageSummary'
        '403':
          description: Member lacks capability for a linked follow-up action
        '404':
          description: User is not entitled to the tenant or workspace scope
  /admin/coverage:
    get:
      summary: Tenant coverage truth report
      operationId: inventoryCoverageReport
      responses:
        '200':
          description: Tenant-scoped coverage report surface
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - tenantId
                  - coverageSummary
                  - rows
                properties:
                  tenantId:
                    type: integer
                  coverageSummary:
                    $ref: '#/components/schemas/CoverageSummary'
                  rows:
                    type: array
                    items:
                      $ref: '#/components/schemas/CoverageRow'
        '403':
          description: Member lacks capability for a linked follow-up action
        '404':
          description: User is not entitled to the tenant or workspace scope
  /admin/operations/{run}:
    get:
      summary: Canonical inventory-sync run detail with per-type coverage section
      operationId: inventorySyncRunDetail
      parameters:
        - in: path
          name: run
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Canonical operation run detail surface
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - id
                  - type
                  - status
                  - outcome
                properties:
                  id:
                    type: integer
                  type:
                    type: string
                    enum:
                      - inventory_sync
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - completed
                  outcome:
                    type: string
                    enum:
                      - pending
                      - succeeded
                      - partially_succeeded
                      - failed
                      - blocked
                  inventoryCoverageSection:
                    oneOf:
                      - $ref: '#/components/schemas/InventoryCoverageRunSection'
                      - type: 'null'
        '403':
          description: In-scope member lacks the run capability required for this operation
        '404':
          description: User is not entitled to the workspace or tenant scope for this run
components:
  schemas:
    BasisRun:
      type: object
      additionalProperties: false
      required:
        - id
        - outcome
        - completedAt
      properties:
        id:
          type: integer
        outcome:
          type: string
          enum:
            - succeeded
            - partially_succeeded
            - failed
            - blocked
        completedAt:
          type: string
          format: date-time
    CoverageSummary:
      type: object
      additionalProperties: false
      required:
        - hasCurrentCoverageResult
        - supportedTypes
        - succeededTypes
        - failedTypes
        - skippedTypes
        - unknownTypes
        - followUpTypes
        - observedItems
      properties:
        hasCurrentCoverageResult:
          type: boolean
        basisRun:
          oneOf:
            - $ref: '#/components/schemas/BasisRun'
            - type: 'null'
        supportedTypes:
          type: integer
        succeededTypes:
          type: integer
        failedTypes:
          type: integer
        skippedTypes:
          type: integer
        unknownTypes:
          type: integer
        followUpTypes:
          type: integer
        observedItems:
          type: integer
    CoverageRow:
      type: object
      additionalProperties: false
      required:
        - type
        - segment
        - label
        - category
        - coverageState
        - followUpRequired
        - observedItemCount
        - supportsDependencies
      properties:
        type:
          type: string
        segment:
          type: string
          enum:
            - policy
            - foundation
        label:
          type: string
        category:
          type: string
        platform:
          type:
            - string
            - 'null'
        coverageState:
          type: string
          enum:
            - succeeded
            - failed
            - skipped
            - unknown
        followUpRequired:
          type: boolean
        observedItemCount:
          type: integer
        basisErrorCode:
          type:
            - string
            - 'null'
        restoreMode:
          type:
            - string
            - 'null'
        riskLevel:
          type:
            - string
            - 'null'
        supportsDependencies:
          type: boolean
    InventoryCoverageRunSection:
      type: object
      additionalProperties: false
      required:
        - basisRun
        - rows
      properties:
        basisRun:
          $ref: '#/components/schemas/BasisRun'
        rows:
          type: array
          items:
            $ref: '#/components/schemas/CoverageRow'