TenantAtlas/specs/238-provider-identity-target-scope/research.md

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.