115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# 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. |