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

Research: Provider Capability Registry

Decision 1: Provider capability state stays derived, not persisted

• Decision: keep provider capability truth derived from existing provider connection state, required-permissions evidence, consent posture, verification posture, and provider-binding metadata.
• Why: the repo already stores the underlying truth in ProviderConnection, required-permissions evidence, and blocked-operation context. A provider-capability table would duplicate that truth without a current-release lifecycle need.
• Alternatives considered:
  • provider-capability snapshot table: rejected because it introduces new persistence, drift risk, and lifecycle questions with no current-release benefit
  • page-local capability arrays: rejected because they preserve current explanation drift across provider-connections, onboarding, required-permissions diagnostics, and blocked-operation messaging

Decision 2: Use one small code-first registry plus evaluator

• Decision: prefer one small support namespace for capability definitions, status enum, and evaluation over a new config-first framework or broad provider abstraction.
• Why: the slice needs one shared capability concept across multiple existing consumers. A small code-first registry is easier to bound and test than another config namespace plus generic loader machinery.
• Alternatives considered:
  • expand config/intune_permissions.php into the sole capability source: rejected because the file already models provider-owned raw permission detail, not shared workflow capability truth
  • use only ProviderOperationRegistry: rejected because required-permissions diagnostics and onboarding also need capability truth outside operation-start paths

Decision 3: Capability keys stay limited to current repo workflows

• Decision: limit the initial provider capability inventory to current workflows already present in repo truth: provider connection checks, inventory sync, compliance snapshot, restore execution, directory groups sync, and directory role-definition sync.
• Canonical initial key set:
  • provider_connection_check -> provider.connection.check
  • inventory_read -> inventory.sync
  • configuration_read -> compliance.snapshot
  • restore_execute -> restore.execute
  • directory_groups_read -> directory.groups.sync
  • directory_role_definitions_read -> directory.role_definitions.sync
• Why: the candidate backlog listed broader future-facing examples, but current-release truth only justifies keys for existing workflows and diagnostics.
• Alternatives considered:
  • future-facing keys such as review_publish or evidence_snapshot_write: rejected because they describe adjacent or not-yet-real provider workflows
  • capability keys copied directly from raw Graph permission names: rejected because that would keep provider-owned requirement detail as platform-core vocabulary

Decision 4: Existing provider reason codes remain blocking reason truth

• Decision: keep current provider reason codes as the blocking or degraded reason truth and add capability keys or capability status as the workflow-level explanation layer.
• Why: the repo already routes blocked outcomes, contextual help, and support diagnostics through provider reason codes. Replacing that system entirely would widen scope and duplicate responsibility.
• Alternatives considered:
  • a second capability-specific reason-code family: rejected because it adds another semantic layer without replacing the existing one
  • no reason-code reference on capability results: rejected because blocked and unknown states still need stable downstream machine-readable reasons

Decision 5: Required Permissions stays the canonical diagnostic deep dive

• Decision: keep TenantRequiredPermissions as the canonical diagnostic page and make it capability-aware by grouping or summarizing raw provider requirements under capability headings.
• Why: the page already exists, already supports filtering and deep inspection, and already has safe links from onboarding and product knowledge.
• Alternatives considered:
  • a new provider-capability diagnostic page: rejected because it duplicates an existing deep-dive surface
  • inline raw permission evidence on provider-connections or onboarding only: rejected because it would spread the diagnostic matrix across summary-first surfaces

Decision 6: Support and contextual-help consumers must adopt the same vocabulary

• Decision: shared help and support-diagnostic consumers should adopt the capability-first explanation if they already consume the same provider blocker.
• Why: otherwise the same provider blocker would still read differently on the main surfaces versus diagnostic surfaces.
• Alternatives considered:
  • leave help and support surfaces untouched: rejected because it preserves one of the biggest remaining explanation drifts in the repo

Implementation prerequisite

• Spec 281 must already be present on the implementation branch because 283 assumes the provider-neutral target-scope and provider-identity baseline prepared there.

Explicit non-goals carried into design

• No provider-capability table or ledger
• No broader provider-neutral artifact taxonomy
• No user RBAC changes
• No provider-profile table
• No routing cutover
• No copy-neutralization or no-legacy enforcement pack work