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

Feature Specification: Provider Verification Runtime Semantics Stabilization

Feature Branch: 294-provider-verification-runtime-semantics
Created: 2026-05-11
Status: Ready
Input: User description: "Prepare Spec 294 as the bounded follow-up to Spec 293. Keep scope limited to the remaining provider/verification failure block in tests/Feature/ProviderConnections and tests/Feature/Verification, covering provider/verification runtime semantics, fixture contracts, dedupe/concurrency behavior, and small surface/report baseline drifts. No application implementation in this prep step."

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Spec 293 stabilized the post-cutover route and workspace-aware baseline, but the remaining red block is now concentrated in provider and verification runtime semantics. The current repo truth still leaves disagreement between provider connection surface expectations, startable verification fixture contracts, shared start-gate dedupe/scope-busy behavior, and verification report count baselines.
• Today's failure: at prep time, the confirmed targeted lane cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification grouped 11 failing assertions into 7 tracked failure groups. The authoritative baseline snapshot lives in failure-classification.md. Those groups cover one provider-neutrality detail drift, one provider-dispatch start-surface mismatch, one grouped provider-operation concurrency cluster, one verification report summary-count drift, one verification authorization start mismatch, one grouped verification restart/dedupe cluster, and one grouped verification post-completion cluster. None of those failures are primarily /admin/t/... or workspace-route cutover issues anymore.
• User-visible improvement: operators and maintainers get one truthful provider/verification contract again: canonical startable verification flows start or dedupe when the connection is truly startable, blocked states stay reserved for real prerequisite failures, cross-operation scope-busy behavior remains consistent, provider-connection detail surfaces keep neutral target-scope disclosure with provider-specific identity detail nested intentionally, and verification report summaries reflect the current emitted check inventory instead of stale hard-coded totals.
• Smallest enterprise-capable version: one stabilization spec that classifies the remaining provider/verification failure groups first, aligns the shared startable-fixture contract, keeps StartVerification and ProviderOperationStartGate as the single runtime owners of started/deduped/scope-busy/blocked semantics, refreshes the provider-connection neutrality baseline and verification report summary-count baseline to current repo truth, and validates the result with the targeted ProviderConnections/Verification lane plus conditional reuse of the existing provider-connection scope browser smoke only when provider-connection disclosure changes visibly.
• Explicit non-goals: no full-suite repair, no route-cutover repair, no Package Execution work, no Guided Operations work, no new provider abstraction or provider-profile table, no new verification schema version, no new panel, no new globally-searchable resource, no new notification policy, no broad UX redesign, and no reopening of historical Specs 238, 188, 084, or 074 as refresh targets.
• Permanent complexity imported: one spec-local failure-classification.md artifact, one bounded failure-category inventory, one bounded seam inventory, and focused tasks against existing provider/verification owner seams. No new runtime persistence, no new abstraction family, and no new product surface are introduced.
• Why now: after Spec 293, this is the only confirmed remaining red cluster that is still tightly bounded and repo-ready. Leaving it unresolved would force later provider, verification, or quality-gate work to absorb the same runtime and fixture drift repeatedly.
• Why not local: the failures span shared runtime owners (StartVerification, ProviderOperationStartGate, OperationRunService identity behavior if implicated), shared provider summary output, verification report production, and the test-fixture contract in tests/Pest.php and target lane call sites. A one-file patch would hide rather than solve the contract disagreement.
• Approval class: Cleanup
• Red flags triggered: cross-cutting runtime stabilization, temptation to fold the work back into Spec 293, and temptation to widen into a broader provider-boundary or full-suite repair. Defense: the package is explicitly pinned to one confirmed failing lane, one failure-classification vocabulary, and existing owner seams only.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve

Review Outcome

• Outcome class: acceptable-special-case
• Workflow outcome: keep
• Test-governance outcome: keep
• Reason: the active auto queue remains intentionally empty, but this user-provided manual follow-up is still justified because current repo truth shows one bounded remaining provider/verification runtime seam after Spec 293, and the package stays narrower than reopening a broader cutover or provider-boundary lane.
• Workflow result: Ready for implementation as one bounded provider/verification stabilization slice that follows Spec 293 without rewriting it.

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

Candidate Selection Gate

• Selected candidate: Provider Verification Runtime Semantics Stabilization
• Source location: explicit user-provided follow-up candidate anchored to specs/293-post-cutover-suite-stabilization/ plus the confirmed failing command cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification
• Why selected now: the repo no longer shows route-cutover or workspace-link debt as the primary blocker inside this lane; the remaining failures now sit exactly on provider/verification runtime seams that later features would otherwise keep rediscovering.
• Why close alternatives were deferred:
  • refreshing Spec 293 directly would blur the handoff boundary between route-cutover stabilization and provider/verification runtime follow-up
  • reopening Spec 238 would rewrite a historical package instead of treating its failing surface assertion as stabilization context
  • reopening Spec 188, Spec 084, or Spec 074 would mix broader historical cleanup or feature foundations back into one targeted follow-up
  • splitting provider and verification into separate micro-specs would duplicate the same start gate, fixture, and report seams across two packages
  • widening to a broader full-suite repair would exceed the user-provided bounded goal
• Roadmap relationship: post-cutover stabilization follow-through within the current workspace-first and provider-boundary hardening trajectory; this is not a new roadmap theme or an automatic next-best-prep queue promotion
• Completed-spec guardrail result: Spec 238 already carries implementation close-out history and is context only; Spec 293 already exists as its own stabilization package with checklist and failure-classification artifacts and must not be rewritten; Specs 188, 084, and 074 remain historical foundation context and are excluded from refresh in this prep pass
• Smallest viable implementation slice: classify and fix only the current failing ProviderConnections/Verification lane across shared startable fixtures, shared start-gate semantics, provider-neutrality surface baseline, and verification report summary counts
• Proposed concise feature description to feed into specify: Stabilize the remaining provider connection and verification runtime contract so current start, dedupe, scope-busy, neutral disclosure, and report-summary behavior match one canonical repo-truth baseline after Spec 293

Spec Scope Fields (mandatory)

• Scope: workspace + managed-environment + canonical operations follow-through
• Primary Routes:
  • /admin/provider-connections
  • /admin/provider-connections/{record}
  • /admin/provider-connections/{record}/edit
  • existing workspace/environment entry points that launch provider verification or provider-backed operations through the admin panel
  • canonical admin.operations.view follow-through for verification report detail
• Data Ownership:
  • ProviderConnection remains the existing workspace-owned, managed-environment-scoped provider binding record
  • ProviderCredential remains the existing provider-owned secret record attached to one ProviderConnection
  • OperationRun remains execution truth, and context.verification_report remains the only persisted verification report artifact used by this slice
  • no new persisted table, profile record, or registry is introduced
  • failure-classification.md is a spec-local prep artifact only and is not runtime truth
• RBAC:
  • workspace membership remains the first entitlement boundary
  • managed-environment access remains the second entitlement boundary
  • existing provider-view and provider-run capabilities continue to gate provider connection detail, verification start, and provider-backed operations
  • non-members or wrong-scope actors remain 404
  • in-scope actors missing capability remain 403

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: N/A - this slice does not add a new canonical-view surface
• Explicit entitlement checks preventing cross-tenant leakage: existing provider-connection and verification follow-through surfaces continue to require workspace plus managed-environment entitlement, and this slice must not loosen that boundary while stabilizing start/report semantics

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): provider connection detail summaries, verification start results, canonical run follow-through, verification report summaries, and shared test-fixture contracts
• Systems touched:
  • 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
  • existing OperationRunService, VerificationReportWriter, and provider-connection resource or view seams only if the targeted reruns prove they are the direct owners
• Existing pattern(s) to extend: the current provider-operation start gate, the current verification start path, the current provider target-scope summary path, the current verification report schema/writer path, and the repo's current createUserWithTenant(..., fixtureProfile: 'credential-enabled') startable-fixture contract
• Shared contract / presenter / builder / renderer to reuse: StartVerification, ProviderOperationStartGate, OperationRunService, ProviderConnectionSurfaceSummary, ProviderConnectionTargetScopeNormalizer, ProviderConnectionTargetScopeDescriptor, and VerificationReportSchema
• Why the existing shared path is sufficient or insufficient: the repo already has the correct shared owners; the missing piece is stabilizing their current contract against stale fixture assumptions, stale report-count baselines, and stale surface assertions rather than introducing a new provider or verification framework
• Allowed deviation and why: only minimal runtime fixes are allowed later if a targeted rerun proves a canonical shared owner is wrong after fixture alignment. Reopening route cutover, adding a new provider abstraction, or broadening verification schema scope is forbidden.
• Consistency impact: provider connection detail, verification start outcomes, provider-operation concurrency, and verification report summaries must all describe the same connection and the same run-state contract
• Review focus: reviewers must verify that implementation reuses the existing shared owners, aligns fixtures before widening runtime changes, and keeps the package inside the confirmed failing lane

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: yes
• Shared OperationRun UX contract/layer reused: ProviderOperationStartGate, StartVerification, OperationRunService, OperationRunLinks, and the existing provider-operation start result path
• Delegated start/completion UX behaviors: current shared start-gate logic remains responsible for started, deduped, scopeBusy, and blocked semantics, queue-dispatch decisions, and canonical run follow-through links; this slice only stabilizes the conditions under which those outcomes occur and how they are asserted
• Local surface-owned behavior that remains: existing provider-connection list/detail actions and existing verification entry points continue to own only initiation inputs and local follow-up placement
• Queued DB-notification policy: N/A - unchanged
• Terminal notification path: unchanged central lifecycle mechanism
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: provider connection default-visible summary language, nested provider identity detail, provider-operation start context, verification report summary counts, and verification start result semantics
• Neutral platform terms preserved or introduced: provider connection, target scope, provider context, verification report, credential source, effective client identity, started, deduped, scope busy, and blocked
• Provider-specific semantics retained and why: Microsoft tenant identifiers and contextual identity details remain provider-owned nested detail where current consent, verification, and troubleshooting flows still need them
• Why this does not deepen provider coupling accidentally: this slice stabilizes the shared neutral summary and start contract while keeping Microsoft-specific detail nested instead of re-promoting it into the primary shared surface or shared run outcome truth
• Follow-up path: broader provider-boundary or future multi-provider work stays deferred; 294 only stabilizes the currently failing provider/verification lane

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Provider connection resource list/detail/edit baselines	yes	Native Filament resource plus shared provider summary primitives	provider connection summary and action family	table, detail, form	no	Existing surfaces only; no new route family or resource
Verification start results on existing provider and verification entry points	yes	Existing action surfaces over shared start-gate logic	start result semantics, run-link follow-through, blocked guidance	action, notification, route follow-through	no	No new action family or notification family
Verification report viewer / operations detail baseline	yes	Existing shared detail surfaces and DB-backed report viewer	verification report summary and disclosure order	detail, page	no	Existing viewer only; no new report surface

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Provider connection resource family	Primary Decision Surface	Operator decides whether the connection is usable and whether verification or another provider action should start	target scope, consent, verification, and current readiness summary	nested provider identity details, capability detail, and recent run follow-through	Primary because this is the surface that owns the provider binding and its immediate next actions	follows the existing provider-connection workflow	removes the need to infer scope from stale or duplicated labels
Verification report viewer / operations detail	Secondary Context Surface	Operator confirms what the latest verification run actually proved after a start, dedupe, or blocked outcome	overall summary, counts, and current next steps	per-check evidence pointers and nested provider-owned detail	Secondary because it explains the result of a previously made action rather than owning the action itself	stays aligned with current operations follow-through	keeps run evidence behind the existing report viewer instead of duplicating it on start surfaces

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Provider connection resource family	operator-MSP, support-platform	target scope, consent, verification, readiness summary	nested provider identity details and provider capability summary	raw secrets never appear; provider-owned identifiers stay secondary	existing primary provider action for the current surface	provider-owned detail stays nested and credential data stays hidden	one shared target-scope summary remains the primary truth across list/detail/edit
Verification report viewer / operations detail	operator-MSP, support-platform, readonly-entitled members	overall summary, counts, and next steps from stored report data	per-check status, reason code, and evidence pointers	raw provider payloads remain out of scope and unavailable by design	View run or existing report follow-through	raw payloads remain absent; support detail stays nested if already available elsewhere	the report summary states the outcome once and later sections add evidence rather than duplicating the same blocker text

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Provider connection resource family	List / Detail / Integrations	CRUD / List-first Resource	Open the connection or start the existing provider action appropriate to the row/detail surface	full-row inspect on list; dedicated detail page for record truth	required on list	grouped secondary actions remain in the existing More or header placement	unchanged existing destructive actions only	/admin/provider-connections	/admin/provider-connections/{record}	workspace, managed environment, provider, target scope	Provider connection	target scope plus consent and verification state	none
Verification report viewer / operations detail	Detail / Evidence / Follow-through	Shared detail surface	Review the latest verification outcome and next steps	explicit open of the existing operations or report detail	forbidden	existing secondary links only	no new destructive action	inherited current collection or follow-through entry point	canonical admin.operations.view or embedded existing report viewer	workspace, managed environment, run identity	Verification report	overall summary and counts	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Provider connection resource family	Workspace operator	Decide whether the connection is the right binding and whether provider work can start now	List/detail resource	Is this the right connection, and is it startable or follow-up-worthy right now?	target scope, consent, verification, readiness summary	nested provider identity details, capability summary, and recent run continuity	consent, verification, readiness	existing provider actions only	Open connection, Check connection, Inventory sync, Compliance snapshot	unchanged existing lifecycle or credential mutations only
Verification report viewer / operations detail	Workspace operator or readonly-entitled member	Understand what the most recent verification run proved and what to do next	Shared report/detail surface	What did the last verification actually prove?	overall summary, counts, and next steps	per-check reason codes and evidence pointers	verification outcome and per-check status	none on the report viewer itself	View run or existing follow-through link	none added by this slice

UI Action Matrix (mandatory when Filament is changed)

294 does not add a new action family. The matrix below pins the existing operator-facing action surfaces whose disclosure and runtime semantics are being stabilized.

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Provider connections list	/admin/provider-connections	Existing New connection header action remains; no new header action is added by 294	Clickable row to provider connection detail	Existing row More actions remain secondary; no new visible primary row mutation is introduced	none added by 294	Existing New connection empty-state flow remains	n/a	n/a	existing only	294 stabilizes disclosure and start-result truth only. The list keeps neutral target-scope visibility and existing provider-action affordances.
Provider connection detail	/admin/provider-connections/{record}	No new header action labels	Dedicated detail page	n/a	none	n/a	Existing grouped provider actions Edit, Check connection, Inventory sync, and Compliance snapshot remain secondary and unchanged in count	n/a	existing only	The detail page may change default-visible disclosure, but 294 does not introduce a new detail action surface or a new destructive action.
Provider connection edit	/admin/provider-connections/{record}/edit	No new header action labels	Dedicated edit page	n/a	none	n/a	Existing grouped secondary actions remain secondary	Existing Save and Cancel remain unchanged	existing only	294 may stabilize supporting disclosure around the edit form, but does not change the edit-page action contract.
Verification report viewer / operations detail	Canonical admin.operations.view follow-through for verification report detail	none added by 294	Dedicated detail page or existing follow-through viewer	n/a	none	n/a	Existing View run or equivalent follow-through remains the primary inspect action; no new mutation is introduced	n/a	existing only	Report disclosure may change through summary truth, but this slice does not add report-header mutations, bulk actions, or destructive actions.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no runtime persistence; one spec-local failure-classification.md artifact only
• New abstraction?: no
• New enum/state/reason family?: yes, one spec-local failure-classification vocabulary for the implementation workflow only
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: provider connection and verification flows currently disagree on what should start, dedupe, block, or count as the current report baseline, which makes the feature lane red and teaches the wrong runtime contract to maintainers and operators.
• Existing structure is insufficient because: the repo already has the runtime owners, but without one bounded stabilization package the remaining seam drift would be fixed piecemeal across tests and app code without a single shared contract.
• Narrowest correct implementation: classify the failing groups first, then adjust only the existing provider/verification owner seams and target lane tests until the current shared contract is explicit and green.
• Ownership cost: low to moderate; maintain one spec-local failure classification artifact and keep the same category and seam names aligned across the prep package.
• Alternative intentionally rejected: folding the work back into Spec 293, reopening older historical specs, or widening to a full-suite repair. All would increase scope without improving the bounded provider/verification contract itself.
• Release truth: current-release runtime and test-governance stabilization only

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, and compatibility-only tests are out of scope. Canonical replacement remains preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature, with conditional Browser reuse only if visible provider-connection disclosure changes
• Validation lane(s): confidence and browser only when needed
• Why this classification and these lanes are sufficient: the package is explicitly bounded to tests/Feature/ProviderConnections and tests/Feature/Verification. Those tests already expose the remaining runtime seams honestly. One existing browser smoke may be reused only when implementation changes visible provider-connection disclosure on a real surface.
• New or expanded test families: none new by design; reuse the existing ProviderConnections and Verification feature files plus one existing provider-connection scope browser smoke if the implementation touches visible provider-connection disclosure
• Fixture / helper cost impact: moderate only because the package must stabilize the shared startable-fixture contract and avoid making expensive provider context setup implicit in more tests
• Heavy-family visibility / justification: no new heavy-governance family and no new browser family are justified
• Special surface test profile: standard-native-filament, shared-detail-family
• Standard-native relief or required special coverage: the feature lane is primary proof; conditional existing browser smoke is enough when visible provider-scope or report disclosure changes
• Reviewer handoff: reviewers must confirm that Filament remains on Livewire v4, provider registration stays in apps/platform/bootstrap/providers.php, no new global-search surface is introduced, existing destructive actions keep confirmation and server authorization, and the final proving commands stay inside the targeted provider/verification lane unless visible surface changes justify the one named browser smoke
• Budget / baseline / trend impact: contained feature-local upkeep only
• Escalation needed: document-in-feature
• Active feature PR close-out entry: RuntimeSemantics
• Planned validation commands:
  • 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

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, and this slice does not introduce a new globally-searchable resource
• Destructive actions: no new destructive action is introduced; any touched existing mutation must retain ->action(...), ->requiresConfirmation(), and server-side authorization
• Asset strategy: no new assets or filament:assets deployment changes are introduced

Scope Boundaries (required for this slice)

In Scope

• classify the current failing ProviderConnections/Verification groups into one bounded failure vocabulary before any implementation work begins
• align the shared startable verification fixture contract with the current canonical repo truth for queued verification starts
• stabilize StartVerification so canonical startable connections return started, deduped, or a fresh post-completion run while blocked remains reserved for real prerequisite failures
• stabilize ProviderOperationStartGate so identical-operation dedupe and cross-operation scopeBusy behavior remain consistent for provider-backed operations
• stabilize the provider connection neutrality baseline so target-scope disclosure stays neutral and provider-specific identity detail remains nested intentionally
• stabilize verification report summary counts so tests follow the current emitted check inventory instead of stale literal limits
• keep the validation lane bounded to tests/Feature/ProviderConnections and tests/Feature/Verification, with conditional reuse of one existing browser smoke only when visible provider-scope or report disclosure changes

Non-Goals

• reopening any /admin/t/... or workspace-route cutover repair
• full-suite repair outside tests/Feature/ProviderConnections and tests/Feature/Verification
• reopening historical package work from Specs 238, 188, 084, or 074
• introducing a new provider-profile table, provider registry, capability registry, or verification schema version
• broad provider-boundary or multi-provider framework work
• new surfaces, new panels, or new notification families

User Scenarios & Testing (mandatory)

User Story 1 - Start verification on one canonical contract (Priority: P1)

As an operator with provider-run capability, I can start provider verification on a canonical startable connection and get truthful started, deduped, or fresh post-completion behavior instead of an unexpected blocked result caused by stale fixture or runtime drift.

Why this priority: this is the operator-critical entry point, and the current failing lane already proves that the start contract is the most user-visible remaining drift.

Independent Test: Can be fully tested by running VerificationAuthorizationTest, VerificationStartAfterCompletionTest, and VerificationStartDedupeTest against canonical startable fixtures and confirming those tests no longer fall back to blocked semantics.

Acceptance Scenarios:

1. Given a managed environment member with provider-run capability and a canonical startable provider connection, When verification starts, Then the result is started and a provider.connection.check run is created.
2. Given the same canonical connection already has an active verification run, When verification starts again, Then the result is deduped and points to the same active run.
3. Given the previous verification run is terminal, When verification starts again, Then a new run is created instead of returning the prior run or a blocked result.

---

User Story 2 - Keep provider operation concurrency truthful (Priority: P1)

As an operator, I can trust that provider operations for the same connection either dedupe the same operation or return one shared scopeBusy follow-through for a different active operation, without creating contradictory extra runs.

Why this priority: provider verification and provider-backed operation trust share the same gate. If concurrency semantics drift, the provider lane stays red and the operator contract becomes untrustworthy.

Independent Test: Can be fully tested by running ProviderDispatchGateStartSurfaceTest and ProviderOperationConcurrencyTest and confirming no extra operation runs or missing queue pushes occur once the current gate contract is aligned.

Acceptance Scenarios:

1. Given an inventory sync is already active for a connection, When a compliance snapshot starts for that same connection, Then no second run is created and the result surfaces the existing active run as scopeBusy guidance.
2. Given the same provider operation starts twice for the same connection while active, When the second start executes, Then the shared gate dedupes instead of creating a duplicate run.

---

User Story 3 - Surface and report baselines stay on current truth (Priority: P2)

As an operator or reviewer, I can open provider connection detail and verification report surfaces and see the current neutral disclosure and report summary truth instead of stale copy or stale count ceilings.

Why this priority: these are the remaining visible baseline drifts after the deeper route cutover is complete.

Independent Test: Can be fully tested by running ProviderConnectionNeutralitySpec238Test and ProviderConnectionHealthCheckWritesReportTest. If provider-connection disclosure changes visibly, conditionally reuse the existing provider-connection scope browser smoke. Verification-report disclosure remains proven by the feature lane in 294.

Acceptance Scenarios:

1. Given a provider connection detail surface shows target scope and nested provider identity detail, When the operator opens the page, Then the page shows the neutral target-scope baseline and the intended provider-specific nested detail without reverting to stale copy expectations.
2. Given a verification run writes the current report shape, When the report summary renders, Then summary.counts.total matches the emitted check inventory and tests do not assert an outdated hard-coded ceiling.

Edge Cases

• A hand-built provider connection that looks valid in a test but does not meet the repo's canonical startable fixture contract must fail as blocked only when the canonical prerequisites are actually absent.
• An active queued run that has become stale must not make later verification or provider-operation starts look like a dedupe success when the canonical gate should clear it first.
• A provider connection surface may still show nested Microsoft tenant detail, but that detail must remain provider-owned context rather than replace the neutral target-scope summary.
• A new verification check may widen the report inventory; summary-count assertions must follow the canonical emitted inventory rather than a stale maximum.
• Readonly or non-member access semantics must remain unchanged while the start contract is stabilized: non-members stay 404, in-scope actors missing capability stay 403, and readonly users can view stored reports without starting verification.

Non-Functional Requirements

• NFR-001 (bounded proof lane): the primary proof command remains cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification; no new broad lane becomes mandatory for this slice
• NFR-002 (no new runtime truth): the slice must not introduce new tables, new persisted provider profiles, new run status values, or a new verification schema version
• NFR-003 (shared-owner discipline): implementation must reuse existing runtime owners (StartVerification, ProviderOperationStartGate, OperationRunService, ProviderConnectionSurfaceSummary, VerificationReportSchema) instead of adding a second semantics layer
• NFR-004 (conditional browser proof only): browser validation is conditional and reuses one existing provider-connection scope smoke only when visible provider-connection disclosure changes

Requirements (mandatory)

Constitution alignment (required): This package introduces no new Graph integration surface, no new provider implementation, no new asset family, and no new long-running workflow beyond the current provider-operation and verification start paths. It stabilizes existing start/report semantics only.

Constitution alignment (RBAC-UX): This package preserves existing verification and provider-operation authorization semantics:

• non-member or wrong-scope access remains 404
• in-scope actor missing capability remains 403
• provider and verification starts continue to enforce capability server-side
• no raw capability string or role-string shortcut is introduced

Constitution alignment (PROV-001): Shared target-scope and verification summary semantics stay provider-neutral by default, while Microsoft-specific identity detail remains nested provider-owned context.

Constitution alignment (TEST-GOV-001): The package keeps proof in the narrowest honest feature lane and documents one optional existing browser smoke instead of adding a new heavy-governance or browser family.

For this package, a failing group means one failing test file or one failing scenario cluster that shares one seam and one category and is tracked as one row in failure-classification.md.

Functional Requirements

• FR-294-001 (failure classification first): Before implementation begins, every currently failing group in the targeted ProviderConnections/Verification lane must be recorded in failure-classification.md with exactly one pinned seam and one pinned failure category.
• FR-294-002 (canonical startable fixture contract): Verification tests or start surfaces that expect a queued provider.connection.check run must use the repo's canonical startable fixture contract rather than ad hoc provider connection construction that no longer satisfies the current gate.
• FR-294-003 (verification start semantics): StartVerification must return started for canonical startable connections, deduped for the same active verification identity, and a new run after a prior terminal run. blocked remains reserved for real prerequisite failures.
• FR-294-004 (provider operation concurrency semantics): ProviderOperationStartGate must dedupe identical active operations for the same provider connection and return shared scopeBusy behavior for a different active provider operation on that same connection, without creating contradictory extra runs.
• FR-294-005 (neutrality surface baseline): Provider connection edit, list, and detail expectations touched by this slice must keep neutral target-scope disclosure as the default visible truth and keep provider-specific identity details nested intentionally rather than as the top-level label set.
• FR-294-006 (verification report summary baseline): Verification report summary counts must remain schema-valid, must match the emitted check inventory, and must not depend on stale hard-coded ceilings that no longer reflect the current check set.
• FR-294-007 (bounded validation): The final implementation proof must stay bounded to the targeted ProviderConnections/Verification lane, plus conditional reuse of one existing provider-connection scope browser smoke only when visible provider-connection disclosure changes.
• FR-294-008 (no spillover): The implementation must not absorb route-cutover fixes, full-suite cleanup, new provider-boundary groundwork, or historical-spec rewrites under the label of provider/verification stabilization.

Success Criteria

• The targeted command cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/Verification passes with no remaining failures in the in-scope lane.
• failure-classification.md, spec.md, plan.md, research.md, data-model.md, quickstart.md, tasks.md, and checklists/requirements.md all use the same pinned failure categories and seam names.
• No implementation change under 294 reopens /admin/t/... cutover work, adds a new provider abstraction, or widens into a broader full-suite repair.
• If visible provider-connection disclosure changes, the reused existing provider-connection scope browser smoke remains green.

Assumptions

• Spec 293 already stabilized the route, panel, and workspace-aware baseline and remains context only.
• The repo's current canonical startable verification fixture is createUserWithTenant(..., fixtureProfile: 'credential-enabled') or an equivalent helper path that seeds a startable Microsoft provider connection truthfully.
• ProviderConnectionSurfaceSummary and the current target-scope normalizer remain the right owner seams for neutral provider-connection disclosure.
• VerificationReportSchema stays at the current major version, and this slice only stabilizes how current report inventory is asserted and surfaced.
• The active automatic candidate queue in docs/product/spec-candidates.md remains intentionally empty; 294 is a deliberate manual follow-up.

Risks

• Misclassifying a fixture-contract drift as a runtime regression could cause unnecessary app changes in the provider or verification owners.
• Dedupe semantics may ultimately be owned one layer deeper than ProviderOperationStartGate; tasks must let implementation step one owner-hop lower only if targeted reruns prove that is necessary.
• Provider-connection view copy and shared summary output could drift again if tests are updated without aligning the shared summary owner.
• Verification report totals may widen again when future checks are added; tasks must tie test expectations to the canonical emitted inventory rather than another literal cap.

Open Questions

• None at prep time. The confirmed target lane, current failing output, and directly read owner seams are sufficient to proceed to implementation.