openapi: 3.1.0
info:
  title: Governance Action Semantics Internal Contract
  version: 0.1.0
  summary: Internal logical contract for Spec 194 governance action friction, reason, and vocabulary alignment
  description: |
    This contract is an internal planning artifact for Spec 194. The affected
    surfaces continue to render through Filament and Livewire. The schemas
    below define the bounded semantic contract for governance action families,
    friction classes, reason policies, danger expectations, approved surface
    bindings, and documented deviations.
servers:
  - url: /internal
x-governance-action-consumers:
  - family: exception_decision
    sourceFiles:
      - apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
      - apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
      - apps/platform/app/Services/Findings/FindingExceptionService.php
    mustRender:
      - shared_family_binding
      - required_reason_for_f2_or_f3_actions
      - canonical_exception_vocabulary
    mustNotRender:
      - local_synonym_drift
      - undocumented_reason_override
  - family: review_lifecycle
    sourceFiles:
      - apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
      - apps/platform/app/Services/TenantReviews/TenantReviewLifecycleService.php
    mustRender:
      - publish_vs_archive_semantic_separation
      - export_remains_f0
    mustNotRender:
      - export_as_governance_peer
  - family: evidence_lifecycle
    sourceFiles:
      - apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
      - apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
      - apps/platform/app/Services/Evidence/EvidenceSnapshotService.php
    mustRender:
      - refresh_vs_expire_separation
      - required_reason_for_expire_when_declared
    mustNotRender:
      - refresh_and_expire_equivalent_semantics
  - family: run_triage
    sourceFiles:
      - apps/platform/app/Filament/System/Pages/Ops/ViewRun.php
      - apps/platform/app/Services/SystemConsole/OperationRunTriageService.php
    mustRender:
      - retry_cancel_investigated_severity_split
      - required_reason_for_high_impact_actions
    mustNotRender:
      - cancel_as_lightweight_follow_up
  - family: lifecycle_support
    sourceFiles:
      - apps/platform/app/Filament/Resources/FindingResource.php
      - apps/platform/app/Filament/Resources/TenantResource.php
      - apps/platform/app/Services/Findings/FindingWorkflowService.php
    mustRender:
      - consistent_close_reopen_family
      - consistent_archive_restore_family
    mustNotRender:
      - undocumented_surface_specific_override
  - family: regression_guards
    sourceFiles:
      - apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php
      - apps/platform/tests/Feature/Guards/Spec194GovernanceActionSemanticsGuardTest.php
      - apps/platform/tests/Unit/Ui/GovernanceActions/GovernanceActionCatalogTest.php
paths:
  /internal/governance-actions/families/{family}:
    get:
      summary: Return the logical semantics contract for one governance action family
      operationId: getGovernanceActionFamilyContract
      parameters:
        - name: family
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/FamilyKey'
      responses:
        '200':
          description: Logical semantics contract for the requested family
          content:
            application/vnd.tenantpilot.governance-action-semantics+json:
              schema:
                $ref: '#/components/schemas/GovernanceActionFamilyContract'
        '404':
          description: Requested family is not declared in the Spec 194 catalog
  /internal/governance-actions/surfaces/{surface}:
    get:
      summary: Return all governance action bindings for one surface
      operationId: getGovernanceSurfaceBindings
      parameters:
        - name: surface
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/SurfaceKey'
      responses:
        '200':
          description: Declared governance action bindings for the requested surface
          content:
            application/vnd.tenantpilot.governance-action-bindings+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GovernanceActionSurfaceBinding'
        '404':
          description: Requested surface has no Spec 194 governance bindings
components:
  schemas:
    FamilyKey:
      type: string
      enum:
        - exception_decision
        - review_lifecycle
        - evidence_lifecycle
        - run_triage
        - finding_lifecycle
        - tenant_lifecycle
        - non_governance_navigation
    SurfaceKey:
      type: string
      enum:
        - finding_exceptions_queue
        - view_finding_exception
        - list_evidence_snapshots
        - view_evidence_snapshot
        - view_tenant_review
        - view_finding
        - tenantless_operation_run_viewer
        - system_view_run
        - view_tenant
        - edit_tenant
    FrictionClass:
      type: string
      enum:
        - F0
        - F1
        - F2
        - F3
    ReasonPolicy:
      type: string
      enum:
        - none
        - optional
        - required
    DangerPolicy:
      type: string
      enum:
        - none
        - contextual
        - required
    AuditChannel:
      type: string
      enum:
        - tenant_audit
        - workspace_audit
        - system_audit
        - operation_context
    GovernanceActionRule:
      type: object
      additionalProperties: false
      required:
        - actionKey
        - canonicalLabel
        - frictionClass
        - reasonPolicy
        - dangerPolicy
        - auditVerb
        - serviceOwner
      properties:
        actionKey:
          type: string
        canonicalLabel:
          type: string
        frictionClass:
          $ref: '#/components/schemas/FrictionClass'
        reasonPolicy:
          $ref: '#/components/schemas/ReasonPolicy'
        dangerPolicy:
          $ref: '#/components/schemas/DangerPolicy'
        modalHeadingPattern:
          type: string
        successNotificationPattern:
          type: string
        auditVerb:
          type: string
        serviceOwner:
          type: string
    GovernanceActionSurfaceBinding:
      type: object
      additionalProperties: false
      required:
        - surfaceKey
        - pageClass
        - actionName
        - familyKey
        - statePredicate
        - auditChannel
      properties:
        surfaceKey:
          $ref: '#/components/schemas/SurfaceKey'
        pageClass:
          type: string
        actionName:
          type: string
        familyKey:
          $ref: '#/components/schemas/FamilyKey'
        statePredicate:
          type: string
        primaryOrSecondary:
          type: string
          enum:
            - primary
            - secondary
        capabilityKey:
          type:
            - string
            - 'null'
        uiFieldKey:
          type:
            - string
            - 'null'
        auditChannel:
          $ref: '#/components/schemas/AuditChannel'
    DocumentedDeviation:
      type: object
      additionalProperties: false
      required:
        - actionKey
        - surfaceKey
        - deviationType
        - rationale
        - reviewGate
      properties:
        actionKey:
          type: string
        surfaceKey:
          $ref: '#/components/schemas/SurfaceKey'
        deviationType:
          type: string
          enum:
            - friction_override
            - reason_override
            - danger_override
            - vocabulary_override
        rationale:
          type: string
        reviewGate:
          type: string
        allowedUntil:
          type:
            - string
            - 'null'
    GovernanceActionFamilyContract:
      type: object
      additionalProperties: false
      required:
        - familyKey
        - canonicalObject
        - rules
        - bindings
        - regressionRequirements
      properties:
        familyKey:
          $ref: '#/components/schemas/FamilyKey'
        canonicalObject:
          type: string
        panels:
          type: array
          items:
            type: string
            enum:
              - tenant
              - admin
              - system
        defaultActionOrder:
          type: array
          items:
            type: string
        defaultMutationScopeSource:
          type: string
        rules:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceActionRule'
        bindings:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceActionSurfaceBinding'
        deviations:
          type: array
          items:
            $ref: '#/components/schemas/DocumentedDeviation'
        regressionRequirements:
          type: object
          additionalProperties: false
          required:
            - requiresGuardCoverage
            - requiresFeatureCoverage
            - requiresBrowserSmoke
            - requiresPositiveAuthCase
            - requiresNegativeAuthCase
          properties:
            requiresGuardCoverage:
              type: boolean
            requiresFeatureCoverage:
              type: boolean
            requiresBrowserSmoke:
              type: boolean
            requiresPositiveAuthCase:
              type: boolean
            requiresNegativeAuthCase:
              type: boolean
            mustVerifyAuditPropagation:
              type: boolean