openapi: 3.1.0
info:
  title: Deferred Embedded Operation Surface Contract
  version: 1.0.0
  summary: CTA hierarchy and scope contract for tenant-detail and onboarding surfaces that reference existing OperationRun records.
paths:
  /admin/tenants/{record}:
    get:
      operationId: renderTenantDetailEmbeddedOperationSurfaces
      summary: Render tenant-detail embedded widgets that may drill into the canonical operations viewers.
      parameters:
        - name: record
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tenant detail surface rendered successfully.
        '403':
          description: Authenticated tenant member lacks the required capability within the established tenant scope.
        '404':
          description: Wrong plane, missing workspace or tenant membership, or inaccessible tenant detail record.
      x-surface-rules:
        recentOperationsSummary:
          canonicalCollectionRoute: /admin/operations
          canonicalDetailRoute: /admin/operations/{run}
          primaryInspectModel: Row-level Open operation links for displayed records.
          collectionAffordance:
            allowed: true
            prominence: secondary
            scopeRequirement: Any remaining collection affordance must make broader admin scope explicit through nearby copy or placement.
          forbiddenPatterns:
            - A header-level collection CTA with equal emphasis to row-level inspect links.
        tenantVerificationWidget:
          primaryCtaByState:
            noRun: Start verification
            activeRun: Open operation
            completedRun: Open operation
            archivedOrInactive: none
          rerunPath:
            owner: Tenant detail header action
            label: Verify configuration
          inlineSecondaryCtasAllowed: []
      x-unchanged-behavior:
        - Existing authorization, capability checks, and tenant/workspace isolation remain authoritative.
        - Existing OperationRun lifecycle, notification timing, and route helpers remain unchanged.
  /admin/onboarding:
    get:
      operationId: renderOnboardingVerificationOperationSurfaces
      summary: Render onboarding verification workflow controls plus embedded report and technical-details surfaces.
      responses:
        '200':
          description: Onboarding verification surface rendered successfully.
        '403':
          description: Authenticated workspace member lacks the required capability within the established workspace scope.
        '404':
          description: Wrong plane, missing workspace membership, or inaccessible onboarding context.
      x-surface-rules:
        workflowControls:
          primaryCtaByState:
            noRun: Start verification
            activeRun: Refresh
            completedRun: none
        reportSurface:
          currentRunInspect:
            allowed: true
            prominence: primary
            labelFamily:
              - Open operation
          previousRunInspect:
            allowed: true
            prominence: secondary
            placement: diagnostics only
        technicalDetails:
          advancedMonitoringLink:
            allowed: true
            prominence: secondary
            visibilityRule: Only when the operator can access the destination and the link is explicitly labeled as advanced.
      x-unchanged-behavior:
        - Existing onboarding workflow semantics, session fields, and verification execution behavior remain unchanged.
        - Existing step progression and permission-assist behavior remain unchanged.
  /admin/operations:
    get:
      operationId: listAdminOperations
      summary: Canonical admin-plane operations collection used by embedded drill-ins.
      responses:
        '200':
          description: Admin operations collection rendered successfully.
        '403':
          description: Authenticated member lacks the required capability within an established scope.
        '404':
          description: Wrong plane, missing scope membership, or inaccessible workspace or tenant context.
      x-canonical-role:
        role: collection-destination
        visibleNoun: Operations
        unchangedBehavior:
          - Existing route helper remains authoritative.
          - This feature only changes how embedded surfaces explain navigation into this collection.
  /admin/operations/{run}:
    get:
      operationId: viewAdminOperation
      summary: Canonical admin-plane operation detail used by embedded drill-ins.
      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-canonical-role:
        role: detail-destination
        visibleNoun: Operation
        unchangedBehavior:
          - Existing route helper remains authoritative.
          - Existing membership and capability checks remain unchanged.
  /admin/t/{tenant}:
    get:
      operationId: tenantDashboardReference
      summary: Reference route for the table-based tenant dashboard operations widget.
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tenant dashboard rendered successfully.
      x-scope-status:
        status: out-of-scope
        rationale: The table-based recent-operations widget on the tenant dashboard is already declaration-backed and is not part of the deferred embedded-surface retrofit.