openapi: 3.1.0
info:
  title: Evidence Domain Foundation
  version: 0.1.0
  description: |
    Planning contract for the tenant evidence snapshot domain. These routes describe
    the expected HTTP-level behavior behind Filament surfaces and downstream consumers.
servers:
  - url: http://localhost
paths:
  /admin/t/{tenant}/evidence:
    get:
      operationId: listEvidenceSnapshots
      summary: List evidence snapshots for a tenant
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Snapshot list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EvidenceSnapshot'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createEvidenceSnapshot
      summary: Queue evidence snapshot creation for a tenant
      parameters:
        - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSnapshotRequest'
      responses:
        '202':
          description: Snapshot generation accepted or existing matching snapshot reused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotGenerationResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/t/{tenant}/evidence/{snapshot}:
    get:
      operationId: viewEvidenceSnapshot
      summary: View one evidence snapshot and its dimension items
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '200':
          description: Snapshot detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceSnapshotDetail'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/t/{tenant}/evidence/{snapshot}/refresh:
    post:
      operationId: refreshEvidenceSnapshot
      summary: Queue creation of a new snapshot from current evidence state
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '202':
          description: Refresh accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotGenerationResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/t/{tenant}/evidence/{snapshot}/expire:
    post:
      operationId: expireEvidenceSnapshot
      summary: Expire a snapshot without mutating its captured content
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '200':
          description: Snapshot expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceSnapshot'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /admin/evidence/overview:
    get:
      operationId: evidenceOverview
      summary: List workspace-scoped evidence completeness across authorized tenants
      parameters:
        - name: tenant_id
          in: query
          required: false
          description: Optional entitled-tenant prefilter carried from tenant context into the canonical overview.
          schema:
            type: integer
      responses:
        '200':
          description: Workspace evidence overview
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EvidenceOverviewRow'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  parameters:
    TenantId:
      name: tenant
      in: path
      required: true
      schema:
        type: integer
    SnapshotId:
      name: snapshot
      in: path
      required: true
      schema:
        type: integer

  responses:
    Forbidden:
      description: In-scope member lacks the required capability
    NotFound:
      description: Workspace or tenant not entitled, or snapshot is outside scope

  schemas:
    CreateSnapshotRequest:
      type: object
      properties:
        required_dimensions:
          type: array
          items:
            type: string
        allow_stale:
          type: boolean
          default: false
    SnapshotGenerationResponse:
      type: object
      properties:
        snapshot_id:
          type: integer
        operation_run_id:
          type: integer
          nullable: true
        reused:
          type: boolean
        status:
          type: string
          enum: [queued, generating, active]
    EvidenceSnapshot:
      type: object
      properties:
        id:
          type: integer
        tenant_id:
          type: integer
        status:
          type: string
          enum: [queued, generating, active, superseded, expired, failed]
        completeness_state:
          type: string
          enum: [complete, partial, missing, stale]
        fingerprint:
          type: string
          nullable: true
        generated_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        summary:
          type: object
    EvidenceSnapshotDetail:
      allOf:
        - $ref: '#/components/schemas/EvidenceSnapshot'
        - type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/EvidenceSnapshotItem'
    EvidenceSnapshotItem:
      type: object
      properties:
        dimension_key:
          type: string
        state:
          type: string
          enum: [complete, partial, missing, stale]
        required:
          type: boolean
        source_kind:
          type: string
        source_record_type:
          type: string
          nullable: true
        source_record_id:
          type: string
          nullable: true
        source_fingerprint:
          type: string
          nullable: true
        measured_at:
          type: string
          format: date-time
          nullable: true
        freshness_at:
          type: string
          format: date-time
          nullable: true
        summary_payload:
          type: object
    EvidenceOverviewRow:
      type: object
      properties:
        tenant_id:
          type: integer
        latest_snapshot_id:
          type: integer
          nullable: true
        snapshot_id:
          type: integer
          nullable: true
        completeness_state:
          type: string
          enum: [complete, partial, missing, stale]
          nullable: true
        generated_at:
          type: string
          format: date-time
          nullable: true
        missing_dimensions:
          type: integer
        stale_dimensions:
          type: integer