openapi: 3.1.0
info:
  title: Audit Log Review Contract
  version: 0.1.0
  description: >-
    Internal route and response contract for the canonical workspace Monitoring
    audit log surface at /admin/audit-log. This documents the filter and
    inspection semantics required by Spec 134; it is not a public API promise.
paths:
  /admin/audit-log:
    get:
      summary: View canonical audit log
      description: >-
        Returns the workspace-scoped audit review surface with optional tenant,
        event, outcome, actor, target, search, and date-range filters. When the
        request is made while tenant context is active and entitled, the active
        tenant may be preselected as the default filter, but the route remains
        canonical and workspace-scoped.
      parameters:
        - in: query
          name: tenant_id
          schema:
            type: string
            nullable: true
          description: Authorized tenant filter within the active workspace.
        - in: query
          name: event_type
          schema:
            type: string
            nullable: true
          description: Canonical audit event taxonomy key.
        - in: query
          name: outcome
          schema:
            type: string
            enum: [success, failed, partial, info, blocked]
            nullable: true
        - in: query
          name: actor
          schema:
            type: string
            nullable: true
          description: Actor label or actor-kind filter.
        - in: query
          name: target_type
          schema:
            type: string
            nullable: true
        - in: query
          name: search
          schema:
            type: string
            nullable: true
          description: High-signal summary search.
        - in: query
          name: date_from
          schema:
            type: string
            format: date
            nullable: true
        - in: query
          name: date_until
          schema:
            type: string
            format: date
            nullable: true
      responses:
        '200':
          description: Authorized workspace-scoped audit review surface.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditLogListRow'
                  meta:
                    type: object
                    required:
                      - scope
                      - filters
                    properties:
                      scope:
                        type: object
                        required: [workspace_id]
                        properties:
                          workspace_id:
                            type: integer
                          tenant_id:
                            type: integer
                            nullable: true
                      filters:
                        $ref: '#/components/schemas/AuditLogFilterState'
                      empty_state:
                        type: object
                        nullable: true
                        properties:
                          title:
                            type: string
                          description:
                            type: string
                          cta_label:
                            type: string
        '403':
          description: Workspace member lacks audit.view capability.
        '404':
          description: Viewer is not entitled to the active workspace or requested tenant scope.
  /admin/audit-log/{auditLogId}:
    get:
      summary: Inspect one audit event
      description: >-
        Returns a detail-inspection representation of one audit event. Related
        target navigation is included only when the target still exists and the
        current viewer is authorized to inspect it.
      parameters:
        - in: path
          name: auditLogId
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Authorized audit event detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogDetail'
        '403':
          description: Workspace member lacks audit.view capability.
        '404':
          description: Viewer is not entitled to the workspace or tenant scope of the event.
components:
  schemas:
    AuditLogListRow:
      type: object
      required:
        - id
        - occurred_at
        - summary
        - event_type
        - outcome
        - actor
      properties:
        id:
          type: integer
        occurred_at:
          type: string
          format: date-time
        summary:
          type: string
        event_type:
          type: string
        outcome:
          type: string
          enum: [success, failed, partial, info, blocked]
        actor:
          $ref: '#/components/schemas/AuditActor'
        target:
          allOf:
            - $ref: '#/components/schemas/AuditTarget'
          nullable: true
        tenant_label:
          type: string
          nullable: true
        has_related_link:
          type: boolean
    AuditLogDetail:
      type: object
      required:
        - id
        - occurred_at
        - summary
        - event_type
        - outcome
        - actor
        - context_items
      properties:
        id:
          type: integer
        occurred_at:
          type: string
          format: date-time
        summary:
          type: string
        event_type:
          type: string
        outcome:
          type: string
          enum: [success, failed, partial, info, blocked]
        actor:
          $ref: '#/components/schemas/AuditActor'
        target:
          allOf:
            - $ref: '#/components/schemas/AuditTarget'
          nullable: true
        context_items:
          type: array
          items:
            type: object
            required: [label, value]
            properties:
              label:
                type: string
              value:
                oneOf:
                  - type: string
                  - type: number
                  - type: integer
                  - type: boolean
        technical_metadata:
          type: object
          additionalProperties: true
        related_link:
          type: object
          nullable: true
          properties:
            label:
              type: string
            url:
              type: string
    AuditActor:
      type: object
      required:
        - actor_type
      properties:
        actor_type:
          type: string
          enum: [human, system, scheduled, integration, platform]
        actor_id:
          oneOf:
            - type: integer
            - type: string
          nullable: true
        actor_label:
          type: string
          nullable: true
        actor_email:
          type: string
          nullable: true
    AuditTarget:
      type: object
      properties:
        target_type:
          type: string
          nullable: true
        target_id:
          type: string
          nullable: true
        target_label:
          type: string
          nullable: true
    AuditLogFilterState:
      type: object
      properties:
        tenant_id:
          type: string
          nullable: true
        event_type:
          type: string
          nullable: true
        outcome:
          type: string
          nullable: true
        actor:
          type: string
          nullable: true
        target_type:
          type: string
          nullable: true
        search:
          type: string
          nullable: true
        date_from:
          type: string
          format: date
          nullable: true
        date_until:
          type: string
          format: date
          nullable: true