TenantAtlas/specs/283-provider-capability-registry/plan.md

Implementation Plan: Provider Capability Registry

Branch: 283-provider-capability-registry | Date: 2026-05-08 | Spec: spec.md Input: Feature specification from specs/283-provider-capability-registry/spec.md

Summary

Prepare the next reserved provider-boundary slice by introducing one provider capability registry and derived capability-evaluation path over the repo's existing provider connection, required-permissions, onboarding, blocked-operation, and support-diagnostic seams. The narrow implementation path reuses the current provider operation registry, provider operation start gate, required-permissions matrix, provider reason translation, provider-connections resource, onboarding wizard, and support links while explicitly rejecting a provider-capability table, a provider framework, a user RBAC rewrite, a broader taxonomy, and adjacent cutover work from Specs 284 through 287.

This plan is intentionally bounded. Filament remains v5 on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, ProviderConnectionResource remains non-globally-searchable, existing destructive provider-connection actions stay confirmation-protected and server-authorized, and raw Graph permission names remain provider-owned evidence rather than the new primary operator vocabulary.

Inherited Baseline / Explicit Delta

Inherited baseline

• Spec 279 already completed the managed-environment core cutover and is historical prerequisite context only.
• Spec 280 already prepared the workspace-first shell and remains separate adjacent context only.
• Spec 281 already prepared the provider-neutral target-scope and provider-identity baseline and is an implementation prerequisite for 283.
• apps/platform/app/Filament/Resources/ProviderConnectionResource.php already exists with List, Create, View, and Edit pages, remains protected static bool $isGloballySearchable = false;, and already groups mutating actions behind confirmation-protected Filament actions.
• apps/platform/app/Filament/Pages/TenantRequiredPermissions.php already lives under the workspace-first managed-environment route shell and already keeps its actions inside the page body rather than the page header.
• apps/platform/app/Support/Verification/TenantPermissionCheckClusters.php already groups raw permission rows into diagnostic clusters such as admin consent, directory/groups, Intune configuration, apps, RBAC, and scripts, but it does not yet publish workflow capability truth.
• apps/platform/app/Services/Providers/ProviderOperationRegistry.php already maps operation types to user RBAC capability requirements and provider bindings, but it does not yet map those operations to provider application capabilities.
• apps/platform/app/Services/Providers/ProviderOperationStartGate.php already blocks or starts provider-backed work through one shared path, but it still explains missing prerequisites through reason codes and raw requirement detail rather than a stable capability contract.
• apps/platform/app/Support/Providers/ProviderReasonTranslator.php, contextual-help catalog or resolver seams, and support-diagnostic consumers already translate provider blockers and route operators to RequiredPermissionsLinks, but they still lead with provider-specific requirement language in several cases.
• apps/platform/app/Models/ProviderConnection.php already persists consent state, verification state, scopes_granted, and metadata, so 283 must treat provider capability state as derived truth rather than add another table.

Explicit delta in this plan

• Introduce one bounded provider capability definition and evaluation layer over the existing provider connection, required-permissions, and blocked-operation seams.
• Keep provider capability state derived and request-time or snapshot-derived; do not add a provider-capability table or ledger.
• Map the current provider-backed operation types to explicit provider capability keys.
• Reuse the required-permissions page as the canonical diagnostic deep dive, but group or summarize raw requirement rows under shared capability headings and statuses.
• Reuse ProviderConnectionResource and ManagedTenantOnboardingWizard as the operator-facing summary consumers for the new capability contract.
• Reuse ProviderReasonTranslator, ProviderNextStepsRegistry, and existing support or product-knowledge links so blocked-operation and diagnostic guidance adopts the same capability vocabulary.
• Keep raw Graph permission names, Intune RBAC prerequisite detail, consent links, and provider portal metadata nested inside provider-owned remediation or evidence blocks.
• Keep Specs 284 through 287 explicitly deferred.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52
Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, existing provider operation, provider reason, onboarding, and required-permissions seams
Storage: PostgreSQL, no new persistence or schema change in this slice
Testing: Pest unit tests, Pest feature tests, and one Pest browser smoke
Validation Lanes: fast-feedback, confidence, browser
Target Platform: Laravel monolith in apps/platform
Project Type: web application
Performance Goals: preserve current provider-connection, onboarding, and required-permissions responsiveness while changing only derived capability evaluation and summary presentation; no new remote inline work or asset path is introduced
Constraints: no provider-capability table, no provider framework, no user RBAC changes, no route-cutover work from Spec 280, no provider-identity extraction work from Spec 281, provider registration stays in apps/platform/bootstrap/providers.php, and ProviderConnectionResource stays non-globally-searchable
Scale/Scope: one shared capability contract over the existing Microsoft provider implementation and current provider-backed workflows only

Likely Affected Repo Surfaces

• apps/platform/app/Services/Providers/ProviderOperationRegistry.php
• apps/platform/app/Services/Providers/ProviderOperationStartGate.php
• apps/platform/app/Support/Providers/ProviderReasonCodes.php
• apps/platform/app/Support/Providers/ProviderReasonTranslator.php
• apps/platform/app/Support/Providers/ProviderNextStepsRegistry.php
• apps/platform/app/Support/Verification/TenantPermissionCheckClusters.php
• apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php
• apps/platform/app/Filament/Pages/TenantRequiredPermissions.php
• apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
• apps/platform/app/Filament/Resources/ProviderConnectionResource.php
• apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php
• apps/platform/app/Support/Links/RequiredPermissionsLinks.php
• apps/platform/app/Support/ProductKnowledge/ContextualHelpCatalog.php
• apps/platform/app/Support/ProductKnowledge/ContextualHelpResolver.php
• apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php if that surface already consumes the shared provider prerequisite explanation and must stay aligned without becoming a separate dashboard initiative
• apps/platform/config/provider_boundaries.php
• apps/platform/config/intune_permissions.php only if the implementation needs to read existing provider-owned requirement identifiers from the current config rather than re-declare them locally
• new bounded support files under apps/platform/app/Support/Providers/Capabilities/ only if implementation needs a small dedicated namespace for the registry, status enum, and evaluator
• representative proof files under apps/platform/tests/Unit/Providers/, apps/platform/tests/Unit/Verification/, apps/platform/tests/Feature/Providers/, apps/platform/tests/Feature/Filament/, apps/platform/tests/Feature/Onboarding/, apps/platform/tests/Feature/RequiredPermissions/, apps/platform/tests/Feature/SupportDiagnostics/, and apps/platform/tests/Browser/

Filament v5 / Capability Surface Notes

• Livewire v4.0+ compliance: all touched Filament work remains on Filament v5 with Livewire v4.
• Provider registration location: provider registration stays in apps/platform/bootstrap/providers.php; nothing moves to bootstrap/app.php.
• Global search rule: ProviderConnectionResource remains non-globally-searchable and keeps its View and Edit pages. No new searchable resource is introduced by this slice.
• Destructive actions: touched provider-connection mutations keep the existing ->action(...), ->requiresConfirmation(), and server-authorization contracts. Grant admin consent remains navigation-only.
• Asset strategy: no new asset registration or deploy-step change is planned.

Provider Capability Contract Fit

• Introduce one bounded capability definition source for current-release provider-backed workflows only.
• Keep the shared capability-key inventory limited to the workflows already present in repo truth:
  • provider_connection_check
  • inventory_read
  • configuration_read
  • restore_execute
  • directory_groups_read
  • directory_role_definitions_read
• Keep capability status values limited to the derived family from the spec: supported, missing, blocked, unknown, and not_applicable.
• Keep capability definitions platform-core, but keep provider requirement mappings provider-owned. That means capability definitions can point to provider-owned requirement keys such as cluster identifiers or Graph permission names without promoting those raw identifiers into the top-level operator vocabulary.
• Prefer one small code-first registry plus evaluator namespace over a new config-first framework or a new table. If implementation discovers that one small code-first registry cannot stay reviewable, that change must be re-justified rather than added silently.
• Reuse existing permission-cluster evidence and provider-connection state as inputs. The capability layer should not replace those inputs; it should standardize how they are interpreted by workflow consumers.

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: mixed native Filament resource plus existing custom onboarding wizard
• Shared-family relevance: provider summary, blocked guidance, onboarding readiness, required-permissions diagnostics, support translation
• State layers in scope: page, detail, modal, Livewire state, URL-query
• Audience modes in scope: operator-MSP, support-platform
• Decision/diagnostic/raw hierarchy plan: capability-first summary, diagnostics-second evidence, provider-raw-third remediation detail
• Raw/support gating plan: provider-specific requirement detail stays nested or lower-priority; raw permission rows stay on the diagnostic page rather than the top-level summary
• One-primary-action / duplicate-truth control: provider-connections and onboarding surface one dominant next step from the capability result and delegate the full proof to the required-permissions page
• Handling modes by drift class or surface: review-mandatory
• Repository-signal treatment: review-mandatory until provider-connections, onboarding, required-permissions, and blocked-operation messaging all use the same capability labels
• Special surface test profiles: standard-native-filament, workflow-hub, shared-detail-family
• Required tests or browser smoke: functional-core, state-contract, browser-smoke
• Exception path and spread control: none; the slice removes explanation drift rather than adding a new exception
• Active feature PR close-out entry: Guardrail

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: provider operation registry, provider operation start gate, required-permissions diagnostics, onboarding readiness, provider connection summaries, provider reason translation, contextual help, and support-diagnostic guidance
• Shared abstractions reused: ProviderOperationRegistry, ProviderOperationStartGate, ProviderReasonTranslator, ProviderNextStepsRegistry, TenantPermissionCheckClusters, TenantRequiredPermissionsViewModelBuilder, ProviderConnectionSurfaceSummary, and RequiredPermissionsLinks
• New abstraction introduced? why?: one small registry plus evaluator namespace is expected because multiple existing shared consumers need one stable capability contract and no current shared abstraction owns that concept yet
• Why the existing abstraction was sufficient or insufficient: existing abstractions already own provider connection state, permission evidence, or blocked-operation explanation, but none of them own the workflow-capability concept across all current consumers
• Bounded deviation / spread control: provider-owned Graph permission names, Intune RBAC detail, consent links, and portal metadata remain nested evidence only and must not define the shared capability contract

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes
• Central contract reused: ProviderOperationStartGate, ProviderOperationStartResultPresenter, OperationUxPresenter, and the current OperationRunService lifecycle path
• Delegated UX behaviors: blocked-versus-started behavior, queued intent messaging, run links, capability-driven remediation hints, and provider-safe follow-up routing stay delegated to the existing shared provider-operation path
• Surface-owned behavior kept local: ProviderConnectionResource and ManagedTenantOnboardingWizard keep only initiation affordances, summary placement, and assist entry points
• Queued DB-notification policy: N/A
• Terminal notification path: existing central lifecycle mechanism
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes
• Provider-owned seams: raw Graph permission names, Intune RBAC remediation detail, admin-consent links, required-permissions URLs, portal links, and any provider-specific troubleshooting metadata
• Platform-core seams: capability definitions, capability status evaluation, operation-to-capability mapping, blocked-operation capability summary, shared capability labels, and shared diagnostic grouping
• Neutral platform terms / contracts preserved: provider capability, capability key, capability status, provider connection, managed environment, target workflow, and provider requirement
• Retained provider-specific semantics and why: the current Microsoft provider still needs its own raw permission names, consent guidance, and Intune RBAC detail for operators to fix blockers. Those details remain explicit provider-owned evidence.
• Bounded extraction or follow-up path: no broader taxonomy or multi-provider framework work in this slice; that remains with Specs 284 through 287

Constitution Check

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

• Inventory-first / snapshot truth: PASS. The slice derives capability truth from existing provider and permission evidence.
• Read/write separation: PASS. No new remote-write workflow is introduced.
• Graph contract path: PASS. No new Graph endpoint or contract-registry work is added.
• Deterministic capabilities: PASS with implementation condition. Capability evaluation must be testable and deterministic from the existing provider and permission inputs.
• RBAC-UX plane separation: PASS. /admin versus /system remains unchanged.
• Workspace isolation: PASS. Workspace membership remains the first boundary.
• Managed-environment isolation: PASS. Managed-environment entitlement remains the second boundary.
• Destructive action discipline: PASS by preservation. Existing confirmation-protected provider-connection mutations remain unchanged.
• Global search safety: PASS. ProviderConnectionResource stays non-globally-searchable.
• OperationRun / Ops-UX: PASS. The slice reuses the shared provider-operation start path and changes only its prerequisite contract.
• Data minimization: PASS. No new persistence or provider-capability ledger is introduced.
• Test governance: PASS. Proof stays bounded to unit, feature, and one browser smoke.
• Proportionality / no premature abstraction: PASS with implementation condition. Any new support namespace must stay narrow and current-release only.
• Persisted truth / behavioral state: PASS. One new derived state family is introduced; no new persistence is introduced.
• UI semantics / shared pattern first / Filament-native UI: PASS. Existing resource, page, and wizard surfaces remain the primary operator paths.
• Provider boundary: PASS with implementation condition. Raw provider requirement detail must remain secondary evidence rather than reappearing as the primary shared label set.

Gate evaluation: PASS.

Post-design re-check: PASS while research.md, data-model.md, quickstart.md, contracts/provider-capability-registry.logical.openapi.yaml, and checklists/requirements.md stay aligned on the same capability keys, status family, derived-truth posture, and proof commands.

Test Governance Check

• Test purpose / classification by changed surface: Unit, Feature, Browser
• Affected validation lanes: fast-feedback, confidence, browser
• Why this lane mix is the narrowest sufficient proof: the registry and evaluator logic are pure derivation and deserve unit proof; the shared start gate, provider-connections, onboarding, required-permissions page, and support translation need feature proof; one browser smoke is enough to prove the real operator path from provider connection or onboarding into the diagnostic page
• Narrowest proving command(s):
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderCapabilityRegistryTest.php tests/Unit/Verification/TenantPermissionCapabilityMappingTest.php)
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/Providers/ProviderCapabilityEvaluationTest.php tests/Feature/Providers/ProviderOperationCapabilityGateTest.php tests/Feature/Filament/ProviderConnectionCapabilitySummaryTest.php tests/Feature/Onboarding/ManagedTenantOnboardingCapabilityAssistTest.php tests/Feature/RequiredPermissions/RequiredPermissionsCapabilityGroupingTest.php tests/Feature/SupportDiagnostics/ProviderCapabilityReasonTranslationTest.php)
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec283ProviderCapabilityRegistrySmokeTest.php)
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)
• Fixture / helper / factory / seed / context cost risks: moderate because proof needs workspace, managed environment, provider connection, permission evidence, and blocked-operation context without widening shared fixture defaults
• Expensive defaults or shared helper growth introduced?: no; any new capability test helper should stay feature-local and opt-in
• Heavy-family additions, promotions, or visibility changes: none beyond one bounded browser smoke
• Surface-class relief / special coverage rule: standard-native-filament relief for provider-connections and required-permissions; one workflow-hub smoke for onboarding continuity
• Closing validation and reviewer handoff: rerun the commands above, verify that no provider-capability table appears, verify that the registry stays current-release-only, verify that provider-connections and onboarding use the same capability labels, verify that the required-permissions page groups evidence under those same labels, verify that blocked-operation context carries capability information, and verify that raw Graph permission names remain secondary evidence
• Budget / baseline / trend follow-up: contained feature-local increase only
• Review-stop questions: did the implementation add persistence, did it invent future-facing capability keys, did it widen into RBAC or taxonomy work, did any touched surface keep a page-local permission vocabulary, did blocked-operation context stay on reason-only or raw permission language
• Escalation path: reject-or-split if implementation introduces persistence, a provider framework, a user RBAC rewrite, or broader cutover work from adjacent specs
• Active feature PR close-out entry: Guardrail
• Why no dedicated follow-up spec is needed: adjacent follow-up work already exists as Specs 284 through 287; 283 only needs the bounded capability slice itself

Review Checklist Status

• Review checklist artifact: checklists/requirements.md
• Review outcome class: implementation-ready
• Workflow outcome: keep
• Test-governance outcome: keep
• Escalation rule: if implementation adds persistence, broad future-facing keys, or adjacent-spec scope, flip the workflow outcome to split or reject-or-split

Rollout Considerations

• Land the registry definitions, evaluator, and shared consumer updates as one bounded slice so provider-connections, onboarding, required-permissions diagnostics, and provider-operation blocking all converge atomically.
• Update the shared evaluation and translation seams before polishing page copy so the touched surfaces inherit the same contract rather than reformatting raw evidence separately.
• Keep provider-owned evidence and remediation nested from the start; otherwise the later UI pass will still have to untangle raw Microsoft-first summaries.
• Keep dashboard or support surfaces limited to consumers of the shared capability contract and do not let them grow into a separate productization initiative in this slice.

Risk Controls

• Reject any implementation that introduces a provider-capability table, ledger, or snapshot model.
• Reject any implementation that creates a future-facing provider framework or tries to solve multi-provider routing, taxonomy, or UI copy in the same slice.
• Reject any implementation that leaves provider-connections, onboarding, and required-permissions diagnostics on different capability or requirement vocabularies.
• Reject any implementation that collapses user RBAC capability failures into provider application capability failures.
• Reject any implementation that promotes raw Graph permission names back into the primary operator summary on touched surfaces.

Research & Design Outputs

• research.md records the bounded derivation decisions, the capability-key inventory, the provider-owned evidence rules, and the rejected alternatives.
• data-model.md captures the derived capability definition, result, evidence, grouped diagnostic view, and operation-gate contracts.
• quickstart.md gives reviewers the bounded proof flow and exact commands.
• contracts/provider-capability-registry.logical.openapi.yaml models the logical capability summary, diagnostic grouping, onboarding assist, support explanation, and operation-start contract.
• checklists/requirements.md records package readiness, boundedness, and outcome state.

Project Structure

Documentation (this feature)

specs/283-provider-capability-registry/
├── checklists/
│   └── requirements.md
├── contracts/
│   └── provider-capability-registry.logical.openapi.yaml
├── data-model.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md

Source Code (expected implementation surfaces)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── TenantRequiredPermissions.php
│   │   │   └── Workspaces/
│   │   │       └── ManagedTenantOnboardingWizard.php
│   │   └── Resources/
│   │       └── ProviderConnectionResource.php
│   ├── Models/
│   │   └── ProviderConnection.php
│   ├── Services/
│   │   ├── Intune/
│   │   │   └── TenantRequiredPermissionsViewModelBuilder.php
│   │   └── Providers/
│   │       ├── ProviderOperationRegistry.php
│   │       └── ProviderOperationStartGate.php
│   └── Support/
│       ├── Links/
│       │   └── RequiredPermissionsLinks.php
│       ├── ProductKnowledge/
│       │   ├── ContextualHelpCatalog.php
│       │   └── ContextualHelpResolver.php
│       ├── Providers/
│       │   ├── ProviderNextStepsRegistry.php
│       │   ├── ProviderReasonCodes.php
│       │   ├── ProviderReasonTranslator.php
│       │   ├── TargetScope/
│       │   │   └── ProviderConnectionSurfaceSummary.php
│       │   └── Capabilities/
│       │       ├── ProviderCapabilityRegistry.php
│       │       ├── ProviderCapabilityResult.php
│       │       ├── ProviderCapabilityStatus.php
│       │       └── ProviderCapabilityEvaluator.php
│       ├── TenantDashboard/
│       │   └── TenantDashboardSummaryBuilder.php
│       └── Verification/
│           └── TenantPermissionCheckClusters.php
├── config/
│   ├── intune_permissions.php
│   └── provider_boundaries.php
└── tests/
    ├── Browser/
    │   └── Spec283ProviderCapabilityRegistrySmokeTest.php
    ├── Feature/
    │   ├── Filament/
    │   │   └── ProviderConnectionCapabilitySummaryTest.php
    │   ├── Onboarding/
    │   │   └── ManagedTenantOnboardingCapabilityAssistTest.php
    │   ├── Providers/
    │   │   ├── ProviderCapabilityEvaluationTest.php
    │   │   └── ProviderOperationCapabilityGateTest.php
    │   ├── RequiredPermissions/
    │   │   └── RequiredPermissionsCapabilityGroupingTest.php
    │   └── SupportDiagnostics/
    │       └── ProviderCapabilityReasonTranslationTest.php
    └── Unit/
        ├── Providers/
        │   └── ProviderCapabilityRegistryTest.php
        └── Verification/
            └── TenantPermissionCapabilityMappingTest.php

Structure Decision: keep the implementation inside apps/platform and add only one small support namespace for provider capability definitions and derived evaluation. Reuse existing Filament, provider-operation, required-permissions, and support-diagnostic seams instead of creating a new module or package.