TenantAtlas/specs/281-provider-connection-scope/research.md

# Research: Provider Connection Scope & Microsoft Profile Extraction

**Date**: 2026-05-07  
**Branch**: `281-provider-connection-scope`

## Decision 1: Keep `281` as a contract-extraction slice, not a new provider framework

- **Decision**: limit the slice to provider-neutral target-scope and identity contract extraction across the existing `ProviderConnection`, resolver, summary, onboarding, and start-gate seams.
- **Rationale**: current repo truth already contains the right seam inventory: `ProviderConnectionTargetScopeDescriptor`, `ProviderConnectionTargetScopeNormalizer`, `ProviderConnectionSurfaceSummary`, `ProviderIdentityResolution`, and `ProviderOperationStartGate`. The problem is the Microsoft-shaped payload still flowing through them, not the absence of a framework.
- **Alternatives considered**:
  - Introduce a provider registry or capability framework: rejected because the feature has only one current provider and the constitution explicitly prefers bounded extraction over speculative multi-provider machinery.
  - Add a generic provider profile subsystem first: rejected because the current release does not need new persistence to describe provider profile detail.

## Decision 2: Treat `ProviderConnection` as the unchanged persisted source of truth

- **Decision**: `ProviderConnection` stays the only persisted binding record for this slice, anchored by `workspace_id` plus `managed_environment_id`. No `tenant_id` migration work and no provider-profile table are added.
- **Rationale**: `ProviderConnection` already belongs to `ManagedEnvironment` via `managed_environment_id`, and the raw candidate wording about replacing `tenant_id` is stale. The remaining defect is contract shaping, not relationship ownership.
- **Alternatives considered**:
  - Re-open the old `tenant_id` to `managed_environment_id` candidate: rejected because repo truth already completed that move.
  - Add a separate provider-profile entity: rejected because provider profile detail is still derived from the current connection and identity-resolution path.

- **Documented candidate deviation**: the raw candidate also proposed a new shared field family around `provider_key`, `external_account_id`, `provider_metadata`, and explicit run-context workspace/environment keys. In current repo truth, `provider`, `workspace_id`, and `managed_environment_id` already exist, so this package narrows the shared contract to `target_scope`, `effective_client_identity`, nested `provider_context`, and existing provider-owned metadata instead of inventing new top-level persisted fields.

## Decision 3: Make `ProviderConnectionTargetScopeDescriptor` the canonical shared `target_scope` contract

- **Decision**: standardize every shared target-scope output on `provider`, `scope_kind`, `scope_identifier`, `scope_display_name`, `shared_label`, and `shared_help_text` instead of any Microsoft-named top-level keys.
- **Rationale**: the descriptor already exists and already exposes the right field names. What is missing is consistent reuse across resolver, audit, UI summary, onboarding, and run-context seams.
- **Alternatives considered**:
  - Keep `target_scope.entra_tenant_id` alongside the neutral fields: rejected because pre-production lean doctrine favors canonical replacement over shared compatibility aliases.
  - Add a second DTO or presenter for neutral naming: rejected because the existing descriptor already covers the need.

## Decision 4: Reshape the shared identity result around effective client identity and nested provider context

- **Decision**: keep `ProviderIdentityResolution` as the single shared identity-result object, but move its planned contract center of gravity to `target_scope`, `effective_client_identity`, `blocked_reason`, and nested `provider_context` rather than shared `tenantContext` naming.
- **Rationale**: the current implementation already carries these concepts as `targetScope`, `effectiveClientId`, `credentialSource`, and contextual detail arrays. The shared leak is the `tenantContext` field name and its downstream use as the primary field in platform-core seams, so the package standardizes the planned artifact language on `target_scope`, `effective_client_identity`, and `provider_context`.
- **Alternatives considered**:
  - Leave `tenantContext` as the canonical shared field and just add neutral labels in UI: rejected because the identity contract would remain Microsoft-shaped below the UI.
  - Split dedicated and platform identities into new separate result types: rejected because one existing result object already supports both paths.

## Decision 5: Keep Microsoft-specific detail inside provider-owned profile or context metadata

- **Decision**: preserve Microsoft tenant ID, authority tenant, redirect URI, consent URL shaping, and Graph runtime options only inside provider-owned nested metadata or provider-owned consumer seams such as `ProviderIdentityContextMetadata`, `AdminConsentUrlFactory`, and `ProviderGateway`.
- **Rationale**: the boundary catalog already marks identity resolution and operation start as platform-core while runtime transport and consent URL shaping remain provider-owned. The narrowest fix is to push Microsoft semantics outward, not to pretend they disappear.
- **Alternatives considered**:
  - Strip Microsoft detail from all outputs entirely: rejected because support, consent, and troubleshooting still need those fields.
  - Keep Microsoft detail as top-level fields in shared summaries: rejected because that keeps the platform-core contract Microsoft-shaped.

## Decision 6: Reuse `ProviderConnectionSurfaceSummary` as the only summary adapter

- **Decision**: keep `ProviderConnectionSurfaceSummary` as the one summary contract reused by `ProviderConnectionResource`, `ManagedTenantOnboardingWizard`, and managed-environment related-context summaries.
- **Rationale**: the wizard already calls `ProviderConnectionSurfaceSummary::forConnection($connection)->targetScopeSummary()`, and the resource already delegates summary rendering there. Reusing the same adapter is the narrowest way to remove duplicate truth.
- **Alternatives considered**:
  - Let onboarding and provider-connections each compute their own neutral labels: rejected because it would create the second identity story this feature is meant to remove.
  - Put raw `entra_tenant_id` back into onboarding for clarity: rejected because it would reintroduce a Microsoft-only summary path.

## Decision 7: Rewrite provider-operation start context to use neutral shared scope fields

- **Decision**: `ProviderOperationStartGate` should emit the neutral `target_scope` descriptor in started and blocked run context, with any Microsoft-specific detail nested under provider-owned provider-context metadata.
- **Rationale**: the start gate is one of the explicit boundary hotspots in `config/provider_boundaries.php`, and it still writes `target_scope.entra_tenant_id` directly today. Later artifact and taxonomy work would inherit that leak if it stays.
- **Alternatives considered**:
  - Leave the start-gate context alone and only update UI summaries: rejected because `OperationRun` context is shared operational truth.
  - Add neutral fields beside `entra_tenant_id`: rejected because the feature is pre-production and should replace the shared shape rather than dual-write it.

## Decision 8: Keep credential validation neutral at the platform-core seam

- **Decision**: `CredentialManager` stays the existing credential access seam, but its scope-validation rule and error wording should align to the normalized target-scope identifier rather than a Microsoft-shaped mismatch message.
- **Rationale**: `CredentialManager` is already inside the shared provider identity path and currently compares a payload scope assertion against `connection->entra_tenant_id`. That is acceptable as an implementation detail, but not as the platform-core contract wording.
- **Alternatives considered**:
  - Ignore the message mismatch and leave it Microsoft-shaped: rejected because it leaks provider semantics back into the shared identity failure path.
  - Change provider-credential persistence shape now: rejected because no new persistence is justified for this slice.

## Decision 9: Keep Filament surface behavior and deployment strategy unchanged

- **Decision**: `ProviderConnectionResource` remains non-globally-searchable, keeps `View` and `Edit` pages, preserves the current confirmation-protected mutations, and adds no new asset registration.
- **Rationale**: the feature changes summary and contract shaping only. The current resource already satisfies the required Filament action and search guardrails.
- **Alternatives considered**:
  - Enable global search for provider connections while touching the resource: rejected because the feature does not need it and the spec explicitly keeps it out of scope.
  - Add new UI chrome or asset bundles for provider profile detail: rejected because the existing resource and wizard can carry the nested disclosure.

## Decision 10: Prove the slice with focused feature coverage and one browser smoke

- **Decision**: use focused provider feature tests, one Filament/browser smoke covering provider-connections plus onboarding, and keep proof commands identical across spec, plan, and quickstart.
- **Rationale**: this slice changes shared contract truth across several PHP seams and two operator-facing consumers, but it does not justify a new heavy-governance family or broad browser matrix.
- **Alternatives considered**:
  - Feature tests only: rejected because the live resource plus onboarding continuity is part of the user-visible contract.
  - Broad browser or smoke expansion across unrelated provider pages: rejected because it would create unnecessary suite cost.

## Final Research Outcome

- `ProviderConnection` and `ProviderCredential` persistence stay unchanged.
- The canonical shared `target_scope` contract is the existing descriptor shape, not `entra_tenant_id`.
- The canonical shared identity result is the existing `ProviderIdentityResolution` seam, but its planned contract must stop centering `tenantContext` as shared truth and instead standardize on `target_scope`, `effective_client_identity`, and nested `provider_context`.
- Provider-specific Microsoft details remain available through `ProviderIdentityContextMetadata` and provider-owned consumers only.
- `ProviderConnectionSurfaceSummary` stays the one summary adapter for provider-connections, onboarding, and related context.
- `ProviderOperationStartGate` becomes the critical contract rewrite point for neutral run context.
- `ProviderConnectionResource` remains non-globally-searchable with confirmation-protected mutations intact.
- The narrowest honest proof is the feature suite already named in the spec, one browser smoke, and no new runtime abstractions.