TenantAtlas/specs/216-provider-dispatch-gate/quickstart.md

Quickstart: Provider-Backed Action Preflight and Dispatch Gate Unification

Goal

Validate that every covered operator-triggered provider-backed start now resolves click-time provider blockers, same-operation dedupe, and protected-scope conflicts before queue admission, while preserving one shared operator vocabulary and truthful Monitoring → Operations drill-in for accepted work.

Prerequisites

1. Start Sail if it is not already running.
2. Use a tenant member with the exact capability required by the target action host.
3. Prepare at least one tenant with:
   • one usable provider connection,
   • one blocked provider condition such as missing default connection, missing consent, or unusable credentials,
   • one active queued or running provider-backed OperationRun for same-operation dedupe checks,
   • one active queued or running provider-backed OperationRun for cross-operation scope_busy checks,
   • one restore run ready for execute validation,
   • one onboarding session with provider verification and bootstrap steps available.
4. Keep a second user or session available if you want to validate tenant isolation and initiator-only notification behavior.

Focused Automated Verification

Run formatting first:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Then run the narrowest focused suite that proves the contract:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Unit/Providers/ProviderOperationStartGateTest.php \
  tests/Unit/Providers/ProviderOperationStartResultPresenterTest.php \
  tests/Feature/ProviderConnections/ProviderDispatchGateStartSurfaceTest.php \
  tests/Feature/Tenants/TenantProviderBackedActionStartTest.php \
  tests/Feature/Workspaces/ManagedTenantOnboardingProviderStartTest.php \
  tests/Feature/Restore/RestoreRunProviderStartTest.php \
  tests/Feature/Directory/ProviderBackedDirectoryStartTest.php \
  tests/Feature/Operations/ProviderBackedRunReasonAlignmentTest.php

If only one action host changed during implementation, rerun the smallest relevant subset before broadening to the full focused suite.

Manual Validation Pass

1. Tenant-scoped start surfaces

Trigger a covered tenant-scoped provider-backed action such as verification, restore execute, or directory sync in these four conditions:

• blocked by missing or unusable provider access,
• deduped by an equivalent active run,
• scope_busy because a different covered operation is already active for the same provider connection,
• accepted with a valid explicit provider connection.

Confirm that:

• no blocked case queues background work,
• the operator sees one consistent accepted/deduped/scope-busy/blocked vocabulary,
• each non-blocked result points to the correct existing or accepted run,
• and no page-local notification copy contradicts the shared contract.

2. Provider-connection resource surfaces

From the provider-connection list and detail pages, start the covered connection-scoped actions.

Confirm that:

• the same blocker or active-run condition produces the same outcome category used on tenant surfaces,
• the provider connection identity shown to the operator matches the accepted run context,
• and connection lifecycle actions remain where they were before this feature.

3. Restore execute flow

Start a restore execution from the existing restore surface.

Confirm that:

• existing preview, warning, and confirmation behavior remains intact,
• blocked preflight prevents queue admission before execution starts,
• accepted execution opens the canonical run link,
• and restore-specific destructive semantics are unchanged apart from the unified start contract.

4. Onboarding verification and bootstrap

Use the onboarding wizard to trigger the provider verification step and the bootstrap step.

Confirm that:

• provider verification uses the same outcome categories as the other covered action hosts,
• bootstrap no longer admits multiple provider-backed runs concurrently for the same connection,
• a blocked, deduped, or scope_busy bootstrap attempt does not leave hidden extra queued work behind,
• and any remaining bootstrap work is visible as a follow-up state on the existing step rather than on a new workflow page.

5. Monitoring → Operations run detail

Open the run detail pages linked from accepted, deduped, and scope_busy results.

Confirm that:

• accepted work shows the same provider connection identity that was chosen at click time,
• run detail and terminal notification reason translation align with the same problem class used at the start surface,
• blocked starts remain distinguishable from accepted work that later fails,
• and no cross-tenant provider identity or active-run existence leaks through canonical monitoring views.

6. Authorization and isolation non-regression

Confirm that:

• non-members still receive 404 behavior and learn nothing about provider readiness or active runs in other tenants,
• members missing the required capability still receive server-enforced 403 on execution,
• accepted-run notifications remain initiator-only,
• and no new start action bypasses the central capability registry.

7. Ten-second scan check

Timebox the first visible read of one result from each action-host family:

• tenant-scoped start surface,
• provider-connection surface,
• onboarding provider step,
• Monitoring run detail.

Confirm that within 10 seconds the operator can answer:

• did the operation get accepted,
• if not, why not,
• and what should happen next.

Final Verification

Before merge, re-run:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Unit/Providers/ProviderOperationStartGateTest.php \
  tests/Unit/Providers/ProviderOperationStartResultPresenterTest.php \
  tests/Feature/Tenants/TenantProviderBackedActionStartTest.php \
  tests/Feature/ProviderConnections/ProviderDispatchGateStartSurfaceTest.php \
  tests/Feature/ProviderConnections/ProviderConnectionHealthCheckStartSurfaceTest.php \
  tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php \
  tests/Feature/Filament/TenantVerificationReportWidgetTest.php \
  tests/Feature/Restore/RestoreRunProviderStartTest.php \
  tests/Feature/RestoreRunWizardExecuteTest.php \
  tests/Feature/RestoreRunRerunTest.php \
  tests/Feature/Directory/ProviderBackedDirectoryStartTest.php \
  tests/Feature/DirectoryGroups/StartSyncFromGroupsPageTest.php \
  tests/Feature/DirectoryGroups/StartSyncTest.php \
  tests/Feature/TenantRBAC/RoleDefinitionsSyncNowTest.php \
  tests/Feature/Workspaces/ManagedTenantOnboardingProviderStartTest.php \
  tests/Feature/ManagedTenantOnboardingWizardTest.php \
  tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php \
  tests/Feature/Filament/RestoreRunUiEnforcementTest.php \
  tests/Feature/Operations/ProviderBackedRunReasonAlignmentTest.php \
  tests/Feature/OpsUx/CanonicalViewRunLinksTest.php \
  tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php \
  tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php \
  tests/Feature/OpsUx/NoQueuedDbNotificationsTest.php \
  tests/Feature/Guards/ProviderDispatchGateCoverageTest.php \
  tests/Feature/Guards/ActionSurfaceContractTest.php \
  tests/Feature/Guards/TestLaneManifestTest.php

If broader confidence is wanted after the focused suite, offer a full application test run as a separate follow-up step.