openapi: 3.0.3
info:
  title: Spec 116 - Baseline Drift Engine
  version: 0.1.0
  description: |
    Minimal contracts for Baseline capture/compare operations and finding summaries.
    This repo is primarily Filament-driven; these endpoints represent conceptual contracts
    or internal routes/services rather than guaranteed public APIs.

servers:
  - url: /

paths:
  /internal/baselines/{baselineProfileId}/snapshots:
    post:
      summary: Capture a baseline snapshot
      parameters:
        - in: path
          name: baselineProfileId
          required: true
          schema:
            type: integer
      requestBody:
        required: false
      responses:
        '202':
          description: Snapshot capture queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationQueued'

  /internal/baselines/{baselineProfileId}/compare:
    post:
      summary: Compare baseline snapshot to tenant inventory
      parameters:
        - in: path
          name: baselineProfileId
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaselineCompareRequest'
      responses:
        '202':
          description: Compare queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationQueued'

  /internal/tenants/{tenantId}/findings:
    get:
      summary: List findings for a tenant (filtered)
      parameters:
        - in: path
          name: tenantId
          required: true
          schema:
            type: integer
        - in: query
          name: scope_key
          required: false
          schema:
            type: string
        - in: query
          name: status
          required: false
          schema:
            type: string
            enum: [open, resolved]
      responses:
        '200':
          description: Findings list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Finding'

components:
  schemas:
    BaselineCompareRequest:
      type: object
      required: [tenant_id]
      properties:
        tenant_id:
          type: integer
        baseline_snapshot_id:
          type: integer
          nullable: true
          description: Optional explicit snapshot selection. If omitted, latest successful snapshot is used.

    OperationQueued:
      type: object
      required: [operation_run_id]
      properties:
        operation_run_id:
          type: integer

    Finding:
      type: object
      required: [id, tenant_id, fingerprint, scope_key, created_at]
      properties:
        id:
          type: integer
        tenant_id:
          type: integer
        fingerprint:
          type: string
          description: Stable identifier; for baseline drift equals recurrence_key.
        recurrence_key:
          type: string
          nullable: true
        scope_key:
          type: string
        change_type:
          type: string
          nullable: true
        policy_type:
          type: string
          nullable: true
        subject_external_id:
          type: string
          nullable: true
        evidence:
          type: object
          additionalProperties: true
        first_seen_at:
          type: string
          format: date-time
          nullable: true
        last_seen_at:
          type: string
          format: date-time
          nullable: true
        times_seen:
          type: integer
          nullable: true
        resolved_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time