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

Implementation Plan: Provider Verification Runtime Semantics Stabilization

Branch: 294-provider-verification-runtime-semantics | Date: 2026-05-11 | Spec: spec.md Input: Feature specification from specs/294-provider-verification-runtime-semantics/spec.md

Note: This plan is produced from the repo's Spec Kit workflow and remains preparation-only. It does not implement application code.

Summary

Stabilize the remaining provider and verification runtime contract after Spec 293 by classifying the current failing lane first, then aligning the shared startable-fixture contract, the shared verification start gate, provider-operation dedupe/scope-busy behavior, provider-connection neutrality disclosure, and verification report summary counts to current repo truth. Keep route-cutover work, full-suite repair, new provider abstractions, and historical-spec rewrites out of scope.

Inherited Baseline / Explicit Delta

Inherited baseline

• Spec 293 already stabilized the route, workspace-aware link, and post-cutover panel baseline.
• The current remaining failing lane is confirmed by cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification. The authoritative prep-time counts and grouped baseline live in failure-classification.md; this plan uses that baseline only as context.
• Historical Specs 238, 188, 084, and 074 remain context only; none of them should be rewritten in this slice.
• The current repo already contains the owner seams this package should reuse: StartVerification, ProviderOperationStartGate, OperationRunService, ProviderConnectionSurfaceSummary, ProviderConnectionTargetScopeNormalizer, ProviderConnectionTargetScopeDescriptor, MicrosoftProviderHealthCheck, and VerificationReportSchema.

Explicit delta in this plan

• Add one spec-local failure-classification.md artifact to pin the observed failure groups, their seams, and their candidate owners before implementation starts.
• Keep the implementation bounded to one feature lane and five pinned seam families.
• Repair fixture contract drift before widening runtime semantics.
• Repair surface/report baseline drift only through the existing shared summary/report owners.
• Reuse one existing provider-connection scope browser smoke only if visible provider-connection disclosure changes.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52
Primary Dependencies: Pest 4, Filament 5.2.1, Livewire 4.1.4, current provider-operation and verification support seams
Storage: no new runtime persistence; one spec-local failure-classification.md artifact only
Testing: focused Pest feature reruns in tests/Feature/ProviderConnections and tests/Feature/Verification, plus conditional reuse of one existing browser smoke
Validation Lanes: confidence, browser only when visible provider-connection disclosure changes
Target Platform: Laravel monolith in apps/platform
Project Type: web application
Performance Goals: keep the slice bounded to the existing feature lane and avoid turning it into a new broad repair lane
Constraints: no full-suite repair, no route-cutover repair, no new provider abstraction, no new schema version, no new panel, no new notification family, and no historical-spec rewrites
Scale/Scope: one provider/verification stabilization slice covering 11 currently failing assertions across seven feature files and a small set of shared owner seams

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

Likely Affected Repo Surfaces

• 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/Services/OperationRunService.php only if targeted reruns prove the run-identity owner needs a one-hop correction
• 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
• existing verification report writer or provider-connection resource/view seams only if targeted reruns prove they are the direct owners

Filament v5 / Surface Notes

• Livewire v4.0+ compliance: all touched admin surfaces remain on Filament v5 with Livewire v4
• Provider registration location: unchanged in apps/platform/bootstrap/providers.php
• Global search rule: ProviderConnectionResource remains non-globally-searchable; no new searchable resource is introduced
• Destructive actions: no new destructive action is planned; touched existing mutations must preserve ->action(...), ->requiresConfirmation(), and server-side authorization
• Asset strategy: no asset registration or filament:assets deployment-step change is planned

Stabilization Fit

• classify the target lane before changing runtime or tests
• align fixture contract drift before classifying runtime regressions
• prefer fixing stale expectations through the current shared owners instead of page-local or test-local shims
• allow a runtime fix only when the targeted rerun proves a canonical shared owner is wrong after fixture alignment
• keep visible provider-scope and report disclosure changes behind existing surfaces only
• keep remaining unrelated debt explicit in failure-classification.md

UI / Surface Guardrail Plan

• Guardrail scope: existing provider connection resource surfaces, existing verification entry points, and existing verification report detail surfaces only
• Native vs custom classification summary: native Filament resource/detail surfaces and existing shared detail surfaces only
• Shared-family relevance: provider connection summary family, verification start-result family, and verification report family
• State layers in scope: table, detail, form, action-result follow-through, and DB-backed report detail only
• Audience modes in scope: operator-MSP, support-platform, and readonly-entitled report viewers
• Decision/diagnostic/raw hierarchy plan: neutral target-scope summary and report summary stay decision-first; nested provider identity detail and per-check evidence remain secondary
• Raw/support gating plan: raw payloads remain absent; provider-owned identity detail remains nested only
• One-primary-action / duplicate-truth control: no new action family; existing primary actions stay primary and no duplicate summary layer is introduced
• Handling modes by drift class or surface: in-scope provider/verification drift is implementation-required; unrelated debt is report-only in failure-classification.md
• Repository-signal treatment: review-mandatory if implementation tries to widen into route cutover, full-suite repair, or new provider abstractions
• Special surface test profiles: standard-native-filament, shared-detail-family
• Required tests or manual smoke: focused feature lane always; one existing provider-connection scope browser smoke only when visible provider-connection disclosure changes
• Exception path and spread control: no exception path is planned; if implementation would need one, stop and reclassify rather than widen silently
• Active feature PR close-out entry: RuntimeSemantics

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: current provider connection summary, current verification start path, current provider-operation start gate, current verification report schema/writer path, and the current shared test-fixture contract
• Shared abstractions reused: StartVerification, ProviderOperationStartGate, OperationRunService, ProviderConnectionSurfaceSummary, ProviderConnectionTargetScopeNormalizer, ProviderConnectionTargetScopeDescriptor, and VerificationReportSchema
• New abstraction introduced? why?: none
• Why the existing abstraction was sufficient or insufficient: the abstractions already exist and own the relevant behavior; the missing piece is contract stabilization, not a new framework
• Bounded deviation / spread control: runtime changes are allowed only inside the current owner seams and only after fixture alignment proves the current owner is at fault

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes
• Central contract reused: ProviderOperationStartGate, StartVerification, OperationRunService, and existing run-link helpers
• Delegated UX behaviors: started, deduped, scopeBusy, blocked, queue-dispatch decisions, and canonical run follow-through links remain delegated to the shared owners above
• Surface-owned behavior kept local: existing provider connection and verification entry points keep initiation placement only
• Queued DB-notification policy: unchanged
• Terminal notification path: unchanged
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes
• Provider-owned seams: nested Microsoft tenant identity details and provider-specific troubleshooting context
• Platform-core seams: neutral target-scope summary, verification start/result semantics, dedupe/scope-busy behavior, and report summary truth
• Neutral platform terms / contracts preserved: provider connection, target scope, provider context, verification report, started, deduped, scope busy, blocked
• Retained provider-specific semantics and why: Microsoft identity detail remains nested because current consent and verification troubleshooting still need it
• Bounded extraction or follow-up path: broader provider-boundary cleanup stays deferred; 294 only stabilizes the confirmed failing lane

Constitution Check

GATE: Must pass before implementation begins and again after the design artifacts are complete.

• Inventory-first, Snapshots-second: PASS. 294 introduces no new inventory or snapshot truth.
• Read/Write Separation by Default: PASS. The slice stabilizes existing start/report behavior only.
• Single Contract Path to Graph: PASS by preservation. No new Graph seam is introduced.
• PROV-001: PASS. Shared neutral disclosure stays primary, provider-specific identity detail stays nested.
• PROP-001, ABSTR-001, V1-EXP-001, and LAYER-001: PASS. No new framework or layer is introduced.
• PERSIST-001 and STATE-001: PASS. The only new vocabulary is spec-local failure classification, not runtime persistence or product state.
• XCUT-001: PASS. Existing shared provider/verification owners are reused.
• RBAC-UX: PASS by preservation. Non-member 404, in-scope no-capability 403, and no new raw capability checks are introduced.
• TEST-GOV-001: PASS. Proof stays in the narrowest honest feature lane with one conditional existing browser smoke only when needed.
• UI-FIL-001: PASS. Existing Filament surfaces remain native; no custom surface or asset family is introduced.
• LEAN-001: PASS. No compatibility shim, no legacy alias, and no historical-spec rewrite is planned.

Gate evaluation: PASS.

Post-design re-check: PASS while the same failure categories, seam names, proving commands, and out-of-scope boundary remain aligned across spec.md, plan.md, research.md, data-model.md, quickstart.md, failure-classification.md, tasks.md, and checklists/requirements.md.

Test Governance Check

• Test purpose / classification by changed surface: Feature, with conditional Browser reuse only when visible provider-connection disclosure changes
• Affected validation lanes: confidence and conditional browser
• Why this lane mix is the narrowest sufficient proof: the failing contract already lives honestly in the targeted feature lane. Optional browser proof is justified only when visible provider-connection disclosure changes on a real provider surface. Verification-report disclosure remains bounded to feature-lane proof in 294.
• Narrowest proving command(s):
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification
  • 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
  • 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
  • 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
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
• Fixture / helper / factory / seed / context cost risks: moderate only around the startable-fixture contract; no broader provider context should become implicit in more tests
• Expensive defaults or shared helper growth introduced?: no; fixture alignment should reduce hidden drift, not widen helper cost
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: standard-native-filament and shared-detail-family remain sufficient
• Closing validation and reviewer handoff: reviewers must rerun the exact commands above, confirm the targeted lane is green, and only require the existing provider-connection scope browser smoke if visible provider-connection disclosure changed
• Budget / baseline / trend follow-up: none beyond feature-local upkeep
• Review-stop questions: did the work widen into route cutover, full-suite repair, or a new provider framework; did it change visible provider/report disclosure without rerunning the named existing browser smoke
• Escalation path: document-in-feature for residual notes; reject-or-split for scope expansion
• Active feature PR close-out entry: RuntimeSemantics
• Why no dedicated follow-up spec is needed: 294 itself is the dedicated follow-up for the remaining provider/verification lane after 293

Review Checklist Status

• Review checklist artifact: checklists/requirements.md
• Review outcome class: acceptable-special-case
• Workflow outcome: keep
• Test-governance outcome: keep
• Resolution note: the package is implementation-ready as one bounded provider/verification stabilization slice following Spec 293
• Escalation rule: if implementation starts repairing unrelated full-suite debt, route cutover, or broader provider-boundary work, stop and split it out of 294

Rollout Considerations

• record the currently observed failing groups in failure-classification.md before changing tests or runtime
• align fixture contract drift before calling anything a runtime regression
• stabilize verification start semantics before provider-operation concurrency semantics, because both depend on the same gate ownership
• stabilize surface/report baseline drift after the runtime start contract settles, so tests do not chase a moving owner contract
• rerun the full targeted lane after each bounded slice, not just isolated files
• use the existing provider-connection scope browser smoke only when visible provider-connection disclosure actually changes

Risk Controls

• reject any implementation that widens into full-suite repair outside the targeted lane
• reject any implementation that reopens route-cutover or workspace-aware link work already handled by Spec 293
• reject any implementation that adds a new provider framework, new profile table, or new verification schema version
• reject any implementation that fixes visible disclosure drift only in tests while leaving the shared summary/report owner inconsistent
• reject any implementation that leaves remaining target-lane failures unclassified in failure-classification.md

Research & Design Outputs

• research.md records the stabilization decisions, rejected alternatives, and evidence anchors
• data-model.md captures the pinned failure categories, seam inventory, and failure-classification.md structure
• quickstart.md gives reviewers the read order, review scenarios, exact proof commands, and stop conditions
• failure-classification.md records the confirmed current failing groups, their seams, categories, candidate owners, and bounded follow-up status
• checklists/requirements.md records the readiness and bounded-scope checks for the package

Project Structure

Documentation (this feature)

specs/294-provider-verification-runtime-semantics/
├── checklists/
│   └── requirements.md
├── data-model.md
├── failure-classification.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md

Source Code (repository root)

apps/platform/
├── app/
│   ├── Services/
│   └── Support/
└── tests/
    ├── Browser/
    └── Feature/

Structure Decision: keep the package inside the existing Laravel app and test structure. Reuse current provider/verification tests, shared owner seams, and one existing browser smoke instead of inventing a new stabilization subsystem.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Spec-local failure-classification vocabulary	The lane needs one shared bounded way to separate fixture drift, runtime regression, concurrency drift, and surface/report drift before implementation	Ad hoc notes or one-off fixes would make the package drift back into unsourced local patches