TenantAtlas/specs/294-provider-verification-runtime-semantics/research.md

# Research: Provider Verification Runtime Semantics Stabilization

## Pinned Failure-Classification Categories

`294` uses exactly these spec-local categories:

- `surface-or-report-baseline-drift`
- `fixture-contract-drift`
- `provider-verification-runtime-regression`
- `dedupe-concurrency-contract-drift`
- `out-of-scope-existing-debt`
- `resolved-or-not-needed`

These categories are implementation-tracking vocabulary only. They do not become runtime product state.

## Pinned Stabilization Seams

`294` stabilizes exactly these seam families:

- `provider-neutrality-surface`
- `shared-startable-fixtures`
- `verification-start-contract`
- `provider-dispatch-concurrency`
- `verification-report-summary`

## Decision 1: Classify the targeted failing lane before changing anything

- The package starts with the already confirmed failing command `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification`.
- `failure-classification.md` records every currently failing group before any implementation work begins.
- This keeps `294` bounded to the confirmed provider/verification lane instead of silently widening into broader suite repair.

## Decision 2: Fixture contract drift must be cleared before runtime semantics are widened

- Current repo truth already has a canonical startable verification fixture path: `createUserWithTenant(..., fixtureProfile: 'credential-enabled')` or an equivalent helper path that seeds a truthful startable Microsoft provider connection.
- Hand-built provider connections that look plausible but miss canonical prerequisites may legitimately block before queue dispatch.
- Therefore, implementation must align startable fixtures first and only treat remaining mismatches as runtime regressions after that alignment.

## Decision 3: `StartVerification` and `ProviderOperationStartGate` remain the runtime owners

- `StartVerification` owns provider verification start, dedupe, and new-run-after-completion behavior.
- `ProviderOperationStartGate` owns shared provider-operation dedupe versus `scopeBusy` behavior, stale-queued cleanup, and blocked-start behavior.
- `294` should stabilize those owners, not add a new semantics layer around them.

## Decision 4: Provider-neutral disclosure stays primary, provider-specific identity detail stays nested

- `ProviderConnectionSurfaceSummary` and the target-scope descriptor/normalizer already define the neutral summary path.
- The current failing neutrality test proves the detail baseline drift lives at that disclosure seam, not in a broader route or panel contract.
- Microsoft tenant identity detail remains allowed as nested provider-owned context, but it should not replace the neutral top-line summary.

## Decision 5: Verification report totals must track the current emitted inventory

- `ProviderConnectionHealthCheckWritesReportTest` currently fails because the report emits more checks than a stale ceiling expects.
- `VerificationReportSchema` validates shape, not the feature-local ceiling.
- Therefore, the implementation should anchor test expectations to the current emitted inventory and current report writer behavior, not to a stale literal maximum.

## Decision 6: Browser proof stays conditional and reused, not expanded

- The primary proof lane is the targeted ProviderConnections/Verification feature suite.
- If implementation changes visible provider-connection disclosure, reuse the existing `tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php` only. Verification-report disclosure remains bounded to feature-lane proof in `294`.
- Do not add a new browser family or a second broad smoke lane under `294`.

## Rejected Alternatives

### Rejected: fold the work back into Spec `293`

That would blur the route-cutover stabilization boundary and make the post-cutover handoff ambiguous.

### Rejected: reopen Spec `238`, Spec `188`, Spec `084`, or Spec `074`

Those packages are historical context. `294` should treat them as context and stabilize only the current remaining failing lane.

### Rejected: split provider and verification into separate micro-specs

The same start gate, fixture contract, and report summary seams would be duplicated across two packages.

### Rejected: widen to a full-suite or broader provider-boundary repair

That would exceed the user-provided bounded scope and bury the actual remaining seam under unrelated work.

## Evidence Anchors

- `apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php`
- `apps/platform/tests/Feature/ProviderConnections/ProviderDispatchGateStartSurfaceTest.php`
- `apps/platform/tests/Feature/ProviderConnections/ProviderOperationConcurrencyTest.php`
- `apps/platform/tests/Feature/Verification/VerificationAuthorizationTest.php`
- `apps/platform/tests/Feature/Verification/VerificationStartAfterCompletionTest.php`
- `apps/platform/tests/Feature/Verification/VerificationStartDedupeTest.php`
- `apps/platform/tests/Feature/Verification/ProviderConnectionHealthCheckWritesReportTest.php`
- `apps/platform/tests/Pest.php`
- `apps/platform/app/Services/Verification/StartVerification.php`
- `apps/platform/app/Services/Providers/ProviderOperationStartGate.php`
- `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php`
- `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php`
- `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeDescriptor.php`
- `apps/platform/app/Services/Providers/MicrosoftProviderHealthCheck.php`
- `apps/platform/app/Support/Verification/VerificationReportSchema.php`

## Boundary Summary

- `294` is a provider/verification stabilization package, not a route-cutover package.
- `293` remains untouched.
- Historical Specs `238`, `188`, `084`, and `074` remain untouched.
- The package keeps the proving lane bounded to the targeted feature folders and one conditional existing browser smoke.