openapi: 3.1.0
info:
  title: Cutover Prerequisite Completion Logical Contract
  version: 0.1.0
  summary: Logical completion contract for the remaining runtime and test-harness seams that unblock Spec 288.
x-canonical-command-authority:
  - specs/287-cutover-prerequisite-completion/spec.md
  - specs/287-cutover-prerequisite-completion/plan.md
  - specs/287-cutover-prerequisite-completion/tasks.md
  - specs/287-cutover-prerequisite-completion/quickstart.md
paths:
  /__logical/prerequisites/provider-connection-routes:
    get:
      summary: Provider-connection route retirement contract
      operationId: getProviderConnectionRouteCompletionContract
      responses:
        '200':
          description: Legacy provider-connection aliases to retire and canonical replacements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConnectionRouteContract'
  /__logical/prerequisites/provider-target-scope:
    get:
      summary: Provider target-scope core neutralization contract
      operationId: getProviderTargetScopeCompletionContract
      responses:
        '200':
          description: Shared provider target-scope fields and provider-owned nested detail rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderTargetScopeContract'
  /__logical/prerequisites/environment-scope-persistence:
    get:
      summary: Workspace-first role authority and environment-scope persistence contract
      operationId: getEnvironmentScopePersistenceCompletionContract
      responses:
        '200':
          description: Role-bearing truth and narrowing-only environment scope rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentScopePersistenceContract'
  /__logical/prerequisites/test-helper-cutover:
    get:
      summary: Tenant-panel test-helper cutover contract
      operationId: getTestHelperCutoverCompletionContract
      responses:
        '200':
          description: Shared test helper replacement and named direct-consumer inventory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestHelperCutoverContract'
  /__logical/prerequisites/targeted-validation:
    get:
      summary: Targeted validation contract
      operationId: getTargetedValidationCompletionContract
      responses:
        '200':
          description: Exact targeted validation commands and bounded proof rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TargetedValidationContract'
components:
  schemas:
    ProviderConnectionRouteContract:
      type: object
      required:
        - retiredRouteFamilies
        - canonicalRouteFamilies
        - launchPointFilesInScope
        - behaviorAfterCompletion
      properties:
        retiredRouteFamilies:
          type: array
          items:
            type: string
          default:
            - /admin/tenants/{tenant:slug}/provider-connections
        canonicalRouteFamilies:
          type: array
          items:
            type: string
          default:
            - /admin/provider-connections
            - /admin/provider-connections/{record}
        launchPointFilesInScope:
          type: array
          items:
            type: string
          default:
            - apps/platform/app/Providers/Filament/AdminPanelProvider.php
            - apps/platform/app/Filament/Resources/TenantResource.php
            - apps/platform/app/Filament/Pages/TenantRequiredPermissions.php
            - apps/platform/app/Support/OperationRunLinks.php
            - apps/platform/app/Support/Providers/ProviderReasonTranslator.php
            - apps/platform/app/Support/Verification/VerificationLinkBehavior.php
        behaviorAfterCompletion:
          type: string
          const: Canonical provider-connection routes are the only accepted runtime path.
    ProviderTargetScopeContract:
      type: object
      required:
        - forbiddenSharedPrimaryKeys
        - requiredNeutralSharedFields
        - allowedProviderOwnedNestedFields
      properties:
        forbiddenSharedPrimaryKeys:
          type: array
          items:
            type: string
          default:
            - entra_tenant_id
            - tenantContext
            - target_scope.entra_tenant_id
        requiredNeutralSharedFields:
          type: array
          items:
            type: string
          default:
            - scope_kind
            - scope_identifier
            - scope_display_name
        allowedProviderOwnedNestedFields:
          type: array
          items:
            type: string
          default:
            - provider_profile.microsoft.tenant_id
            - provider_profile.microsoft.authority_tenant
            - provider_profile.microsoft.consent_url
    EnvironmentScopePersistenceContract:
      type: object
      required:
        - roleAuthoritySource
        - narrowingOnlyScopeStore
        - forbiddenPersistenceBehavior
      properties:
        roleAuthoritySource:
          type: string
          const: workspace_memberships
        narrowingOnlyScopeStore:
          type: string
          const: managed_environment_memberships or its in-place successor
        forbiddenPersistenceBehavior:
          type: array
          items:
            type: string
          default:
            - mirrored workspace role values as environment role truth
            - second independent role matrix at environment scope
    TestHelperCutoverContract:
      type: object
      required:
        - retiredHelpers
        - canonicalHelpers
        - directConsumersInScope
      properties:
        retiredHelpers:
          type: array
          items:
            type: string
          default:
            - setTenantPanelContext
        canonicalHelpers:
          type: array
          items:
            type: string
          default:
            - setAdminPanelContext
            - post-cutover admin/workspace context helper
        directConsumersInScope:
          type: array
          items:
            type: string
          default:
            - tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php
            - tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php
    TargetedValidationContract:
      type: object
      required:
        - featureCommand
        - browserCommand
        - formattingCommand
        - outOfScopeProof
      properties:
        featureCommand:
          type: string
          const: export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/ProviderConnections/TenantlessListRouteTest.php tests/Feature/ProviderConnections/TenantlessListScopingTest.php tests/Feature/Auth/WorkspaceFirstManagedEnvironmentAccessTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php)
        browserCommand:
          type: string
          const: export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php)
        formattingCommand:
          type: string
          const: export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)
        outOfScopeProof:
          type: array
          items:
            type: string
          default:
            - no global no-legacy guard suite
            - no full-suite baseline
            - no package execution
            - no guided operations
            - no UI copy cleanup
            - no provider capability expansion