TenantAtlas/specs/427-exchange-teams-verified-source-contract-enablement/plan.md

# Implementation Plan: Spec 427 - Exchange / Teams Verified Source Contract Enablement

**Branch**: `427-exchange-teams-verified-source-contract-enablement` | **Date**: 2026-07-03 | **Spec**: `specs/427-exchange-teams-verified-source-contract-enablement/spec.md`  
**Input**: Feature specification from `/specs/427-exchange-teams-verified-source-contract-enablement/spec.md`

## Summary

Verify and enable precise source-contract states for exactly four Exchange/Teams Coverage v2 resource types: `transportRule`, `acceptedDomain`, `appPermissionPolicy`, and `meetingPolicy`. The implementation must use the existing Coverage v2 source-contract resolver/registry path, record verified-pending-capture or exact blocker reasons, and prove that no evidence, compare/render, certification, restore, customer output, UI, or provider capture is promoted by this spec.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12, Filament 5, Livewire 4  
**Primary Dependencies**: Existing Coverage v2 Tenant Configuration services, `GraphClientInterface` / repo provider abstraction, Pest 4  
**Storage**: PostgreSQL via existing Coverage v2 tables/metadata; no new table by default  
**Testing**: Pest 4 unit and feature tests; browser N/A by default  
**Validation Lanes**: focused fast-feedback/confidence files; no browser lane unless the spec is amended for UI  
**Target Platform**: Laravel monolith under `apps/platform`  
**Project Type**: Web application / Laravel monolith  
**Performance Goals**: No real provider calls; resolver decisions must be deterministic and cheap  
**Constraints**: no remote capture, no evidence promotion, no UI, no `tenant_id`, no endpoint guessing, no provider permission widening  
**Scale/Scope**: exactly four repo-canonical resource types; no optional Exchange/Teams expansion

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing surface change.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A.
- **No-impact class, if applicable**: backend/internal contract metadata and tests only.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: Coverage v2 contract/metadata family only; no rendered shared detail family.
- **State layers in scope**: none for UI; internal source-contract state/reason metadata only.
- **Audience modes in scope**: N/A.
- **Decision/diagnostic/raw hierarchy plan**: N/A for UI; raw/support data stays out of default output/logs.
- **Raw/support gating plan**: raw payloads and secrets are not displayed/logged.
- **One-primary-action / duplicate-truth control**: N/A.
- **Handling modes by drift class or surface**: report-only N/A path for no rendered UI.
- **Repository-signal treatment**: no UI signal expected.
- **Special surface test profiles**: N/A.
- **Required tests or manual smoke**: functional core tests only; browser `N/A - no rendered UI surface changed`.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage: `N/A - no rendered UI surface changed`.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none.
- **No-impact rationale**: Contract verification is internal prerequisite truth and requires no reachable rendered surface.
- **Navigation / Filament provider-panel handling**: no panel/provider change.
- **Screenshot or page-report need**: no.

## Product Surface Contract Plan

- **Product Surface Contract reference**: N/A - no rendered product surface changed.
- **No-legacy posture**: canonical replacement / no compatibility exception.
- **Page archetype and surface budget plan**: N/A.
- **Technical Annex and deep-link demotion plan**: N/A for UI. Contract proof stays in tests/implementation report; raw payloads, source keys, permissions, and blocker diagnostics are not product content.
- **Canonical status vocabulary plan**: N/A for rendered UI. Internal source-contract states are prerequisite states, not product badges.
- **Product Surface exceptions**: none.
- **Browser verification plan**: `N/A - no rendered UI surface changed`.
- **Human Product Sanity plan**: N/A.
- **Visible complexity outcome target**: neutral.
- **Implementation report target**: `specs/427-exchange-teams-verified-source-contract-enablement/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire v4.x confirmed; no Livewire code change planned.
- **Panel provider registration location**: no panel change; Laravel providers remain in `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no Filament Resource/global search behavior changed.
- **Destructive/high-impact action posture**: none; no UI or mutation action added.
- **Asset strategy**: no assets; no new `filament:assets` requirement.
- **Testing plan**: resolver, contract metadata, fail-safe/no-promotion, identity, redaction, no-tenant-id, no-mini-platform, and regression tests.
- **Deployment impact**: no env vars, migrations, queues, scheduler, storage, or assets by default. If implementation discovers a required migration or provider permission productization, stop and amend this spec first.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php`, `CoverageSourceContractDecision`, `ResourceTypeRegistry`, `apps/platform/config/graph_contracts.php` only when verified repo-safe contracts exist, identity registry/resolver, claim guard, redaction helpers, and focused tests.
- **Shared abstractions reused**: existing Coverage v2 source-contract resolver/registry, `GraphClientInterface` / repo provider abstraction, identity strategy registry, and Claim Guard.
- **New abstraction introduced? why?**: none planned. A small value object/helper is allowed only if it replaces ambiguity in the existing resolver and remains proportional.
- **Why the existing abstraction was sufficient or insufficient**: Existing resolver decides captured vs blocked, but current generic missing-contract behavior is too coarse for the next Exchange/Teams evidence sequence. The plan adds precise metadata/state inside the existing path rather than a new platform.
- **Bounded deviation / spread control**: source-contract state/reason values are limited to four target types and must have direct behavior/test consequences.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: none.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

No remote capture, provider operation, queued work, or OperationRun creation is in scope. If live provider verification becomes necessary, implementation must stop and the spec must be amended.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes.
- **Provider-owned seams**: Exchange/Teams source contract names, Microsoft permission names, response shapes, provider-native IDs, and source versions.
- **Platform-core seams**: Coverage v2 contract state/blocker semantics, capture eligibility, claim safety, evidence promotion rules, workspace/managed-environment/provider-connection ownership.
- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider connection, resource type, source contract, capture eligibility, blocker reason, evidence, claim state.
- **Retained provider-specific semantics and why**: Exchange/Teams labels and Microsoft contract metadata are necessary to verify these four concrete contracts, but remain provider-owned metadata.
- **Bounded extraction or follow-up path**: document-in-feature for any contained provider-specific blocker; follow-up-spec only if provider permission productization or contract verification requires a broader product decision.

## Constitution Check

- Inventory-first: no inventory/snapshot truth changes; source contracts remain prerequisites.
- Read/write separation: no write/change/provider capture action in scope.
- Graph contract path: any verified Graph source must be represented through existing contract registry/provider abstraction; direct HTTP and endpoint guessing are forbidden.
- Deterministic capabilities: contract states and blocker reasons must be testable.
- RBAC-UX: no new UI/action; provider-context checks must preserve existing workspace/environment/provider scope if touched.
- Workspace isolation: any provider-context verification must remain same workspace and managed environment.
- Tenant isolation / SCOPE-001: no `tenant_id`; provider-native tenant IDs remain metadata only.
- Run observability: no remote/queued work; OperationRun is N/A.
- Data minimization: no raw provider payload, secrets, or raw permission context in logs/default output.
- Test governance: focused Unit/Feature tests are the narrowest proof; browser N/A.
- Proportionality: bounded contract-state/reason metadata is justified by false-readiness prevention and immediate prerequisite value.
- No premature abstraction: extend existing resolver/registry; no Exchange/Teams mini-platform.
- Persisted truth: no new persisted entity by default.
- Behavioral state: every new state/reason changes a blocker/follow-up action; presentation-only labels are forbidden.
- Shared pattern first: reuse Coverage v2 resolver/registry and claim guard.
- Provider boundary: provider details remain provider-owned metadata.
- UI/Productization coverage: no rendered UI; Product Surface N/A.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for resolver/metadata/state mapping; Feature for no-promotion, no-tenant-id, no-mini-platform, and regressions.
- **Affected validation lanes**: focused fast-feedback/confidence.
- **Why this lane mix is the narrowest sufficient proof**: No rendered UI and no real provider calls are in scope; service/config behavior can be proven with focused tests.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec427ExchangeTeamsSourceContractStateTest.php tests/Unit/Support/TenantConfiguration/Spec427ExchangeTransportRuleContractTest.php tests/Unit/Support/TenantConfiguration/Spec427ExchangeAcceptedDomainContractTest.php tests/Unit/Support/TenantConfiguration/Spec427TeamsAppPermissionPolicyContractTest.php tests/Unit/Support/TenantConfiguration/Spec427TeamsMeetingPolicyContractTest.php tests/Unit/Support/TenantConfiguration/Spec427SourceContractPermissionMetadataTest.php tests/Unit/Support/TenantConfiguration/Spec427SourceContractResponseShapeTest.php tests/Unit/Support/TenantConfiguration/Spec427SourceContractIdentityHandoffTest.php tests/Unit/Support/TenantConfiguration/Spec427SourceContractRedactionTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec427ExchangeTeamsNoEvidencePromotionTest.php tests/Feature/TenantConfiguration/Spec427ExchangeTeamsNoCompareRenderCertificationTest.php tests/Feature/TenantConfiguration/Spec427ExchangeTeamsNoCustomerRestoreClaimTest.php tests/Feature/TenantConfiguration/Spec427ExchangeTeamsNoTenantIdTest.php tests/Feature/TenantConfiguration/Spec427ExchangeTeamsNoMiniPlatformTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec426ExchangeTeamsSourceContractResolverTest.php tests/Feature/TenantConfiguration/Spec426ExchangeTeamsCoreEvidenceReadinessTest.php tests/Unit/Support/TenantConfiguration/Spec417CoverageIdentityStrategyRegistryTest.php tests/Unit/Support/TenantConfiguration/Spec420M365CaptureSourceContractResolverTest.php tests/Feature/TenantConfiguration/Spec420M365GenericEvidenceCaptureTest.php`
- **Fixture / helper / factory / seed / context cost risks**: local fake contract metadata/payload shapes only; no broader default setup.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: N/A - no rendered UI surface changed.
- **Closing validation and reviewer handoff**: implementation report must list exact commands, pass counts, and any Signal 9 direct-file fallback.
- **Budget / baseline / trend follow-up**: none expected.
- **Review-stop questions**: no endpoint guessing, no fake verified contract, no evidence promotion, no `tenant_id`, no hidden provider calls.
- **Escalation path**: document-in-feature for exact blocked contracts; follow-up-spec for provider permission productization or live capture.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: This spec is already the bounded source-contract prerequisite; broader promotions are listed as separate follow-ups.

## Project Structure

### Documentation (this feature)

```text
specs/427-exchange-teams-verified-source-contract-enablement/
|-- spec.md
|-- plan.md
|-- tasks.md
`-- checklists/
    `-- requirements.md
```

### Source Code (likely affected during later implementation)

```text
apps/platform/
|-- app/
|   |-- Services/TenantConfiguration/
|   |   |-- CoverageSourceContractResolver.php
|   |   |-- CoverageSourceContractDecision.php
|   |   |-- CoverageIdentityStrategyRegistry.php
|   |   `-- ClaimGuard.php
|   `-- Support/TenantConfiguration/
|       `-- CaptureOutcome.php
|-- config/
|   `-- graph_contracts.php
`-- tests/
    |-- Unit/Support/TenantConfiguration/
    `-- Feature/TenantConfiguration/
```

**Structure Decision**: Keep all runtime work inside existing Coverage v2 Tenant Configuration services/config/tests. Do not create new base folders, Exchange/Teams table families, dashboards, routes, or provider subsystem.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
| --- | --- | --- |
| Bounded source-contract state/reason vocabulary | Later evidence/certification specs need exact blockers and next actions | Generic `capture_blocked_missing_contract` cannot distinguish missing source, permission, beta-only, response shape, adapter, identity, or redaction blockers |

## Proportionality Review

- **Current operator problem**: Release reviewers need exact proof that Exchange/Teams contracts are verified or blocked before later evidence/certification claims.
- **Existing structure is insufficient because**: Existing generic blocked outcomes are safe but too coarse to unblock or intentionally defer later work.
- **Narrowest correct implementation**: Add precise state/reason metadata for four existing resource types in existing resolver/registry paths.
- **Ownership cost created**: Four per-type matrices, focused tests, and implementation-report proof.
- **Alternative intentionally rejected**: Leave all four as generic missing-contract blockers. Rejected because it would force future specs to rediscover blockers and risks endpoint guessing.
- **Release truth**: Current prerequisite truth for the immediate Coverage v2 Exchange/Teams sequence.

## Implementation Phases

### Phase 0 - Preflight

Confirm branch, dirty state, completed dependency status, target canonical names, current resolver behavior, no UI scope, no OperationRun scope, and no evidence promotion scope.

### Phase 1 - Target Mapping And Current-State Audit

Map spec labels to repo-canonical resource types and document current registry/source-contract/identity/readiness state for each.

### Phase 2 - Contract State Model

Add or confirm the bounded verified/blocker state model and mapping to repo-canonical outcomes/metadata, including the draft `graph_v1` label to repo-canonical `graph_v1_fallback` where applicable.

### Phase 3 - Per-Type Contract Verification

For each target type, verify source class, contract name/version, permission model, response shape, identity handoff, redaction rules, and final state. Block instead of guessing.

### Phase 4 - Resolver / Registry Integration

Integrate verified or blocked contract states through the existing resolver/registry path.

### Phase 5 - No-Promotion And Regression Proof

Prove no evidence, coverage promotion, compare/render, certification, restore, customer claim, `tenant_id`, or mini-platform appears. Re-run Spec 426/417/420 regressions.

### Phase 6 - Implementation Report

Record matrices, validation, Product Surface N/A, Filament/Livewire output contract, deployment impact, deferred work, and gate results.