TenantAtlas/specs/260-governance-service-packaging/contracts/governance-service-packaging.openapi.yaml

openapi: 3.0.3
info:
  title: TenantPilot Governance-as-a-Service Packaging v1 (Conceptual)
  version: 0.1.0
  description: |
    Conceptual contract for the Governance-as-a-Service Packaging v1 planning package.

    These paths describe existing Filament admin and tenant-scoped routes reused by
    the implementation. The schemas document the derived package summary and
    package-availability contract expected over existing review, review-pack,
    evidence, stored-report-backed evidence, and governance-decision truth; they
    do not define a new public REST API.    
servers:
  - url: /
paths:
  /admin/reviews/workspace:
    get:
      summary: View management-ready package readiness in the customer review workspace
      description: |
        Existing admin-plane workspace page reused as the primary decision surface.
        The route remains read-only, tenant-safe, and package-readiness remains
        informational rather than a second competing action path.        
      parameters:
        - in: query
          name: tenant
          required: false
          schema:
            type: string
          description: |
            Optional tenant prefilter using the current 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 management-ready package context for a released review
      description: |
        Existing tenant-scoped released-review detail route reused as the secondary
        package context surface. The customer-workspace flow uses the existing
        `customer_workspace=1` query flag to keep the detail read-only and
        management-ready.        
      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/GovernancePackageDetailModel'
        '403':
          description: Forbidden for an in-scope actor missing the inherited review-view capability on the reused route
        '404':
          description: Not found for non-members, tenant mismatches, or out-of-scope review targets

  /admin/review-packs/{reviewPack}/download:
    get:
      summary: Download the current review-pack-backed governance package artifact
      description: |
        Existing signed review-pack download route reused as the default package
        delivery seam. The management-ready path should reuse this route rather than
        creating a new package artifact namespace or triggering generation.        
      parameters:
        - in: path
          name: reviewPack
          required: true
          schema:
            type: integer
        - in: query
          name: source_surface
          required: false
          schema:
            type: string
        - in: query
          name: review_id
          required: false
          schema:
            type: integer
        - in: query
          name: tenant_filter_id
          required: false
          schema:
            type: integer
        - in: query
          name: interpretation_version
          required: false
          schema:
            type: string
      responses:
        '302':
          description: Signed download redirect to the current review-pack artifact
        '403':
          description: Forbidden for an in-scope actor missing the review-pack capability or a valid signature
        '404':
          description: Not found for non-members, tenant mismatches, or inaccessible review packs

  /admin/t/{tenant}/evidence/{evidenceSnapshot}:
    get:
      summary: Open supporting evidence from the management-ready package context
      description: |
        Existing tenant-scoped evidence detail route reused only after explicit
        drilldown from the released-review detail surface and current 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
      properties:
        version_key:
          type: string
          example: compliance_evidence_mapping.v1
        display_label:
          type: string
        calm_disclosure:
          type: string
          nullable: true

    PackageAvailabilityState:
      type: object
      description: Package-facing availability derived from the existing artifact-truth seam. Canonical mapping is publishable -> available, internal_only or stale -> partial, blocked or missing_input -> unavailable, historical_only -> expired, and package-level entitlement restriction -> blocked. Secondary-artifact restrictions do not force the top-level package state to blocked when the summary remains readable.
      required:
        - state
        - message
      properties:
        state:
          type: string
          enum:
            - available
            - partial
            - unavailable
            - expired
            - blocked
        message:
          type: string
        reason_code:
          type: string
          nullable: true
          description: Explains why the package is not fully available without creating a second availability taxonomy.
          enum:
            - current_review_pack_missing
            - current_review_pack_expired
            - stale_basis
            - evidence_basis_partial
            - interpretation_missing
            - source_not_publishable
            - entitlement_restricted
        download_url:
          type: string
          nullable: true

    SupportingArtifactLink:
      type: object
      description: Optional proof or artifact drilldown. A supporting link may be forbidden or unavailable while the top-level package summary remains readable.
      required:
        - artifact_family
        - state
        - label
      properties:
        artifact_family:
          type: string
          enum:
            - review_pack
            - evidence_snapshot
            - stored_report
        state:
          type: string
          enum:
            - available
            - partial
            - unavailable
            - expired
            - redacted
            - forbidden
        label:
          type: string
        message:
          type: string
          nullable: true
        url:
          type: string
          nullable: true

    ManagementFindingHighlight:
      type: object
      required:
        - label
        - customer_summary
      properties:
        finding_id:
          type: integer
          nullable: true
        label:
          type: string
        severity:
          type: string
          nullable: true
        customer_summary:
          type: string
        control_key:
          type: string
          nullable: true

    GovernanceDecisionFollowUp:
      type: object
      required:
        - decision_source
        - decision_state
        - decision_summary
      properties:
        decision_source:
          type: string
          enum:
            - finding_exception
            - risk_acceptance
        decision_state:
          type: string
          enum:
            - awareness_required
            - expiring
            - expired
            - revoked
            - missing_basis
        decision_summary:
          type: string
        accountable_label:
          type: string
          nullable: true
        review_due_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true

    GovernancePackageSummary:
      type: object
      required:
        - review_id
        - tenant_id
        - interpretation
        - delivery_artifact_family
        - package_availability
        - executive_summary
      properties:
        review_id:
          type: integer
        tenant_id:
          type: integer
        interpretation:
          $ref: '#/components/schemas/ControlInterpretationVersion'
        delivery_artifact_family:
          type: string
          enum:
            - review_pack
        package_availability:
          $ref: '#/components/schemas/PackageAvailabilityState'
        executive_summary:
          type: string
        highlights:
          type: array
          items:
            type: string
        top_findings:
          type: array
          items:
            $ref: '#/components/schemas/ManagementFindingHighlight'
        accepted_risks:
          type: array
          description: Currently valid tolerated-risk positions that explain why material risk is presently accepted and does not require immediate stakeholder follow-up beyond awareness.
          items:
            $ref: '#/components/schemas/GovernanceDecisionFollowUp'
        governance_decisions:
          type: array
          description: Accepted-risk or exception decision entries that still require stakeholder awareness or follow-up. Entries must be disjoint from accepted_risks for the same review.
          items:
            $ref: '#/components/schemas/GovernanceDecisionFollowUp'
        evidence_basis_summary:
          type: string
          nullable: true
        recommended_next_action:
          type: string
          nullable: true
        supporting_artifacts:
          type: array
          items:
            $ref: '#/components/schemas/SupportingArtifactLink'

    CustomerReviewWorkspaceEntry:
      type: object
      required:
        - tenant_id
        - tenant_name
        - latest_published_review_id
        - package_availability
        - control_readiness
      properties:
        tenant_id:
          type: integer
        tenant_name:
          type: string
        latest_published_review_id:
          type: integer
        latest_review_published_at:
          type: string
          format: date-time
          nullable: true
        interpretation:
          $ref: '#/components/schemas/ControlInterpretationVersion'
        package_availability:
          $ref: '#/components/schemas/PackageAvailabilityState'
        control_readiness:
          type: string
        evidence_basis:
          type: string
          nullable: true
        recommended_next_action:
          type: string
          nullable: true
        evidence_proof_state:
          type: string
          nullable: true
        management_teaser:
          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'

    GovernancePackageDetailModel:
      type: object
      required:
        - review
        - package
      properties:
        review:
          type: object
          required:
            - review_id
            - tenant_id
            - published_at
          properties:
            review_id:
              type: integer
            tenant_id:
              type: integer
            published_at:
              type: string
              format: date-time
              nullable: true
        package:
          $ref: '#/components/schemas/GovernancePackageSummary'