openapi: 3.0.3
info:
  title: TenantPilot Compliance Evidence Mapping v1 (Conceptual)
  version: 0.1.0
  description: |
    Conceptual contract for the Compliance Evidence Mapping v1 planning package.

    These paths describe existing Filament admin and tenant-scoped routes reused by
    the implementation. The schemas document the shared interpretation contract the
    feature is expected to add to existing review payloads; they do not define a new
    public REST API.
servers:
  - url: /
paths:
  /admin/reviews/workspace:
    get:
      summary: View the compliance evidence mapping workspace
      description: |
        Existing admin-plane customer review workspace page reused as the primary
        decision surface for mapped control readiness summaries. The route remains
        read-only and tenant-safe.
      parameters:
        - in: query
          name: tenant
          required: false
          schema:
            type: string
          description: |
            Optional tenant prefilter using the existing tenant id or external id
            pattern already accepted by the workspace page.
      responses:
        '200':
          description: Workspace page rendered
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerReviewWorkspacePageModel'
        '404':
          description: Not found for non-members, actors without entitled tenants, or explicit out-of-scope tenant targeting

  /admin/t/{tenant}/reviews/{review}:
    get:
      summary: Open the mapped control explanation for a released review
      description: |
        Existing tenant-scoped released-review detail route reused as the secondary
        context surface from the customer review workspace. The customer-workspace
        flow uses the existing `customer_workspace=1` query flag to keep the detail
        read-only and customer-safe.
      parameters:
        - in: path
          name: tenant
          required: true
          schema:
            type: integer
        - in: path
          name: review
          required: true
          schema:
            type: integer
        - in: query
          name: customer_workspace
          required: false
          schema:
            type: boolean
          description: Existing query-context flag that suppresses operator lifecycle actions on the detail surface.
      responses:
        '200':
          description: Released review detail rendered
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerReviewDetailModel'
        '404':
          description: Not found for non-members, tenant mismatches, or out-of-scope review targets

  /admin/t/{tenant}/evidence/{evidenceSnapshot}:
    get:
      summary: Open supporting evidence from a mapped control explanation
      description: |
        Existing tenant-scoped evidence detail route reused only after explicit
        drilldown from the released-review detail surface and existing capability
        checks.
      parameters:
        - in: path
          name: tenant
          required: true
          schema:
            type: integer
        - in: path
          name: evidenceSnapshot
          required: true
          schema:
            type: integer
        - in: query
          name: source_surface
          required: false
          schema:
            type: string
          description: Existing source-surface metadata hook reused by the shared audit path.
      responses:
        '200':
          description: Evidence proof detail rendered
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Forbidden for an in-scope actor missing the evidence capability
        '404':
          description: Not found for non-members, mismatched tenant scope, or unavailable evidence targets

components:
  schemas:
    ControlInterpretationVersion:
      type: object
      required:
        - version_key
        - display_label
        - non_certification_disclosure
      properties:
        version_key:
          type: string
          example: compliance_evidence_mapping.v1
        display_label:
          type: string
        non_certification_disclosure:
          type: string

    AccessState:
      type: object
      required:
        - state
        - message
      properties:
        state:
          type: string
          enum:
            - available
            - absent
            - unavailable
            - expired
            - redacted
            - partial
        message:
          type: string
        url:
          type: string
          nullable: true

    CustomerControlSummary:
      type: object
      required:
        - control_key
        - control_name
        - readiness_bucket
        - limitation_flags
        - customer_summary
        - recommended_next_action
      properties:
        control_key:
          type: string
        control_name:
          type: string
        domain_key:
          type: string
          nullable: true
        readiness_bucket:
          type: string
          enum:
            - follow_up_required
            - review_recommended
            - evidence_on_record
        limitation_flags:
          type: array
          items:
            type: string
            enum:
              - accepted_risk_influenced
              - partial_mapping
              - stale_evidence
              - supporting_evidence_unavailable
              - unmapped
        customer_summary:
          type: string
        evidence_basis_summary:
          type: string
          nullable: true
        accepted_risk_summary:
          type: string
          nullable: true
        recommended_next_action:
          type: string
        detail_anchor:
          type: string
          nullable: true

    CustomerControlExplanation:
      allOf:
        - $ref: '#/components/schemas/CustomerControlSummary'
        - type: object
          properties:
            explanation_text:
              type: string
            evidence_basis_items:
              type: array
              items:
                type: string
            proof_access:
              $ref: '#/components/schemas/AccessState'

    CustomerReviewWorkspaceEntry:
      type: object
      required:
        - tenant_id
        - tenant_name
        - latest_published_review_id
        - latest_review_published_at
        - interpretation
        - control_summaries
      properties:
        tenant_id:
          type: integer
        tenant_name:
          type: string
        latest_published_review_id:
          type: integer
        latest_review_published_at:
          type: string
          format: date-time
        interpretation:
          $ref: '#/components/schemas/ControlInterpretationVersion'
        control_summaries:
          type: array
          items:
            $ref: '#/components/schemas/CustomerControlSummary'
        follow_up_summary:
          type: string
          nullable: true

    CustomerReviewWorkspacePageModel:
      type: object
      required:
        - workspace_id
        - entries
      properties:
        workspace_id:
          type: integer
        tenant_filter_id:
          type: integer
          nullable: true
        entries:
          type: array
          items:
            $ref: '#/components/schemas/CustomerReviewWorkspaceEntry'
        empty_state_message:
          type: string
          nullable: true

    CustomerReviewDetailModel:
      type: object
      required:
        - review_id
        - tenant_id
        - customer_workspace_context
        - interpretation
        - controls
        - operator_actions_hidden
      properties:
        review_id:
          type: integer
        tenant_id:
          type: integer
        customer_workspace_context:
          type: boolean
        interpretation:
          $ref: '#/components/schemas/ControlInterpretationVersion'
        controls:
          type: array
          items:
            $ref: '#/components/schemas/CustomerControlExplanation'
        operator_actions_hidden:
          type: boolean
        supporting_evidence_collapsed_by_default:
          type: boolean
        raw_support_details_hidden_by_default:
          type: boolean