TenantAtlas/specs/436-exchange-content-backed-evidence-promotion-slice-1/plan.md

Implementation Plan: Exchange Content-Backed Evidence Promotion Slice 1

Branch: feat/436-exchange-content-backed-evidence-promotion-slice-1 | Date: 2026-07-08 | Spec: spec.md Input: Feature specification from specs/436-exchange-content-backed-evidence-promotion-slice-1/spec.md

Summary

Promote exactly transportRule, remoteDomain, and inboundConnector to append-only internal content-backed Coverage v2 evidence through the Exchange PowerShell capture adapter. The implementation must replace the current generic/comparable normalizer write path with Spec 435 structured envelopes, target-specific normalizers, and hash builder; preserve Spec 434 identity/content-only guards and empty-collection policy; consume Spec 433 readiness, Spec 432 runner boundary, and Spec 430 command contracts; and add no UI, migration, trigger, compare/render, certification, restore, or customer claim.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12, Filament 5, Livewire 4 Primary Dependencies: Existing Laravel services, Coverage v2 models, Pest 4, Exchange PowerShell support classes Storage: PostgreSQL through existing tenant_configuration_resources and tenant_configuration_resource_evidence; no migration planned Testing: Pest 4 Unit and Feature tests Validation Lanes: fast-feedback/confidence; PostgreSQL lane only if implementation unexpectedly touches migration/schema behavior and the spec is amended Target Platform: Laravel platform app under apps/platform Project Type: web monolith backend-only slice Performance Goals: deterministic per-item normalization/hash without external calls during tests; no UI render path or browser cost Constraints: no raw stdout/stderr evidence, no raw payload outside evidence storage, no generic/comparable normalizer promotion path, no evidence on unsafe identity or failed gates Scale/Scope: exactly three Exchange resource types and fake-runner test coverage

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-only.
• Native vs custom classification summary: N/A.
• Shared-family relevance: backend evidence/OperationRun only; no rendered shared interaction family.
• State layers in scope: backend capture/evidence only.
• Audience modes in scope: N/A.
• Decision/diagnostic/raw hierarchy plan: raw provider payload remains evidence-storage-only; diagnostics stay internal; no product layer.
• Raw/support gating plan: raw payload stored only in evidence storage; no UI support/raw surface.
• One-primary-action / duplicate-truth control: N/A.
• Handling modes by drift class or surface: hard-stop-candidate for any UI, route, trigger, report, Review Pack, PDF, or customer output.
• Repository-signal treatment: review-mandatory for any guarded path change; hard-stop for UI/migration/trigger scope.
• Special surface test profiles: N/A.
• Required tests or manual smoke: browser N/A - no rendered UI surface changed.
• Exception path and spread control: none.
• Active feature PR close-out entry: N/A - no rendered UI surface changed.
• UI/Productization coverage decision: No UI surface impact.
• Coverage artifacts to update: none.
• No-impact rationale: backend-only evidence promotion through existing tables and services.
• Navigation / Filament provider-panel handling: checked no-impact; no provider registration/global search/asset changes.
• Screenshot or page-report need: no.

Product Surface Contract Plan

• Product Surface Contract reference: docs/product/standards/product-surface-contract.md.
• No-legacy posture: canonical replacement; no compatibility exception.
• Page archetype and surface budget plan: N/A.
• Technical Annex and deep-link demotion plan: OperationRun details, raw evidence payloads, IDs, source keys, payloads, normalized payloads, and hashes stay internal and are not rendered.
• Canonical status vocabulary plan: N/A for UI.
• 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/436-exchange-content-backed-evidence-promotion-slice-1/implementation-report.md.

Filament / Livewire / Deployment Posture

• Livewire v4 compliance: unchanged; no Livewire runtime code planned.
• Panel provider registration location: no panel change; Laravel provider registration remains apps/platform/bootstrap/providers.php.
• Global search posture: no Resource/global search change.
• Destructive/high-impact action posture: none; no UI action or start surface added.
• Asset strategy: no assets; filament:assets is not newly required.
• Testing plan: Unit/Feature for adapter wiring, target normalizers, hash determinism, identity blocking, append-only evidence, OperationRun safety, redaction, no-promotion, no-surface, and regressions.
• Deployment impact: no env vars, migrations, queues, scheduler, storage, assets, or Dokploy runtime changes planned.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes, backend evidence/capture only.
• Systems touched: Exchange PowerShell adapter/eligibility/identity/content-only guard, structured output envelope, target normalizers, hash builder, Coverage v2 writer/upserter, OperationRun safe context, provider readiness.
• Shared abstractions reused: tenant_configuration.capture, OperationSummaryKeys, ExchangePowerShellStructuredOutputEnvelope, ExchangePowerShellEvidenceNormalizer, ExchangePowerShellHashInputBuilder, CanonicalIdentityResolver, CoverageResourceUpserter, CoverageEvidenceWriter.
• New abstraction introduced? why?: none planned. Use existing Spec 434/435 classes. If a helper is needed, keep it private/narrow and document in the report.
• Why the existing abstraction was sufficient or insufficient: Coverage v2 storage and Spec 434/435 services are sufficient. The current adapter normalizer path is insufficient because it still uses GenericPayloadNormalizer and ExchangeTeamsComparablePayloadNormalizer.
• Bounded deviation / spread control: Exchange-specific normalization stays provider-owned and does not alter platform-core evidence table semantics.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: no rendered UX; internal OperationRun ownership/context only.
• Central contract reused: existing tenant_configuration.capture lifecycle conventions.
• Delegated UX behaviors: N/A.
• Surface-owned behavior kept local: none.
• Queued DB-notification policy: N/A.
• Terminal notification path: unchanged.
• Exception path: none; adding a new operation/start UX requires spec amendment.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes.
• Provider-owned seams: Exchange PowerShell command contracts, source surface, structured item shape, target-specific normalizers, protected field handling.
• Platform-core seams: Coverage v2 evidence/resource storage, OperationRun truth, workspace/managed-environment/provider scope, identity hard-stop, redaction/no-customer-output, no-promotion posture.
• Neutral platform terms / contracts preserved: provider connection, managed environment, evidence, capture outcome, content-backed, operation run, canonical identity, payload hash.
• Retained provider-specific semantics and why: transportRule, remoteDomain, inboundConnector, and Exchange PowerShell contract names are required for this bounded first Exchange slice.
• Bounded extraction or follow-up path: Spec 437 can promote comparable/renderable only after Spec 436 passes.

Constitution Check

Principle	Plan Result	Notes
Inventory-first / evidence truth	PASS	Writes existing Coverage v2 evidence as internal source-backed proof; no customer/product truth.
Read/write separation	PASS	Backend evidence append only through trusted flow; no destructive or restore/apply action.
Graph contract path	PASS	Exchange PowerShell path must not route through Graph gateway or fake Graph endpoints.
Deterministic capabilities	PASS	Spec 433 readiness and provider capability stay gate truth.
RBAC / workspace isolation	PASS	Existing scope fields and provider connection scope required; no route/action change.
OperationRun truth	PASS	tenant_configuration.capture is evidence owner; invocation operation remains runner truth.
Summary counts	PASS	Use allowed keys or amend spec before adding keys.
Data minimization	PASS	Raw structured provider item only in evidence storage; no raw stdout/stderr/transcripts.
Test governance	PASS	Unit/Feature focused tests; Browser N/A.
Proportionality	PASS	No new table, OperationRun type, UI framework, or status family planned.
Provider boundary	PASS	Exchange semantics remain provider-owned.
Product Surface	PASS	N/A - no rendered UI surface changed.

Test Governance Check

• Test purpose / classification by changed surface: Unit for normalizer/hash/identity blockers; Feature for DB-backed evidence append, OperationRun safety, append-only/latest-pointer, redaction, no-surface guard.
• Affected validation lane(s): fast-feedback/confidence. Browser N/A.
• Fixture/helper/factory/seed/context cost: reuse existing Spec 430-435 fake runner/readiness fixtures; keep provider/workspace setup explicit.
• Heavy-governance or browser family impact: none.
• Narrowest reviewer command: focused Spec436 tests plus listed regression filters.
• Budget/baseline/trend follow-up: none expected.
• Review outcome target: document-in-feature for any bounded non-blocking conditions; reject-or-split for UI/migration/trigger/target expansion/no-promotion violations.

Technical Approach

1. Re-check Spec 435 PASS/merge-ready state and current branch/dirty state.
2. Add failing focused tests for adapter wiring, target-specific normalizer usage, hash determinism, identity blocking, append-only evidence, raw payload location, OperationRun sanitization, no-promotion, no-surface, and no-tenant-id behavior.
3. Update ExchangePowerShellEvidenceCaptureAdapter so non-empty eligible Exchange captures build a Spec 435 envelope from runner output, evaluate target-specific normalizer readiness, use normalized target payloads and ExchangePowerShellHashInputBuilder hash output, and append evidence with content-only cap.
4. Remove or bypass GenericPayloadNormalizer and ExchangeTeamsComparablePayloadNormalizer for Exchange evidence promotion; preserve generic Graph capture path.
5. Keep Spec 434 eligibility, identity, content-only, and empty-collection behavior intact.
6. Ensure OperationRun context/summary remains sanitized and uses allowed summary keys.
7. Run focused tests, regressions, Pint, git diff --check, and complete the implementation report.

Domain / Model Implications

• No new models, migrations, tables, columns, enum/status family, OperationRun type, UI state, or customer output artifact.
• Existing TenantConfigurationResource latest pointer update remains the source for latest evidence state.
• Existing TenantConfigurationResourceEvidence stores raw structured provider item, normalized payload, hash, source metadata, operation, scope, and content-backed coverage state.

Data / Migration Plan

No migration. Runtime must use existing Coverage v2 tables. If a schema gap is discovered, implementation must stop and amend spec/plan/tasks before proceeding.

Security / RBAC / Redaction Plan

• Reuse trusted backend flow and provider/capture authorization.
• Preserve workspace, managed environment, and provider connection scope checks.
• Require combined Exchange readiness before evidence append.
• Keep protected Exchange config out of OperationRun context/logs/summaries/customer output.
• Store raw structured provider item only in evidence storage.
• Add sentinel tests for credential, token, stdout/stderr, transcript, normalizer preview, hash preview, and protected connector/config fields.

Implementation Phases

Phase 0 - Preflight

• Capture branch, HEAD, and git status --short.
• Confirm Spec 435 PASS/merge-ready and prerequisite proof from Specs 430-435.
• Confirm no UI/routes/jobs/schedules/listeners/migration/tenant_id scope.

Phase 1 - Adapter Integration Update

• Wire Exchange adapter to Spec 435 structured envelope.
• Wire Exchange adapter to Spec 435 target normalizers.
• Wire Exchange adapter to Spec 435 hash input builder.
• Remove/avoid generic/Teams comparable normalizer path for Exchange evidence.
• Preserve Graph/generic capture path.

Phase 2 - Evidence Persistence

• Use Coverage v2 evidence writer.
• Persist raw structured provider payload in evidence storage only.
• Persist normalized target payload.
• Persist payload hash.
• Link OperationRun.
• Preserve append-only behavior.
• Update latest pointer according to repo pattern.

Phase 3 - Target Evidence Promotion

• Implement transportRule capture.
• Implement remoteDomain capture with stable identity only.
• Implement inboundConnector capture with stable identity/redaction only.
• Keep blocked states explicit.

Phase 4 - Blocking / Empty / Failure Semantics

• Block readiness failures.
• Block unsupported provider capability.
• Block output failures.
• Block unsafe identity.
• Preserve empty collection no-evidence policy.
• Add exact blocker outcomes and prove persisted evidence capture_outcome values stay within existing repo-allowed values.

Phase 5 - Redaction / No-Promotion

• Prove OperationRun context sanitized.
• Prove raw payload only in evidence storage.
• Prove content-backed-only coverage.
• Prove no UI/jobs/schedules/listeners/customer output.

Phase 6 - Regression / Report

• Run focused tests and regressions.
• Run Pint.
• Run git diff --check.
• Complete implementation report.

Rollout Considerations

• Staging/production deployment impact: none beyond code/test deployment.
• No env vars, migrations, queues, scheduler, storage, asset build, reverse proxy, or Dokploy change planned.
• Rollback is reverting the adapter/test changes and the Spec 436 artifacts.

Stop Conditions

Stop and amend/split if implementation needs:

• UI, routes, Filament, Livewire, assets, global search, provider registration, reports, Review Packs, customer output, jobs, schedules, listeners, console commands, or browser proof.
• migration/schema changes, new evidence table, tenant_id, new OperationRun type, or new persisted outcome/summary key.
• target expansion beyond the three included types.
• compare/render/certification/restore/customer claim.
• Graph gateway fallback or fake Graph endpoints.
• durable collection-level empty proof.