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:

```bash
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:

```bash
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:

```bash
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.