# Research: Provider Identity & Target Scope Neutrality

## Decision 1: Use one small shared target-scope descriptor instead of a broad provider identity framework

- **Decision**: Introduce one small shared descriptor for provider connection target scope and reuse it across the provider connection resource, onboarding, validation, and audit wording.
- **Rationale**: The current release needs one neutral shared truth for multiple real surfaces, not a generalized provider marketplace or identity framework. A small descriptor layer is enough to keep shared language neutral while still letting Microsoft-specific detail remain contextual.
- **Alternatives considered**:
  - Page-local label cleanup only: rejected because it would leave the shared contract Microsoft-shaped underneath.
  - Broad provider identity abstraction: rejected because there is still only one shipped provider runtime and the current hotspot is narrower than that.

## Decision 2: Keep Microsoft tenant and directory details as provider-owned contextual metadata

- **Decision**: Retain `entra_tenant_id`, authority-tenant details, consent wording, and Microsoft verification details only as contextual provider-owned metadata on Microsoft paths.
- **Rationale**: Operators still need Microsoft-specific identifiers for consent and troubleshooting, but those identifiers should not define the default meaning of a provider connection on generic shared surfaces.
- **Alternatives considered**:
  - Remove Microsoft-specific details from the UI entirely: rejected because the current product still needs them on Microsoft-only workflows.
  - Keep them as the default connection summary: rejected because that preserves the current provider-boundary drift.

## Decision 3: Neutralize shared Filament surfaces first, not every provider term in the repo

- **Decision**: Limit the first slice to provider connection list, detail, create, edit, onboarding provider setup, and shared audit or validation wording directly tied to those surfaces.
- **Rationale**: These are the concrete operator-facing hotspots already named in the spec. A repo-wide terminology sweep would widen scope without improving the core shared contract any faster.
- **Alternatives considered**:
  - Rename every provider-related term immediately: rejected because it would turn one bounded hotspot into a broad copy and architecture sweep.
  - Leave onboarding for later: rejected because it would preserve two competing interpretations of the same connection truth.

## Decision 4: Anchor neutrality in shared resolution and mutation paths, not only in UI labels

- **Decision**: Update the existing provider connection and identity-resolution outputs plus mutation and audit wording so shared surfaces all consume the same neutral target-scope semantics.
- **Rationale**: UI-only changes would be fragile because validation, audit prose, and future surfaces would still source their meaning from Microsoft-shaped service outputs.
- **Alternatives considered**:
  - Keep service outputs unchanged and translate everything in Filament only: rejected because future surfaces would likely repeat the same drift.
  - Replace the entire provider identity stack: rejected because the current hotspot is limited to shared target-scope meaning.

## Decision 5: Enforce the contract with focused guardrails, not browser coverage

- **Decision**: Add focused unit and feature guard coverage for neutral target-scope descriptors, shared surface labels, onboarding reuse, and audit wording.
- **Rationale**: The risk is semantic drift in shared provider connection truth, not browser-only interaction. Narrow unit and feature coverage are the cheapest proof.
- **Alternatives considered**:
  - Browser tests: rejected because they add cost without proving unique behavior for this slice.
  - Manual review only: rejected because the feature exists to stop the same hotspot from reopening quietly.