openapi: 3.0.3
info:
  title: Baseline Governance v1 (Golden Master)
  version: 1.0.0
  description: |
    Conceptual HTTP contract for Baseline Governance actions.

    Note: The implementation is Filament + Livewire; these endpoints describe the server-side behavior
    (authorization, precondition failures, operation run creation) in a REST-like form for clarity.

servers:
  - url: /admin

paths:
  /workspaces/{workspaceId}/baselines:
    get:
      summary: List baseline profiles
      parameters:
        - $ref: '#/components/parameters/workspaceId'
      responses:
        '200':
          description: OK

  /workspaces/{workspaceId}/baselines/{baselineProfileId}:
    get:
      summary: View baseline profile
      parameters:
        - $ref: '#/components/parameters/workspaceId'
        - $ref: '#/components/parameters/baselineProfileId'
      responses:
        '200':
          description: OK
        '404':
          description: Not found (workspace not entitled)
        '403':
          description: Forbidden (missing capability)

  /workspaces/{workspaceId}/baselines/{baselineProfileId}/capture:
    post:
      summary: Capture immutable baseline snapshot from a tenant
      parameters:
        - $ref: '#/components/parameters/workspaceId'
        - $ref: '#/components/parameters/baselineProfileId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source_tenant_id]
              properties:
                source_tenant_id:
                  type: integer
      responses:
        '202':
          description: Enqueued (OperationRun created/reused)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationRunStartResponse'
        '422':
          description: Precondition failure (no OperationRun created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreconditionFailure'
              examples:
                missingSourceTenant:
                  value:
                    reason_code: baseline.capture.missing_source_tenant
        '404':
          description: Not found (workspace not entitled)
        '403':
          description: Forbidden (missing capability)

  /tenants/{tenantId}/baseline-compare:
    post:
      summary: Compare tenant state to assigned baseline and generate drift findings
      parameters:
        - $ref: '#/components/parameters/tenantId'
      responses:
        '202':
          description: Enqueued (OperationRun created/reused)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationRunStartResponse'
        '422':
          description: Precondition failure (no OperationRun created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreconditionFailure'
              examples:
                noAssignment:
                  value:
                    reason_code: baseline.compare.no_assignment
                profileNotActive:
                  value:
                    reason_code: baseline.compare.profile_not_active
                noActiveSnapshot:
                  value:
                    reason_code: baseline.compare.no_active_snapshot
        '404':
          description: Not found (tenant/workspace not entitled)
        '403':
          description: Forbidden (missing capability)

  /tenants/{tenantId}/baseline-compare/latest:
    get:
      summary: Fetch latest baseline compare summary for tenant
      parameters:
        - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: OK

components:
  parameters:
    workspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: integer
    tenantId:
      name: tenantId
      in: path
      required: true
      schema:
        type: integer
    baselineProfileId:
      name: baselineProfileId
      in: path
      required: true
      schema:
        type: integer

  schemas:
    OperationRunStartResponse:
      type: object
      required: [operation_run_id]
      properties:
        operation_run_id:
          type: integer
        reused:
          type: boolean
          description: True if an already-queued/running run was returned

    PreconditionFailure:
      type: object
      required: [reason_code]
      properties:
        reason_code:
          type: string
          description: Stable code for UI + support triage