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)

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:

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.