# Data Model: Provider Identity & Target Scope Neutrality

## Overview

This slice introduces one shared target-scope descriptor, one provider-owned contextual identity metadata shape, one operator-facing connection summary, and one narrow neutrality guard result. No new database persistence is introduced.

## Entity: ProviderConnectionTargetScopeDescriptor

- **Purpose**: Express the neutral platform meaning of what a provider connection points to without carrying provider-specific identity as part of the descriptor itself.
- **Identity**:
  - `provider_connection_id` for existing records
  - draft or create-flow input tuple `(provider, scope_kind, scope_identifier, scope_display_name)` before persistence
- **Core fields**:
  - `provider`
  - `scope_kind`
  - `scope_identifier`
  - `scope_display_name`
  - `shared_label`
  - `shared_help_text`
- **Validation rules**:
  - The descriptor must remain renderable without provider-specific labels.
  - In this current-release slice, `scope_kind` is tenant-only even though the neutral field remains generic for future provider-boundary-safe extension.
  - `scope_kind`, `scope_identifier`, and `scope_display_name` must be sufficient to describe the neutral target-scope meaning on shared surfaces.
  - `scope_identifier` and `scope_display_name` must be usable on shared surfaces without relying on Microsoft directory vocabulary.
  - Provider-owned identity details must live beside the descriptor in contextual metadata or summary shapes, not inside the descriptor itself.

## Entity: ProviderConnectionTargetScopeNormalizationResult

- **Purpose**: Represent the deterministic result of normalizing create or edit input before persistence, including explicit blocked outcomes for unsupported combinations or missing provider context.
- **Fields**:
  - `status`
  - `provider`
  - `scope_kind`
  - `target_scope` when `status = normalized`
  - `contextual_identity_details[]` when `status = normalized`
  - `preview_summary` when a shared-surface preview can be derived without assuming persisted runtime state
  - `failure_code`
  - `message`
- **Status values**:
  - `normalized`
  - `blocked`
- **Failure code values**:
  - `none`
  - `unsupported_provider_scope_combination`
  - `missing_provider_context`
- **Validation rules**:
  - `normalized` results must carry `provider`, `scope_kind`, `target_scope`, `contextual_identity_details[]`, `failure_code = none`, and a human-readable `message`; they may include `preview_summary` only when consent and verification state can be derived without assuming persisted runtime state.
  - `blocked` results must carry `provider`, `scope_kind`, `failure_code`, and `message` and must not pretend readiness or persisted summary truth exists.
  - The normalization result must preserve the distinction between neutral target-scope truth and provider-owned contextual identity details.

## Entity: ProviderIdentityContextMetadata

- **Purpose**: Carry provider-owned identity details that remain necessary for Microsoft consent, verification, troubleshooting, or audit drill-in.
- **Fields**:
  - `provider`
  - `detail_key`
  - `detail_label`
  - `detail_value`
  - `visibility`
- **Visibility values**:
  - `contextual_only`
  - `audit_only`
  - `troubleshooting_only`
- **Validation rules**:
  - Context metadata must never replace the shared target-scope descriptor on generic provider surfaces.
  - Microsoft-only labels such as `Entra tenant ID` remain allowed only when `provider = microsoft` and visibility is contextual.

## Entity: ProviderConnectionSurfaceSummary

- **Purpose**: Define the default-visible operator-facing summary for shared provider connection surfaces.
- **Fields**:
  - `provider`
  - `target_scope`
  - `consent_state`
  - `verification_state`
  - `readiness_summary`
  - `contextual_identity_details[]`
- **Validation rules**:
  - `provider`, `target_scope`, `consent_state`, and `verification_state` must all be visible without opening diagnostics.
  - `contextual_identity_details[]` must remain secondary to the target-scope summary.
  - Shared surface summaries must not collapse consent and verification into one ambiguous state.

## Entity: ProviderConnectionNeutralityCheckResult

- **Purpose**: Deterministic result shape used by guard tests and review checks.
- **Fields**:
  - `status`
  - `surface_key`
  - `path`
  - `surface_ownership`
  - `allowed_exception_classes[]`
  - `violation_code`
  - `message`
  - `suggested_follow_up`
- **Status values**:
  - `allowed`
  - `review_required`
  - `blocked`
- **Violation code examples**:
  - `provider_specific_default_label`
  - `provider_specific_default_filter`
  - `provider_specific_required_field`
  - `provider_specific_validation_message`
  - `provider_specific_default_helper_copy`
  - `provider_specific_default_audit_prose`
  - `missing_target_scope_descriptor`
- **Surface ownership values**:
  - `platform_core`
  - `provider_owned`
- **Validation rules**:
  - `allowed` means the shared surface uses neutral target-scope truth by default.
  - `review_required` means the path contains documented provider-owned contextual detail or an allowed exception class.
  - `blocked` means a shared surface reintroduced provider-specific default truth.

## Relationships

- One `ProviderConnectionSurfaceSummary` consumes exactly one `ProviderConnectionTargetScopeDescriptor` and may carry zero or more `ProviderIdentityContextMetadata` entries beside it.
- One `ProviderConnectionTargetScopeNormalizationResult` may carry zero or more `ProviderIdentityContextMetadata` entries beside exactly one normalized target-scope descriptor.
- One `ProviderConnectionNeutralityCheckResult` references exactly one touched surface or helper path.

## Lifecycle

### Target-scope descriptor lifecycle

- `draft_input`: create or edit flow has neutral shared scope data but is not yet persisted.
- `persisted_shared_truth`: existing `provider_connections` row has a neutral target-scope descriptor available for shared surfaces.
- `context_enriched`: provider-owned contextual details are attached for Microsoft consent, verification, or audit drill-in.

### Neutrality check lifecycle

- `allowed`: shared surface is neutral by default.
- `review_required`: shared surface stays neutral but exposes documented provider-owned contextual detail.
- `blocked`: shared surface or helper reintroduced provider-specific default truth.

## Rollout Model

- No new database table or column is planned for this slice.
- The descriptor layer is derived from existing provider connection truth and existing provider-owned identity details.
- Provider connection list, detail, create, edit, onboarding provider setup, and audit wording adopt the new descriptor first.
- Broader provider identity migration and compare-boundary work remain out of scope for this feature.