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.