openapi: 3.1.0
info:
  title: Operation Run Link Contract Enforcement
  version: 1.0.0
  summary: Logical internal contract for Spec 232 canonical admin and system operation-run links plus bounded guard enforcement.
  description: |
    This contract documents the internal helper-owned URL semantics that Spec 232 enforces.
    It is intentionally logical rather than a public HTTP API because the feature reuses
    existing Filament pages, helper families, and route ownership instead of introducing
    a new controller namespace.
servers:
  - url: https://logical.internal
    description: Non-routable placeholder used to describe internal repository contracts.
paths:
  /internal/operation-run-links/admin/collection:
    post:
      summary: Build the canonical admin operations collection URL for a covered source surface.
      operationId: buildAdminOperationCollectionLink
      x-not-public-http: true
      requestBody:
        required: true
        content:
          application/vnd.tenantpilot.admin-operation-collection-input+json:
            schema:
              $ref: '#/components/schemas/AdminOperationCollectionLinkInput'
      responses:
        '200':
          description: Canonical admin collection link emitted through `OperationRunLinks::index(...)`.
          content:
            application/vnd.tenantpilot.operation-link+json:
              schema:
                $ref: '#/components/schemas/CanonicalOperationLink'
  /internal/operation-run-links/admin/detail:
    post:
      summary: Build the canonical admin operation detail URL for a covered source surface.
      operationId: buildAdminOperationDetailLink
      x-not-public-http: true
      requestBody:
        required: true
        content:
          application/vnd.tenantpilot.admin-operation-detail-input+json:
            schema:
              $ref: '#/components/schemas/AdminOperationDetailLinkInput'
      responses:
        '200':
          description: Canonical admin detail link emitted through `OperationRunLinks::view(...)` or `tenantlessView(...)`.
          content:
            application/vnd.tenantpilot.operation-link+json:
              schema:
                $ref: '#/components/schemas/CanonicalOperationLink'
  /internal/operation-run-links/system/collection:
    post:
      summary: Build the canonical system operations collection URL for a covered system source surface.
      operationId: buildSystemOperationCollectionLink
      x-not-public-http: true
      requestBody:
        required: true
        content:
          application/vnd.tenantpilot.system-operation-collection-input+json:
            schema:
              $ref: '#/components/schemas/SystemOperationCollectionLinkInput'
      responses:
        '200':
          description: Canonical system collection link emitted through `SystemOperationRunLinks::index()`.
          content:
            application/vnd.tenantpilot.operation-link+json:
              schema:
                $ref: '#/components/schemas/CanonicalOperationLink'
  /internal/operation-run-links/system/detail:
    post:
      summary: Build the canonical system operation detail URL for a covered system source surface.
      operationId: buildSystemOperationDetailLink
      x-not-public-http: true
      requestBody:
        required: true
        content:
          application/vnd.tenantpilot.system-operation-detail-input+json:
            schema:
              $ref: '#/components/schemas/SystemOperationDetailLinkInput'
      responses:
        '200':
          description: Canonical system detail link emitted through `SystemOperationRunLinks::view(...)`.
          content:
            application/vnd.tenantpilot.operation-link+json:
              schema:
                $ref: '#/components/schemas/CanonicalOperationLink'
  /internal/guards/operation-run-link-contract/check:
    post:
      summary: Scan the bounded app-side source surface for raw operation-run link bypasses.
      operationId: checkOperationRunLinkContract
      x-not-public-http: true
      requestBody:
        required: true
        content:
          application/vnd.tenantpilot.operation-run-link-guard-input+json:
            schema:
              $ref: '#/components/schemas/OperationRunLinkGuardCheck'
      responses:
        '200':
          description: Guard completed and found no violations inside the declared boundary.
          content:
            application/vnd.tenantpilot.operation-run-link-guard-report+json:
              schema:
                $ref: '#/components/schemas/OperationRunLinkGuardReport'
        '422':
          description: Guard found one or more raw bypasses outside the allowlist.
          content:
            application/vnd.tenantpilot.operation-run-link-guard-report+json:
              schema:
                $ref: '#/components/schemas/OperationRunLinkGuardReport'
  /admin/operations:
    get:
      summary: Existing canonical admin operations collection route.
      operationId: openAdminOperationsCollection
      responses:
        '200':
          description: Admin monitoring collection renders for an entitled workspace operator.
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Actor is in scope but lacks the required capability.
        '404':
          description: Actor is not entitled to the workspace or tenant-bound records referenced by the current context.
  /admin/operations/{run}:
    get:
      summary: Existing canonical admin operation detail route.
      operationId: openAdminOperationDetail
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Canonical admin run detail renders for an entitled operator.
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Actor is a member in scope but lacks current capability.
        '404':
          description: Actor cannot access the run because of workspace, tenant, or plane isolation.
  /system/ops/runs:
    get:
      summary: Existing canonical system operations collection route.
      operationId: openSystemOperationsCollection
      responses:
        '200':
          description: System monitoring collection renders for an entitled platform user.
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Platform user lacks the required system operations capability.
        '404':
          description: Actor is not entitled to the system plane.
  /system/ops/runs/{run}:
    get:
      summary: Existing canonical system operation detail route.
      operationId: openSystemOperationDetail
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Canonical system run detail renders for an entitled platform user.
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Platform user lacks the required system operations capability.
        '404':
          description: Actor is not entitled to the system plane or the run is not visible there.
components:
  schemas:
    OperationPlane:
      type: string
      enum:
        - admin
        - system
    OperationLinkKind:
      type: string
      enum:
        - collection
        - detail
    CoveredSurfaceKey:
      type: string
      description: Stable identifier for the source surface that emits the canonical link.
    CanonicalNavigationContextInput:
      type: object
      description: |
        Opaque helper-owned navigation context payload passed through the admin helper family
        when a source surface needs canonical back-link or query continuity.
      additionalProperties: true
    AdminOperationCollectionLinkInput:
      type: object
      required:
        - surfaceKey
      properties:
        surfaceKey:
          $ref: '#/components/schemas/CoveredSurfaceKey'
        tenantId:
          type: integer
        tenantExternalId:
          type: string
        navigationContext:
          $ref: '#/components/schemas/CanonicalNavigationContextInput'
        activeTab:
          type: string
        problemClass:
          type: string
        operationType:
          type: string
          description: Optional helper-owned operations table type filter, used by inventory coverage history links.
        allTenants:
          type: boolean
          default: false
      description: Canonical input for `OperationRunLinks::index(...)`.
    AdminOperationDetailLinkInput:
      type: object
      required:
        - surfaceKey
        - runId
      properties:
        surfaceKey:
          $ref: '#/components/schemas/CoveredSurfaceKey'
        runId:
          type: integer
        navigationContext:
          $ref: '#/components/schemas/CanonicalNavigationContextInput'
      description: Canonical input for `OperationRunLinks::view(...)` or `tenantlessView(...)`.
    SystemOperationCollectionLinkInput:
      type: object
      required:
        - surfaceKey
      properties:
        surfaceKey:
          $ref: '#/components/schemas/CoveredSurfaceKey'
      description: Canonical input for `SystemOperationRunLinks::index()`.
    SystemOperationDetailLinkInput:
      type: object
      required:
        - surfaceKey
        - runId
      properties:
        surfaceKey:
          $ref: '#/components/schemas/CoveredSurfaceKey'
        runId:
          type: integer
      description: Canonical input for `SystemOperationRunLinks::view(...)`.
    CanonicalOperationLink:
      type: object
      required:
        - label
        - url
        - plane
        - kind
        - canonicalNoun
      properties:
        label:
          type: string
        url:
          type: string
        plane:
          $ref: '#/components/schemas/OperationPlane'
        kind:
          $ref: '#/components/schemas/OperationLinkKind'
        canonicalNoun:
          type: string
          example: Operation
        preservedQueryKeys:
          type: array
          items:
            type: string
      description: Helper-owned operator-facing link output for canonical operations destinations.
    OperationRunLinkGuardCheck:
      type: object
      required:
        - includePaths
        - allowlistedPaths
        - forbiddenPatterns
      properties:
        includePaths:
          type: array
          items:
            type: string
          examples:
            - - app/Filament/Widgets/Tenant/RecentOperationsSummary.php
              - app/Filament/Pages/InventoryCoverage.php
              - app/Filament/Resources/InventoryItemResource.php
              - app/Filament/Resources/ReviewPackResource.php
              - app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
              - app/Support/Navigation/RelatedNavigationResolver.php
              - app/Filament/System/Pages/Directory/ViewTenant.php
              - app/Filament/System/Pages/Directory/ViewWorkspace.php
              - app/Filament/System/Pages/Ops/Runs.php
              - app/Filament/System/Pages/Ops/ViewRun.php
              - app/Providers/Filament/AdminPanelProvider.php
              - app/Providers/Filament/TenantPanelProvider.php
              - app/Support/Middleware/EnsureFilamentTenantSelected.php
              - app/Http/Controllers/ClearTenantContextController.php
              - app/Support/OpsUx/OperationRunUrl.php
        allowlistedPaths:
          type: array
          items:
            type: string
          examples:
            - - app/Providers/Filament/AdminPanelProvider.php
              - app/Providers/Filament/TenantPanelProvider.php
              - app/Support/Middleware/EnsureFilamentTenantSelected.php
              - app/Http/Controllers/ClearTenantContextController.php
        forbiddenPatterns:
          type: array
          items:
            type: string
          examples:
            - - "route('admin.operations.index'"
              - "route('admin.operations.view'"
              - "/system/ops/runs"
              - "Runs::getUrl("
              - "ViewRun::getUrl("
        acceptedDelegates:
          type: array
          items:
            type: string
          examples:
            - - app/Support/OpsUx/OperationRunUrl.php
      description: Declares the bounded source surface and explicit exceptions for the guard.
    OperationRunLinkGuardViolation:
      type: object
      required:
        - filePath
        - line
        - snippet
        - reason
      properties:
        filePath:
          type: string
        line:
          type: integer
        snippet:
          type: string
        expectedHelper:
          type: string
        reason:
          type: string
      description: Actionable failure output for one raw bypass.
    OperationRunLinkGuardReport:
      type: object
      required:
        - scannedPaths
        - allowlistedPaths
        - violations
      properties:
        scannedPaths:
          type: array
          items:
            type: string
        allowlistedPaths:
          type: array
          items:
            type: string
        acceptedDelegates:
          type: array
          items:
            type: string
        violations:
          type: array
          items:
            $ref: '#/components/schemas/OperationRunLinkGuardViolation'
      description: Report shape returned by the bounded guard check.