TenantAtlas/specs/171-operations-naming-consolidation/contracts/operation-naming-surface-contract.yaml

openapi: 3.1.0
info:
  title: Operations Naming Consolidation Surface Contract
  version: 1.0.0
  summary: Visible naming contract for existing OperationRun references outside Spec 170.
paths:
  /admin/operations:
    get:
      operationId: listAdminOperations
      summary: Display the canonical admin-plane operations collection.
      responses:
        '200':
          description: Admin operations surface rendered successfully.
        '403':
          description: Authenticated member lacks the required capability within an established scope.
        '404':
          description: Wrong plane, missing scope membership, or inaccessible workspace/tenant context.
      x-visible-naming:
        collectionLabel: Operations
        collectionActionLabels:
          - Open operations
          - View in Operations
        forbiddenCollectionLabels:
          - Runs
          - Open all runs
        summaryPluralNoun: operations
        unchangedBehavior:
          - Existing route helper remains admin.operations.index.
          - Existing workspace and tenant entitlement rules remain authoritative.
  /admin/operations/{run}:
    get:
      operationId: viewAdminOperation
      summary: Display one existing operation record in the admin plane.
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Admin operation detail rendered successfully.
        '403':
          description: Authenticated member lacks the required capability within an established scope.
        '404':
          description: Wrong plane, missing scope membership, or inaccessible operation record.
      x-visible-naming:
        singularLabel: Operation
        actionLabel: Open operation
        identifierPattern: Operation #{id}
        identifierFieldLabel: Operation ID
        forbiddenVisibleLabels:
          - View run
          - Run #{id}
          - Run ID
        unchangedBehavior:
          - Existing route helper remains admin.operations.view.
          - Existing authorization and scope checks remain unchanged.
  /system/ops/runs/{run}:
    get:
      operationId: viewSystemOperation
      summary: Display one existing operation record in the system plane when a shared surface targets platform detail.
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: System operation detail rendered successfully.
        '403':
          description: Authenticated platform user lacks the required capability.
        '404':
          description: Wrong plane or inaccessible operation record.
      x-visible-naming:
        singularLabel: Operation
        actionLabel: Open operation
        identifierPattern: Operation #{id}
        identifierFieldLabel: Operation ID
        forbiddenVisibleLabels:
          - View run
          - Run #{id}
          - Run ID
        unchangedBehavior:
          - System-plane interaction semantics remain owned by Spec 170.
          - Existing route helper remains the system run-detail helper.
  /admin/onboarding:
    get:
      operationId: renderWorkspaceOnboardingOperationReports
      summary: Render workspace-context onboarding and verification surfaces that may link to an existing operation.
      responses:
        '200':
          description: Workspace onboarding surface rendered successfully.
        '403':
          description: Authenticated workspace member lacks the required capability within an established scope.
        '404':
          description: Wrong plane, missing workspace membership, or inaccessible onboarding context.
      x-embedded-surface-rules:
        workflowActionsMayRemain:
          - Start verification
        requiredRecordActionLabel: Open operation
        requiredIdentifierLabels:
          - Operation ID
          - Operation #{id}
        forbiddenRecordLabels:
          - View run
          - Run ID
          - Run #{id}
        notes:
          - Task verbs may remain task-oriented when the UI starts new work rather than naming an existing record.
          - Existing onboarding routing and workspace entitlement semantics remain unchanged.
  /admin/t/{tenant}:
    get:
      operationId: renderTenantEmbeddedOperationReports
      summary: Render tenant-context embedded verification surfaces that may link to an existing operation.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tenant-context surface rendered successfully.
        '403':
          description: Authenticated tenant member lacks the required capability.
        '404':
          description: Wrong plane, missing scope membership, or inaccessible tenant context.
      x-embedded-surface-rules:
        workflowActionsMayRemain:
          - Start verification
        requiredRecordActionLabel: Open operation
        requiredIdentifierLabels:
          - Operation ID
          - Operation #{id}
        forbiddenRecordLabels:
          - View run
          - Run ID
          - Run #{id}
        notes:
          - Task verbs may remain task-oriented when the UI starts new work rather than naming an existing record.
x-summary-copy-rules:
  appliesTo:
    - workspace overviews
    - admin monitoring lifecycle helper banners
    - tenant recent-operations widgets
    - onboarding bootstrap summaries
  requiredPluralNoun: operations
  forbiddenPluralNoun: runs
  notes:
    - Existing counts, route targets, and status semantics remain unchanged.
    - Collection drill-ins may use panel-appropriate collection wording such as View in Operations.