# Feature Specification: Provider Boundary Hardening

**Feature Branch**: `237-provider-boundary-hardening`  
**Created**: 2026-04-24  
**Status**: Draft  
**Input**: User description: "Provider Boundary Hardening"

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: TenantPilot already has generic-looking provider seams, but shared contracts and orchestration paths can still absorb Microsoft Graph or Entra semantics as if they were platform-core truth.
- **Today's failure**: Contributors can extend provider-backed workflows by deepening Microsoft-shaped fields, defaults, and fallback behavior inside shared platform seams, which quietly turns future portability into cross-cutting rewrite work.
- **User-visible improvement**: Current Microsoft-backed workflows stay intact while the platform core becomes more predictable, reviewable, and resistant to accidental provider leakage in future work.
- **Smallest enterprise-capable version**: Classify the highest-risk shared seams as provider-owned or platform-core, harden the shared contracts around neutral concepts, and add focused review and test guardrails that block new platform-core Graph leakage.
- **Explicit non-goals**: No second-provider runtime, no AWS or GCP adapters, no broad provider marketplace or registry redesign, no speculative generic connector framework, and no repo-wide copy cleanup beyond seams that are genuinely platform-core.
- **Permanent complexity imported**: One explicit provider-boundary classification model for in-scope seams, one stricter neutral-contract discipline for platform-core paths, one bounded exception model for current-release Microsoft truth, and focused regression coverage for guardrails.
- **Why now**: The roadmap places this immediately after Canonical Control Catalog Foundation in the near-term Governance Platform anti-drift sequence, and Spec 236 is already created.
- **Why not local**: Local fixes inside one adapter or one page would leave other shared seams free to keep importing Microsoft semantics, so the product would continue drifting even while individual hotspots look cleaner.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New abstraction risk and future-proofing risk. Defense: the first slice stays tightly scoped to already hot shared seams, preserves Microsoft-first product truth, and avoids speculative multi-provider runtime work.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**:
  - No new standalone route is required in the hardening slice.
  - Existing provider-backed admin, tenant-context, and monitoring flows remain on their current surfaces and consume the hardened seams behind the scenes.
- **Data Ownership**:
  - No new tenant-owned or workspace-owned business entity is introduced.
  - The first slice hardens shared contracts, boundary classification, and provider-owned metadata handling around existing provider and governance workflows.
- **RBAC**:
  - No new top-level capability is introduced.
  - Existing authorization on provider-backed workflows continues to gate downstream behavior; this spec must not relax workspace or tenant isolation.

For canonical-view specs, the spec MUST define:

- Not applicable in this slice because no new canonical-view surface or cross-tenant filter behavior is introduced.

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: provider-backed orchestration, shared contracts, monitoring-adjacent execution seams, governed-subject resolution boundaries
- **Systems touched**: provider gateways, provider client adapters, shared orchestration or registry seams, and guardrails that review new provider-backed code paths
- **Existing pattern(s) to extend**: current provider gateway and provider client adapter seam, existing provider dispatch and operation orchestration boundaries, current provider-boundary constitution rules
- **Shared contract / presenter / builder / renderer to reuse**: existing provider gateway and provider-dispatch contracts stay in place; the feature hardens which side of the boundary owns provider-specific semantics rather than introducing a parallel path
- **Why the existing shared path is sufficient or insufficient**: the shared seams are sufficient as extension points, but they are insufficiently explicit today about whether touched behavior is provider-owned or platform-core, so contributors can still deepen Microsoft coupling by default
- **Allowed deviation and why**: bounded current-release Microsoft exceptions are allowed only where the seam is explicitly classified as provider-owned or where the spec records a narrow provider-specific necessity
- **Consistency impact**: in-scope shared contracts must use one neutral platform vocabulary, and provider-specific descriptors, identifiers, payload assumptions, and fallback behavior must remain on the provider-owned side of the seam
- **Review focus**: reviewers should block any new shared-path change that exposes Graph- or Entra-shaped semantics as platform-core truth without an explicit boundary classification or approved exception

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: binary ownership with documented current-release exception metadata
- **Seams affected**: provider gateways, client adapters, orchestration entry points, registry or resolution seams that decide provider-backed behavior, and shared vocabulary used by those contracts
- **Authoritative first-slice seam inventory**:
  - `provider.gateway_runtime` -> provider-owned -> `ProviderGateway.php`, `MicrosoftGraphOptionsResolver.php`
  - `provider.identity_resolution` -> platform-core with documented exception metadata -> `ProviderIdentityResolution.php`, `ProviderIdentityResolver.php`, `PlatformProviderIdentityResolver.php`
  - `provider.connection_resolution` -> platform-core with documented exception metadata -> `ProviderConnectionResolver.php`, `ProviderConnectionResolution.php`
  - `provider.operation_registry` -> platform-core -> `ProviderOperationRegistry.php`
  - `provider.operation_start_gate` -> platform-core -> `ProviderOperationStartGate.php`
- **Neutral platform terms preserved or introduced**: provider, provider connection, target scope, operation type, governed subject, provider-owned metadata, platform-core contract, unsupported combination
- **Provider-specific semantics retained and why**: Microsoft Graph payload shapes, Entra and tenant identifiers, Microsoft workload descriptors, and any provider-specific transport or error details remain provider-owned because current product truth is still Microsoft-first
- **Why this does not deepen provider coupling accidentally**: the first slice makes the boundary explicit, keeps seam ownership binary, and requires any retained provider-specific semantics to live either behind provider-owned contracts or as named exception metadata on a platform-core seam instead of becoming a third ownership class
- **Follow-up path**: Provider Identity & Target Scope Neutrality and Platform Vocabulary Boundary Enforcement for Governed Subject Keys build on this boundary hardening rather than redefining it

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

N/A - no operator-facing surface change is required in the hardening slice.

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: yes
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: yes - seam ownership and boundary-check result values are new; runtime `ProviderReasonCodes` expansion remains conditional on whether existing unsupported-path handling is insufficient
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: The product can still become more provider-shaped with each new shared-path change, which raises the long-term cost of governance features and increases the risk that platform-visible behavior is really Microsoft behavior with generic names.
- **Existing structure is insufficient because**: existing generic class names and seams do not by themselves prevent provider-specific identifiers, fallback semantics, or vocabulary from becoming platform-core truth.
- **Narrowest correct implementation**: classify only the highest-risk shared seams, keep current Microsoft behavior where it already belongs, harden neutral contracts at those seams, and add guardrails instead of broad speculative architecture.
- **Ownership cost**: maintainers must preserve the seam classifications, uphold the neutral-contract rules in review, and keep focused tests aligned as provider-backed workflows evolve.
- **Alternative intentionally rejected**: a full multi-provider abstraction rewrite was rejected because it imports speculative scope; pure local cleanup was rejected because it leaves the repo free to continue drifting at every other shared seam.
- **Release truth**: current-release truth with deliberate anti-drift preparation for later provider-boundary follow-through

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Unit, Feature
- **Validation lane(s)**: fast-feedback, confidence
- **Why this classification and these lanes are sufficient**: the first slice is a contract-boundary hardening effort. Unit coverage proves seam classification and neutral-contract rules, while focused feature coverage proves that current Microsoft-backed workflows still behave correctly through the hardened seams.
- **New or expanded test families**: targeted provider-boundary guardrail tests only
- **Fixture / helper cost impact**: minimal; prefer existing provider fixtures and narrow seam-specific helpers over new broad provider test scaffolding
- **Heavy-family visibility / justification**: none; no browser or heavy-governance lane is justified for this slice
- **Special surface test profile**: N/A
- **Standard-native relief or required special coverage**: ordinary feature coverage only
- **Reviewer handoff**: reviewers should confirm that the tests prove boundary ownership and unsupported-path handling, not just class existence, and that no new heavy provider harness becomes the default path for ordinary seam checks
- **Budget / baseline / trend impact**: none expected
- **Escalation needed**: none
- **Active feature PR close-out entry**: Guardrail
- **Planned validation commands**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderBoundaryClassificationTest.php tests/Unit/Providers/ProviderBoundaryGuardrailTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Providers/ProviderBoundaryHardeningTest.php tests/Feature/Providers/UnsupportedProviderBoundaryPathTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ProviderBoundaryPlatformCoreGuardTest.php`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Classify Shared Seams Before Extending Them (Priority: P1)

As a maintainer extending a provider-backed workflow, I want to know whether a seam is provider-owned or platform-core before I change it so I do not accidentally encode Microsoft semantics into shared platform truth.

**Why this priority**: This is the smallest valuable slice. If the seam classification is explicit, later changes can stay bounded even before every follow-on cleanup is delivered.

**Independent Test**: Inspect a targeted shared seam, classify it, and prove that a contributor can determine where provider-specific semantics are allowed without guessing from class names alone.

**Acceptance Scenarios**:

1. **Given** a shared provider-backed seam is in scope for the hardening slice, **When** a maintainer reviews it, **Then** the seam is explicitly classified as provider-owned or platform-core.
2. **Given** a seam is classified as platform-core, **When** a change introduces Microsoft-specific identifiers or payload assumptions there, **Then** the change is rejected by the defined guardrails rather than silently accepted.

---

### User Story 2 - Keep Microsoft Truth Bounded Without Breaking Current Behavior (Priority: P1)

As a product maintainer, I want current Microsoft-backed workflows to continue working while Microsoft-specific semantics move or remain behind provider-owned boundaries so the anti-drift work does not regress the current release.

**Why this priority**: The hardening only matters if it is shippable without destabilizing the product's actual Microsoft-first workflows.

**Independent Test**: Exercise at least one hardened Microsoft-backed path and confirm the user-visible behavior stays the same while the shared seam no longer owns provider-specific truth.

**Acceptance Scenarios**:

1. **Given** a provider-owned adapter is responsible for Microsoft-specific request or response handling, **When** the shared platform seam calls it, **Then** the Microsoft behavior still completes correctly without moving Graph semantics into the platform-core contract.
2. **Given** a provider-specific concept is not supported at a shared seam, **When** the platform-core path encounters it, **Then** the result is an explicit unsupported outcome instead of an inherited Microsoft default.

---

### User Story 3 - Catch New Provider Leakage in Review and CI (Priority: P2)

As a reviewer, I want narrow tests and guardrails that catch new platform-core provider leakage so the boundary does not depend on tribal knowledge.

**Why this priority**: Without enforceable guardrails, the spec would describe a preferred architecture but not actually keep the repo from drifting back.

**Independent Test**: Introduce a representative provider-specific field or fallback into a platform-core seam and verify that the new guardrail coverage fails.

**Acceptance Scenarios**:

1. **Given** a new platform-core contract change introduces provider-specific vocabulary without an approved exception, **When** the targeted tests or review guardrails run, **Then** the change fails visibly.
2. **Given** a provider-owned seam intentionally keeps Microsoft-specific metadata, **When** the same guardrails run, **Then** the bounded provider-owned usage is allowed and documented instead of being treated as a false violation.

### Edge Cases

- One in-scope seam contains both neutral platform fields and provider-owned metadata and must separate them without inventing duplicate contracts.
- A historical shared path still uses Graph- or Entra-shaped field names even though the seam is now classified as platform-core.
- Only one provider exists in production today, so unsupported-path behavior must stay explicit without pretending a second provider runtime already exists.
- A shared orchestration path currently falls back to Microsoft-first behavior when no explicit provider handler is present.
- A provider-owned surface intentionally uses Microsoft vocabulary because the operator is configuring a Microsoft-specific capability, while the shared contract under it must remain neutral.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature does not add Microsoft Graph calls, destructive mutations, or new queued work. It hardens where existing provider-backed runtime behavior may encode provider-specific semantics into platform-core truth. If implementation touches existing writes or operations, that slice must keep current tenant isolation and existing observability intact.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature intentionally introduces one explicit boundary-classification model and one stricter neutral-contract discipline because generic class names alone have not prevented provider leakage. The first slice stays derived and review-oriented, avoids new persistence, and avoids speculative multi-provider abstractions.

**Constitution alignment (XCUT-001):** This feature is cross-cutting across provider gateways, orchestration, and shared contracts. It extends existing shared seams rather than creating parallel provider infrastructure, and reviewer focus stays on preventing new local Microsoft-shaped paths from appearing inside platform-core code.

**Constitution alignment (PROV-001):** Every in-scope seam must be classified as provider-owned or platform-core. Provider-specific semantics remain on provider-owned paths unless a narrow current-release exception is documented. Shared platform contracts preserve neutral platform vocabulary and explicit unsupported-path behavior.

**Constitution alignment (TEST-GOV-001):** Coverage stays in narrow unit and feature lanes. Tests must prove boundary ownership and unsupported-path semantics on the touched seams without introducing a broad provider integration harness.

**Constitution alignment (OPS-UX):** Not applicable in this slice because it does not create or redesign an `OperationRun`.

**Constitution alignment (RBAC-UX):** No authorization boundary changes are introduced. Existing authorization continues to protect provider-backed flows on their current surfaces.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable.

**Constitution alignment (BADGE-001):** Not applicable in this slice because no new status badge family is introduced.

**Constitution alignment (UI-FIL-001):** Not applicable in this slice because no Filament surface change is required.

**Constitution alignment (UI-NAMING-001):** If implementation touches any operator-visible provider descriptor as part of a hardened seam, Microsoft-specific wording must remain contextual to the provider-owned surface and must not redefine the shared platform contract.

**Constitution alignment (DECIDE-001):** Not applicable in this slice because no new or materially changed operator-facing decision surface is required.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** Not applicable in this slice because no operator-facing surface is added or materially refactored.

**Constitution alignment (ACTSURF-001 - action hierarchy):** Not applicable.

**Constitution alignment (OPSURF-001):** Not applicable in this slice because there is no new operator-facing page contract.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** The feature adds one interpretation layer for boundary ownership because direct reuse of current class names and runtime paths is insufficient to keep provider-specific truth out of platform-core seams. Tests must focus on boundary consequences rather than thin wrappers.

### Functional Requirements

- **FR-237-001 Boundary ownership classification**: The system MUST define one explicit boundary-ownership classification for every high-risk shared seam touched by this feature, identifying it as provider-owned or platform-core. Retained current-release exceptions MUST be recorded as seam metadata, not as a third ownership class.
- **FR-237-002 Neutral platform-core contracts**: Platform-core seams in scope MUST use neutral platform vocabulary and MUST NOT expose Microsoft- or Graph-specific identifiers, payload semantics, or fallback assumptions as their primary contract.
- **FR-237-003 Provider-owned metadata containment**: Microsoft-specific request, response, transport, verification, and error semantics MUST remain behind provider-owned adapters or services.
- **FR-237-004 Hardened shared seam coverage**: The first slice MUST harden at least the current provider gateway seam and at least one shared orchestration or registry seam where provider leakage currently risks becoming platform-core truth.
- **FR-237-005 Explicit unsupported behavior**: If a platform-core seam encounters a provider-specific behavior with no explicit provider-owned handler, the outcome MUST be explicit unsupported behavior rather than inherited Microsoft default behavior.
- **FR-237-006 Current-release behavior preservation**: The hardened seams MUST preserve current Microsoft-backed product behavior for already supported flows.
- **FR-237-007 Exception discipline**: Any retained provider-specific semantics at a shared seam MUST be documented as a narrow current-release exception and MUST NOT become the default meaning of the platform-core contract.
- **FR-237-008 Review and test guardrails**: The repo MUST provide focused review or test guardrails that fail when new platform-core provider leakage is introduced on an in-scope seam.
- **FR-237-009 Provider-owned allowance**: The same guardrails MUST allow provider-specific metadata and logic on seams explicitly classified as provider-owned.
- **FR-237-010 No speculative multi-provider runtime**: The first slice MUST NOT introduce second-provider execution paths, provider marketplace abstractions, or generic connector runtime machinery.
- **FR-237-011 Shared vocabulary continuity**: Follow-on provider-boundary work for identity, target scope, or governed-subject vocabulary MUST be able to build on the same boundary classifications instead of redefining them locally.
- **FR-237-012 Explicit shared orchestration binding**: Shared orchestration paths touched by this feature MUST require an explicit provider binding instead of inferring `microsoft` as an implicit default when the platform-core path resolves an operation.

### Key Entities *(include if feature involves data)*

- **Boundary Ownership Classification**: The explicit determination that a touched seam is either provider-owned or platform-core, with any narrow current-release exception recorded as metadata on that seam.
- **Platform-Core Contract**: A shared contract that expresses provider-neutral platform concepts and delegates provider-specific behavior to provider-owned seams.
- **Provider-Owned Adapter**: The seam that translates Microsoft-specific identifiers, payloads, verification details, and errors into or out of platform-core contracts without redefining platform truth.
- **Boundary Guardrail Result**: The focused review or test outcome that confirms whether a changed seam respects the declared ownership and neutral-contract rules.

## Assumptions

- Current-release product truth remains Microsoft-first, but Microsoft semantics must stay bounded where the seam is platform-core.
- Existing provider gateway and orchestration hotspots are sufficient to prove the first slice without introducing a new provider runtime.
- Identity, target-scope, and governed-subject follow-through specs will consume this boundary decision instead of reopening it from scratch.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-237-001**: 100% of high-risk shared seams touched in the first slice are explicitly classified as provider-owned or platform-core before implementation is considered complete.
- **SC-237-002**: 100% of platform-core seams hardened by this spec avoid Microsoft- or Graph-specific primary contract fields or fallback semantics.
- **SC-237-003**: At least one already supported Microsoft-backed workflow continues to pass through the hardened seams without user-visible regression.
- **SC-237-004**: In all covered unsupported-path scenarios for the hardened seams, the outcome is explicit unsupported behavior rather than inherited Microsoft default behavior.