# Data Model: Provider Boundary Hardening

## Overview

The first slice introduces one explicit seam-ownership catalog with binary ownership plus documented exception metadata, one split between shared operation definition and provider binding, and one deterministic guard result shape. No new database persistence is introduced.

## Entity: ProviderBoundarySeam

- **Purpose**: Declares whether a touched seam is provider-owned or platform-core, and records any documented current-release exception metadata that remains temporarily allowed.
- **Identity**:
  - `seam_key` — stable catalog key such as `provider.gateway_runtime`, `provider.identity_resolution`, or `provider.operation_registry`
- **Core fields**:
  - `owner`
  - `description`
  - `implementation_paths[]`
  - `neutral_terms[]`
  - `retained_provider_semantics[]`
  - `follow_up_action`
- **Owner values**:
  - `provider_owned`
  - `platform_core`
- **Validation rules**:
  - Every first-slice seam must have exactly one owner classification.
  - `platform_core` seams must list the neutral platform terms they preserve.
  - Any seam that retains provider-specific semantics must list them in `retained_provider_semantics[]` and pair them with an explicit `follow_up_action`.
  - `implementation_paths[]` must reference real code paths used by tests and review guardrails.

### Authoritative first-slice seam inventory

- `provider.gateway_runtime` — `ProviderGateway.php`, `MicrosoftGraphOptionsResolver.php`
- `provider.identity_resolution` — `ProviderIdentityResolution.php`, `ProviderIdentityResolver.php`, `PlatformProviderIdentityResolver.php`
- `provider.connection_resolution` — `ProviderConnectionResolver.php`, `ProviderConnectionResolution.php`
- `provider.operation_registry` — `ProviderOperationRegistry.php`
- `provider.operation_start_gate` — `ProviderOperationStartGate.php`

## Entity: ProviderOperationDefinition

- **Purpose**: Represents the platform-core definition of a provider-backed operation without silently embedding provider truth.
- **Identity**:
  - `operation_type`
- **Core fields**:
  - `module_key`
  - `label`
  - `required_capability`
- **Validation rules**:
  - The definition must not require a provider field as its primary identity.
  - Labels and module keys remain shared orchestration truth and do not encode Microsoft-specific vocabulary by default.
  - Operation type values remain unchanged in this slice.

## Entity: ProviderOperationBinding

- **Purpose**: Connects one shared operation definition to the current provider-owned runtime behavior.
- **Fields**:
  - `operation_type`
  - `provider`
  - `binding_status`
  - `handler_notes`
  - `exception_notes`
- **Binding status values**:
  - `active`
  - `unsupported`
- **Validation rules**:
  - Every binding must reference an existing `operation_type`.
  - Missing binding is explicit and must not fall back silently to Microsoft behavior.
  - Provider-specific notes remain secondary to the platform-core operation definition.

## Entity: ProviderBoundaryCheckResult

- **Purpose**: Shared deterministic result used by tests and review guardrails.
- **Fields**:
  - `status`
  - `seam_key`
  - `file_path`
  - `violation_code`
  - `message`
  - `suggested_follow_up`
- **Status values**:
  - `allowed`
  - `review_required`
  - `blocked`
- **Violation code examples**:
  - `platform_core_provider_leak`
  - `undeclared_exception`
  - `missing_provider_binding`
  - `provider_binding_as_primary_truth`
- **Validation rules**:
  - `allowed` means the touched seam matches its declared ownership.
  - `review_required` means the seam has documented exception metadata or needs explicit follow-up.
  - `blocked` means the touched change violates the seam ownership or provider-binding rules.

## Relationships

- One `ProviderBoundarySeam` may cover multiple implementation paths.
- One `ProviderOperationDefinition` may have one current `ProviderOperationBinding` in the first slice because only Microsoft runtime support exists today.
- One `ProviderBoundaryCheckResult` references exactly one seam evaluation, but a review may emit multiple results across multiple touched files.

## Lifecycle

### Boundary seam lifecycle

- `provider_owned`: provider-specific semantics are allowed inside the seam.
- `platform_core`: provider-specific semantics are blocked unless explicitly extracted.
- `platform_core` with documented exception metadata: named provider-specific details remain temporarily allowed only while the seam records the retained semantics and explicit follow-up action.

### Operation binding lifecycle

- `active`: current provider runtime is explicitly supported for the operation.
- `unsupported`: the operation definition exists, but the current seam must fail explicitly instead of inheriting default provider behavior.

## Rollout Model

- The first slice keeps the catalog in code, not in the database.
- Existing Microsoft-backed runtime behavior remains the only shipped provider binding.
- Shared identity resolution and operation registry cleanup happen before any persistence or UI neutrality changes.
- Deeper target-scope and provider-connection neutrality remain follow-up work.