TenantAtlas/specs/429-exchange-teams-source-surface-catalog-adapter-strategy/plan.md

# Implementation Plan: Spec 429 - Exchange/Teams Source Surface Catalog & Adapter Strategy

**Branch**: `429-exchange-teams-source-surface-catalog-adapter-strategy` | **Date**: 2026-07-04 | **Spec**: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md`
**Input**: Feature specification from `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/spec.md`

## Summary

Prepare a no-runtime Exchange/Teams source-surface catalog and adapter strategy. The implementation loop must create static Spec Kit catalog artifacts only, classify source surfaces and adapter patterns, choose a bounded Cohort 1, document blockers and deferred boundaries, and prove no runtime code, provider calls, evidence, OperationRuns, UI, or customer claims changed.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12 repo context; no runtime code planned
**Primary Dependencies**: Existing Spec Kit artifacts; Microsoft Learn official documentation; existing Coverage v2 repo truth
**Storage**: N/A - no database, migration, persisted runtime artifact, or runtime registry consumption
**Testing**: Static artifact validation only; no Pest tests unless implementation adds optional static JSON validation
**Validation Lanes**: docs/spec/catalog validation; no browser lane
**Target Platform**: Laravel monolith under `apps/platform`, read-only context only
**Project Type**: web application monorepo, docs/catalog-only feature
**Performance Goals**: N/A - no runtime path
**Constraints**: no runtime code, migrations, tests, provider calls, OperationRuns, UI, evidence, customer output, or claims
**Scale/Scope**: Exchange/Teams catalog and Cohort 1 strategy for later Spec 430 implementation

## 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**: docs/spec/catalog-only.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: none at runtime.
- **State layers in scope**: none.
- **Audience modes in scope**: N/A.
- **Decision/diagnostic/raw hierarchy plan**: N/A for runtime; catalog artifacts must keep technical source details out of customer/readiness language.
- **Raw/support gating plan**: N/A for runtime.
- **One-primary-action / duplicate-truth control**: N/A.
- **Handling modes by drift class or surface**: hard-stop-candidate if implementation attempts runtime UI, route, navigation, report, Review Pack, PDF, evidence, OperationRun, restore, certification, or customer output work.
- **Repository-signal treatment**: completed Specs 422/426/427 are read-only evidence; Spec 428 is a prepared fail-safe/no-op dependency and non-blocking for catalog-only work.
- **Special surface test profiles**: N/A.
- **Required tests or manual smoke**: `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 - catalog/strategy only, no rendered UI surface changed`.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none.
- **No-impact rationale**: No routes, UI files, Filament resources/pages/widgets, navigation, reports, downloads, or customer surfaces change.
- **Navigation / Filament provider-panel handling**: no panel change.
- **Screenshot or page-report need**: no.

## Product Surface Contract Plan

- **Product Surface Contract reference**: N/A for runtime; spec records no rendered product surface changed.
- **No-legacy posture**: canonical documentation-only strategy; no compatibility exception.
- **Page archetype and surface budget plan**: N/A.
- **Technical Annex and deep-link demotion plan**: N/A at runtime; catalog artifacts must not create application-facing technical annexes.
- **Canonical status vocabulary plan**: N/A for UI. Documentation-only catalog statuses are not runtime vocabulary.
- **Product Surface exceptions**: none.
- **Browser verification plan**: `N/A - no rendered UI surface changed`.
- **Human Product Sanity plan**: N/A for runtime.
- **Visible complexity outcome target**: neutral runtime impact; future implementation should reduce source-surface ambiguity.
- **Implementation report target**: `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: unchanged; no Livewire code.
- **Panel provider registration location**: no panel/provider change; Laravel providers remain under `apps/platform/bootstrap/providers.php`.
- **Global search posture**: unchanged; no Filament Resource changed.
- **Destructive/high-impact action posture**: none.
- **Asset strategy**: no assets; no new `filament:assets` requirement.
- **Testing plan**: no pages/widgets/relation managers/actions; static artifact validation only.
- **Deployment impact**: none - no env vars, migrations, queues, scheduler, storage, assets, provider credentials, or provider permissions.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: no runtime touch; planning context for future source/evidence systems.
- **Systems touched**: Spec artifacts only. Read-only source evidence includes `ResourceTypeRegistry`, `SupportedScopeResolver`, `CoverageSourceContractResolver`, `CoverageIdentityStrategyRegistry`, `ExchangeTeamsComparablePayloadNormalizer`, `ExchangeTeamsCoverageComparator`, `ExchangeTeamsRenderableSummaryBuilder`, `ClaimGuard`, and related Spec 419/420/422/426/427 reports/tests.
- **Shared abstractions reused**: none now. Future runtime specs must reuse existing Coverage v2 paths unless they record a bounded exception.
- **New abstraction introduced? why?**: none in runtime. Documentation-only classifications exist to prevent unsafe implementation drift.
- **Why the existing abstraction was sufficient or insufficient**: Existing Coverage v2 can block missing source contracts and protect claims, but it cannot choose Exchange/Teams adapter source surfaces without catalog work.
- **Bounded deviation / spread control**: Static catalog artifacts may introduce documentation-only source/adapter/status vocabulary. Later runtime work must re-justify any promotion into code.

## 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.

Future provider capture, PowerShell execution, or remote work must create/reuse OperationRun through the central service and start UX contract in a separate spec.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes, documentation-only classification.
- **Provider-owned seams**: Exchange Online PowerShell, Teams PowerShell, Exchange Online Admin API, Microsoft Graph resource availability, Security & Compliance/Purview PowerShell, SharePoint/OneDrive/PnP boundary, Microsoft permission/RBAC names, provider-native identifiers, response shapes.
- **Platform-core seams**: Coverage v2 source-contract state, evidence truth, identity truth, claim guard, workspace/managed-environment/provider-connection ownership, no-customer-claim rules.
- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider connection, target type, source surface, adapter pattern, evidence state, claim boundary, blocker, cohort.
- **Retained provider-specific semantics and why**: Microsoft source names are necessary for catalog accuracy but remain inside Spec Kit documentation until a later implementation spec.
- **Bounded extraction or follow-up path**: document-in-feature. Spec 430 is the first runtime follow-up and must not implement the whole catalog.

## Constitution Check

- Inventory-first: catalog only; no inventory, snapshot, backup, or evidence truth changes.
- Read/write separation: no write/change behavior.
- Graph contract path: no Graph calls and no graph contract additions; later Graph work must use `GraphClientInterface` and `config/graph_contracts.php`.
- Deterministic capabilities: no capability resolver changes.
- RBAC-UX: no route, policy, action, global search, or authorization change.
- Workspace isolation: no runtime query or ownership change.
- Tenant isolation: no tenant-plane read/write change.
- Run observability: no OperationRun; future remote/provider work must use OperationRun.
- OperationRun start UX: N/A.
- Ops-UX 3-surface feedback: N/A.
- OperationRun lifecycle: no status/outcome transition.
- Summary counts: no new counts.
- Data minimization: catalog must not store secrets, tokens, raw credential payloads, mail content, Teams content, or customer data.
- Test governance: docs/catalog-only validation; no runtime test family.
- Proportionality: documentation taxonomy is justified by blocked Exchange/Teams sequence and no runtime machinery is introduced.
- No premature abstraction: no runtime abstraction.
- Persisted truth: no new persistence.
- Behavioral state: no runtime status family.
- UI semantics: no UI.
- Shared pattern first: future runtime must reuse Coverage v2, OperationRun, Claim Guard, and product-surface paths.
- Provider boundary: provider-specific source details stay documentation-only and provider-owned.
- V1 explicitness / few layers: catalog before adapter; no framework.
- Spec discipline / bloat check: broad source-surface ambiguity is grouped into one coherent catalog spec rather than multiple micro-specs.
- Badge semantics: no badge changes.
- Filament-native UI: N/A.
- UI/Productization coverage: no UI surface impact is recorded.

## Test Governance Check

- **Test purpose / classification by changed surface**: N/A - no runtime behavior changed.
- **Affected validation lanes**: docs/spec/catalog static checks only.
- **Why this lane mix is the narrowest sufficient proof**: The implementation changes only Spec Kit documentation artifacts.
- **Narrowest proving command(s)**:
  - `git status --short`
  - `git diff --check`
  - `git diff --name-only`
  - optional if JSON catalog is added: `python3 -m json.tool specs/429-exchange-teams-source-surface-catalog-adapter-strategy/catalog/exchange-teams-target-types.json > /dev/null`
- **Fixture / helper / factory / seed / context cost risks**: none.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: N/A.
- **Closing validation and reviewer handoff**: Confirm catalog artifacts exist, matrix fields are complete, and no files outside Spec 429 changed.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: Did runtime code change? Did any provider call/adapter/evidence/OperationRun/UI/customer claim appear? Did catalog terms become runtime values?
- **Escalation path**: reject-or-split if runtime adapter work is attempted.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage: `N/A - catalog/strategy only, no rendered UI surface changed`.
- **Why no dedicated follow-up spec is needed**: This spec is the dedicated catalog/strategy follow-up. Runtime adapter implementation is separately deferred to Spec 430.

## Project Structure

### Documentation (this feature)

```text
specs/429-exchange-teams-source-surface-catalog-adapter-strategy/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
|-- catalog/
|   |-- exchange-source-surface-catalog.md
|   |-- teams-source-surface-catalog.md
|   |-- exchange-teams-target-type-matrix.md
|   |-- adapter-strategy.md
|   `-- cohort-plan.md
`-- implementation-report.md
```

### Source Code

No source code changes are planned or allowed.

Relevant read-only evidence paths:

```text
docs/product/spec-candidates.md
docs/product/roadmap.md
specs/420-m365-generic-evidence-coverage-pack/
specs/422-exchange-teams-comparable-renderable-pack/
specs/426-exchange-teams-core-evidence-identity-readiness/
specs/427-exchange-teams-verified-source-contract-enablement/
specs/428-exchange-teams-content-backed-evidence-promotion/
apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php
apps/platform/app/Services/TenantConfiguration/SupportedScopeResolver.php
apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php
apps/platform/app/Services/TenantConfiguration/CoverageIdentityStrategyRegistry.php
apps/platform/app/Services/TenantConfiguration/ExchangeTeamsComparablePayloadNormalizer.php
apps/platform/app/Services/TenantConfiguration/ExchangeTeamsCoverageComparator.php
apps/platform/app/Services/TenantConfiguration/ExchangeTeamsRenderableSummaryBuilder.php
```

**Structure Decision**: Spec-only/catalog package. Implementation must stay under the Spec 429 directory.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
| --- | --- | --- |
| Documentation-only source/adapter taxonomy | Prevents unsafe one-off Exchange/Teams adapter work after Specs 427/428 blocked the narrow path | Four direct adapters would repeat the endpoint-guessing and false-readiness risk |

## Proportionality Review

- **Current operator problem**: Future release reviewers need a credible Exchange/Teams adapter map before evidence or customer claims can progress.
- **Existing structure is insufficient because**: Existing Coverage v2 structures block missing contracts but do not decide source surfaces, adapter patterns, or implementation cohorts.
- **Narrowest correct implementation**: Static catalog and strategy documents, no runtime code.
- **Ownership cost created**: Catalog maintenance and later specs must keep cohort/source decisions in sync.
- **Alternative intentionally rejected**: One-off adapters, guessed Graph endpoints, broad provider framework, and customer-readiness claims.
- **Release truth**: Current-release prerequisite truth.

## Implementation Phases

### Phase 0 - Preflight

- Capture branch, HEAD, dirty state, selected candidate, completed-spec guardrail, and Spec 428 non-blocking assumption.
- Confirm no runtime/UI/evidence/customer-claim work is planned.

### Phase 1 - Source Reference Collection

- Collect official Microsoft Learn references for Exchange Online PowerShell, Exchange Online Admin API, Teams PowerShell, Graph Teams overview, Teams app/meeting/messaging/external-access policies, Exchange mail-flow/domains/remote domains, and Security & Compliance boundaries.
- Collect repo source references from Coverage v2 services and completed specs.

### Phase 2 - Exchange Catalog

- Catalog Exchange mail flow/transport, domains/connectors, organization configuration, sharing/relationship configuration, protection/hygiene, recipient/mailbox, and Purview/Security & Compliance boundary families.
- Classify candidate target types by source surface, adapter pattern, risk, value, and blocker.

### Phase 3 - Teams Catalog

- Catalog Teams app governance, meetings/events, messaging/channels, calling/voice, external/guest access, and files/storage/integration boundary families.
- Classify candidate target types by source surface, adapter pattern, risk, value, and blocker.

### Phase 4 - Target Type Matrix And Cohort Plan

- Normalize target type names.
- Complete required matrix fields.
- Select Cohort 1, Cohort 2, deferred, unsupported, and unknown groups.

### Phase 5 - Adapter Strategy

- Define Graph-native, Exchange Admin API, Exchange PowerShell, Teams PowerShell, Security & Compliance, unsupported, and unknown paths.
- Identify the first Spec 430 implementation slice and review/test constraints.

### Phase 6 - Validation And Report

- Validate no runtime diff.
- Create implementation report with required matrices and no-claim/no-promotion proof.