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

Quickstart: Provider Verification Runtime Semantics Stabilization

Purpose

294 is the bounded follow-up to Spec 293. It exists only to stabilize the remaining provider and verification runtime semantics block still failing inside:

• tests/Feature/ProviderConnections
• tests/Feature/Verification

It is not a full-suite repair, not a route-cutover package, and not a broader provider-boundary refresh.

Preconditions

• Stay on branch 294-provider-verification-runtime-semantics.
• Run all PHP, Artisan, and formatter commands through Sail.
• Keep the macOS PATH workaround when using terminal commands in this workspace:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"

• Treat Spec 293 as inherited context only.
• Do not implement any route-cutover or /admin/t/... repair under this package.

Read Order

1. spec.md
2. plan.md
3. research.md
4. data-model.md
5. failure-classification.md
6. tasks.md
7. checklists/requirements.md

Implementation Intent

• Classify the current failing lane before changing tests or runtime.
• Clear fixture-contract drift before widening runtime changes.
• Reuse the current shared owners: StartVerification, ProviderOperationStartGate, OperationRunService, ProviderConnectionSurfaceSummary, and VerificationReportSchema.
• Keep provider-neutral disclosure primary and provider-specific identity detail nested.
• Keep validation bounded to the target feature lane, with one conditional existing provider-connection scope browser smoke only if provider-connection disclosure changes visibly.

Pinned Failure-Classification 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

Pinned Stabilization Seams

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

Grouping Unit

294 tracks one failure group per failing test file or failing scenario cluster that shares one seam and one category. The authoritative grouped baseline lives in failure-classification.md.

Review Scenarios

Scenario 1: Verification start contract

• Canonical startable verification fixtures should return started.
• Repeated active starts should return deduped.
• Post-completion starts should create a new run.
• blocked should remain reserved for real prerequisite failures.

Scenario 2: Provider-operation concurrency

• Same-operation active reruns should dedupe.
• Different active operations on the same provider connection should return one shared scopeBusy follow-through.
• Queue counts and created runs must stay aligned with the shared gate contract.

Scenario 3: Surface and report baselines

• Provider connection surfaces should keep neutral target-scope disclosure as the primary truth.
• Provider-specific Microsoft identity detail may stay nested, but must not replace the neutral disclosure.
• Verification report counts must track the current emitted check inventory, not a stale literal ceiling.

Planned Proof Commands

Full in-scope lane

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification

Verification start cluster

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Verification/VerificationAuthorizationTest.php tests/Feature/Verification/VerificationStartAfterCompletionTest.php tests/Feature/Verification/VerificationStartDedupeTest.php

Provider dispatch and concurrency cluster

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderDispatchGateStartSurfaceTest.php tests/Feature/ProviderConnections/ProviderOperationConcurrencyTest.php

Surface and report baseline cluster

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php tests/Feature/Verification/ProviderConnectionHealthCheckWritesReportTest.php

Conditional existing browser smoke

Run this only if implementation changes visible provider-connection disclosure:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php

Formatting

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

Stop Conditions

Stop and split the work out of 294 if any of the following becomes necessary:

• route-cutover or /admin/t/... repair
• full-suite cleanup outside tests/Feature/ProviderConnections and tests/Feature/Verification
• a new provider abstraction, provider-profile table, capability registry, or verification schema version
• reopening historical Specs 238, 188, 084, or 074 as implementation targets
• adding a new browser family instead of reusing the existing provider-scope smoke

Expected Close-Out State

• the full in-scope ProviderConnections/Verification lane is green
• failure-classification.md reflects the final disposition of every currently failing group
• any visible provider-connection disclosure change is backed by the existing provider-connection scope browser smoke
• no out-of-scope debt has been silently absorbed