TenantAtlas/specs/237-provider-boundary-hardening/data-model.md

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.