TenantAtlas/specs/437-exchange-comparable-promotion-slice-1/implementation-report.md

# Implementation Report: Spec 437 - Exchange Comparable Promotion Slice 1

Date: 2026-07-09

## Result

- **Status**: PASS.
- **Active spec**: `specs/437-exchange-comparable-promotion-slice-1/`.
- **Branch**: `feat/437-exchange-comparable-promotion-slice-1`.
- **HEAD at implementation start/end**: `30a6733f Spec 436: Exchange content-backed evidence promotion (#503)`.
- **Implementation/fix iterations**: 1 implementation pass, 2 review-fix passes.

## Candidate Gate Result

PASS. Spec 437 is a directly provided, prepared comparable-only backend slice for exactly `transportRule`, `remoteDomain`, and `inboundConnector`. Spec 436 is present at current base and records PASS for the required content-backed evidence prerequisite. The implementation now fails closed unless explicit content-backed/captured provenance and a valid SHA-256 payload hash are supplied.

## Branch And Dirty State

- Branch at implementation start: `feat/437-exchange-comparable-promotion-slice-1`.
- HEAD at implementation start: `30a6733f Spec 436: Exchange content-backed evidence promotion (#503)`.
- Initial dirty state: untracked active Spec 437 package only.
- Final dirty state: intended Spec 437 runtime/test/spec files.

## Files Changed

- `apps/platform/app/Services/TenantConfiguration/ExchangePowerShellComparablePayloadBuilder.php`
- `apps/platform/tests/Unit/Support/TenantConfiguration/Spec437ExchangeComparablePayloadBuilderTest.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec437ExchangeComparablePromotionFeatureTest.php`
- `specs/437-exchange-comparable-promotion-slice-1/checklists/requirements.md`
- `specs/437-exchange-comparable-promotion-slice-1/implementation-report.md`
- `specs/437-exchange-comparable-promotion-slice-1/plan.md`
- `specs/437-exchange-comparable-promotion-slice-1/spec.md`
- `specs/437-exchange-comparable-promotion-slice-1/tasks.md`

Completed historical specs were used as read-only context and were not rewritten.

## Spec 436 Prerequisite Proof

- Current base HEAD is `30a6733f Spec 436: Exchange content-backed evidence promotion (#503)`.
- `specs/436-exchange-content-backed-evidence-promotion-slice-1/implementation-report.md` records PASS and merge-ready.
- Spec 436 records append-only content-backed evidence outcomes for `transportRule`, `remoteDomain`, and `inboundConnector`.
- Spec 436 records no compare/render/certification/restore/customer/UI/job/schedule/listener/migration promotion.
- Spec 436 records `tenant_configuration.capture` as evidence provenance and Exchange PowerShell invocation as runner truth only.

## Target Comparable Outcome Matrix

| Type | Content-backed prerequisite | Comparable? | Renderable? | Blocker |
|---|---|---|---|---|
| `transportRule` | Yes | Yes | No | none |
| `remoteDomain` | Yes | Yes when source identity is stable and not domain/display-only | No | `unsafe_identity` for domain-only/display-only identity |
| `inboundConnector` | Yes | Yes | No | none |

When evidence, content-backed/captured provenance, or normalized identity is missing, unsafe, or unsupported, the builder returns no comparable artifact and an explicit blocker.

## Safety Matrix

| Area | State |
|---|---|
| Raw payload as input | No |
| Normalized payload as input | Yes |
| OperationRun context as input | No |
| Protected exact values exposed | No |
| Persisted coverage-level promotion | No |
| Renderable | No |
| Certification | No |
| Restore | No |
| Customer output | No |
| UI | No |
| Jobs/Schedules/Listeners | No |
| Migration | No |

## Comparable Input Proof

`ExchangePowerShellComparablePayloadBuilder::build()` accepts:

- `resourceType`
- Spec 436 `normalizedPayload`
- required `payloadHash` as valid SHA-256 non-material provenance
- required content-backed/captured provenance metadata: `evidence_state`, `coverage_level`, and `capture_outcome`

It does not accept raw provider payload, stdout, stderr, transcript, OperationRun context, logs, UI read models, report output, or Review Pack output as material input. Stable material identity is derived only from `normalized_payload.source_identity`; external metadata is ignored for material identity and compare fields. Missing or malformed `payloadHash`, non-content-backed evidence state, non-content-backed coverage level, or non-captured outcome returns a blocker and no comparable payload.

## Comparable Output Proof

Builder output is a machine-readable derived result:

- `comparable`
- optional `blocker`
- `payload`
- `comparable_hash`

Comparable payloads include:

- workload `exchange`
- resource type
- comparable payload shape version
- `compare_input = normalized_payload_only`
- stable identity field plus scoped app-keyed HMAC-derived source key
- target-safe material fields after value-policy validation
- redacted presence/count/state structures
- safe source/provenance metadata

Comparable payloads exclude raw provider objects, raw policy text, raw protected values, exact identity values, unsalted identity hashes, customer prose, risk verdicts, restore instructions, and certification labels.

## Evidence Immutability Proof

`Spec437ExchangeComparablePromotionFeatureTest` asserts derived comparable output does not mutate:

- `raw_payload`
- `normalized_payload`
- `payload_hash`
- `operation_run_id`
- `source_metadata`
- persisted `coverage_level`
- `TenantConfigurationResource.latest_*`
- `TenantConfigurationResourceType.default_coverage_level`
- OperationRun type/context

No resource, evidence, resource type, or OperationRun write path is used by the builder.

## Redaction Proof

Focused unit tests prove:

- `transportRule` conditions/actions/exceptions use redacted markers/counts and do not expose raw sender domains, subject words, header values, or exception email values.
- `remoteDomain` protected domain/settings values use redacted markers/counts and domain-only/display-only identity is blocked case/separator-insensitively.
- `inboundConnector` routing/TLS/protected config uses redacted markers/counts and does not expose raw IPs, hosts, smart hosts, certificate names, comments, or routing metadata.
- Credential material, tokens, authorization headers, cookies, raw stdout/stderr, transcript, and OperationRun context do not appear in comparable output.
- Unexpected exact protected/sensitive values return `unsafe_exact_value` and no comparable payload.
- Malformed exact values on otherwise allowlisted safe fields, such as string secrets in boolean fields or unknown enum values, return `unsafe_exact_value` and no comparable payload.

## Determinism Proof

Focused unit tests prove:

- same normalized material produces the same comparable hash
- material safe changes change the comparable hash
- volatile-only input changes do not change the comparable hash
- redacted exact-value changes with unchanged safe marker/count do not change the comparable hash
- redacted count changes change the comparable hash
- hash behavior is covered for `transportRule`, `remoteDomain`, and `inboundConnector`
- non-material Evidence/OperationRun provenance is excluded from `comparable_hash`
- compare-shape/source contract metadata that changes normalization semantics remains hash-relevant, following Spec 435 hash-input precedent
- identity HMAC values are deterministic for a deployment key without exposing exact identity values

Provider ordering stability is inherited from Spec 436 normalized payload ordering and preserved by builder canonical sorting.

## Delta Proof

N/A. No comparator was added because repository architecture did not require comparison output for this comparable-payload-only slice. Tasks T035-T037 are completed as N/A with explicit notes in `tasks.md`.

## No Raw Payload Proof

Tests inject raw-provider, raw stdout, raw stderr, transcript, OperationRun context, credential/token-like, exact protected/sensitive, and metadata override values into non-material positions and assert none are emitted in comparable output. Static feature tests also assert the builder does not use `GenericPayloadNormalizer`, `ExchangeTeamsComparablePayloadNormalizer`, `CoverageEvidenceWriter`, or direct evidence model writes.

## No OperationRun Context Input Proof

- No new OperationRun type was added.
- `OperationRunType::TenantConfigurationCapture` remains the evidence provenance type.
- `OperationRunType::TenantConfigurationExchangePowerShellInvocation` remains runner truth only.
- OperationRun context is not builder input and is not stored with comparable payloads or deltas.

## No Persisted Coverage-Level Promotion Proof

Comparable output is derived service output only. Feature tests assert evidence remains `CoverageLevel::ContentBacked`, resource latest state remains unchanged, and resource type defaults remain unchanged. No Exchange-specific compare table or migration was added.

## No Renderable / Certification / Restore / Customer Proof

No render model, certification state, restore/apply state, customer-ready/customer-claimable state, customer-safe summary, report, Review Pack, PDF, customer route, or customer badge was added.

## No UI / Route / Trigger Proof

Static tests assert no new Exchange comparable Filament, Livewire, route, Blade view, job, console command, migration, or OperationRun type exists. Browser proof is `N/A - no rendered UI surface changed`.

## No Tenant ID / Migration Proof

Static tests assert:

- no `tenant_id` column exists on `tenant_configuration_resources`
- no `tenant_id` column exists on `tenant_configuration_resource_evidence`
- no Exchange comparable migration was added
- no Exchange-specific compare table or mini-platform was added

## Product Surface Close-Out

- **Runtime UI files changed**: no.
- **UI impact**: N/A - no rendered UI surface changed.
- **Product Surface exceptions**: none.
- **Browser proof**: N/A - no rendered UI surface changed.
- **Human Product Sanity**: N/A - no product surface changed.
- **Visible complexity outcome**: neutral.
- **No-legacy confirmation**: no aliases, fallback readers, hidden routes, duplicate UI, old labels, compatibility shim, dual write, or fallback reader.
- **Completed-spec rewrite assertion**: completed historical specs were not rewritten.
- **Livewire v4 compliance**: unchanged; no Livewire code changed.
- **Provider registration location**: unchanged; Laravel panel providers remain under `apps/platform/bootstrap/providers.php`.
- **Global search posture**: unchanged; no Filament Resource changed.
- **Destructive/high-impact action posture**: none; no UI action, runtime trigger, restore, apply, or destructive/high-impact action was added.
- **Asset strategy**: no assets; no `filament:assets` requirement introduced.
- **Deployment impact**: no env vars, migrations, queues, scheduler, storage, assets, routes, jobs, listeners, commands, or Dokploy runtime behavior changes.

## Validation

- `php -l apps/platform/app/Services/TenantConfiguration/ExchangePowerShellComparablePayloadBuilder.php`
  - Result: PASS.
- `php -l apps/platform/tests/Unit/Support/TenantConfiguration/Spec437ExchangeComparablePayloadBuilderTest.php`
  - Result: PASS.
- `php -l apps/platform/tests/Feature/TenantConfiguration/Spec437ExchangeComparablePromotionFeatureTest.php`
  - Result: PASS.
- `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec437 --compact`
  - Result: failed before completion with Symfony Process signal 9. Non-Docker fallback used.
- `cd apps/platform && php artisan test --filter=Spec437 --compact`
  - Result: PASS, 34 tests / 225 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --filter='Spec436|Spec435|Spec434|Spec433|Spec432|Spec431|Spec430' --compact`
  - Result: failed before completion with Symfony Process signal 9. Non-Docker fallback used.
- `cd apps/platform && php artisan test --filter='Spec436|Spec435|Spec434|Spec433|Spec432|Spec431|Spec430' --compact`
  - Result: PASS, 302 tests / 2196 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --filter='Spec421|Spec425|Spec415|Spec417|Spec419|Spec420|Spec426|Spec427|ProviderCapabilityRegistry' --compact`
  - Result: failed before completion with Symfony Process signal 9. Non-Docker fallback used.
- `cd apps/platform && php artisan test --filter='Spec421|Spec425|Spec415|Spec417|Spec419|Spec420|Spec426|Spec427|ProviderCapabilityRegistry' --compact`
  - Result: PASS, 282 passed / 8 skipped / 2488 assertions. Skips are existing PostgreSQL-specific skips in the SQLite/default fallback lane.
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - Result: PASS.
- `git diff --check`
  - Result: PASS.
- `git status --short`
  - Result: intended Spec 437 runtime/test/spec files.

## Post-Implementation Analysis

Iteration 1 found review findings around fail-open exact protected values, missing content-backed provenance enforcement, case-sensitive remoteDomain unsafe identity handling, unsalted identity hashing, incomplete target hash coverage, and incomplete spec/report consistency.

Iteration 2 resolved the confirmed findings by adding content-backed/captured provenance blockers, scoped app-keyed HMAC identity anchors, case/separator-insensitive unsafe remoteDomain identity checks, fail-closed `unsafe_exact_value` handling, expanded target hash/security tests, and synchronized Spec Kit artifacts.

Iteration 3 resolved the follow-up review finding that exact safe fields were field-allowlisted but not value-policy-validated. The builder now validates exact safe values by field policy, blocks malformed allowlisted values, requires a valid SHA-256 payload hash, and records the strategic hash decision: run/evidence provenance is excluded from `comparable_hash`, while source/shape/normalizer metadata remains hash-relevant because it changes compare semantics under the Spec 435 precedent.

Confirmed in-scope findings after second fix pass: none.

Residual risks: none for this slice. Renderable output, certified compare packs, customer output, reports, Review Packs, PDFs, Teams slices, and restore/apply remain deferred to separate specs.

## Deferred Work

- Spec 438 - Exchange Internal Render Model Slice 1.
- Teams PowerShell adapter and evidence slices.
- Exchange/Teams certified compare pack.
- M365 customer output and claim guard.
- Restore/apply.
- Reports, Review Packs, PDFs, and customer-facing output.

## Merge Readiness Gate

Status: PASS.

Merge-ready: yes.

Manual review prompt:

```markdown
Du bist ein Senior Staff Software Architect und Enterprise SaaS Reviewer.

Führe eine finale manuelle Review der implementierten Spec `437-exchange-comparable-promotion-slice-1` streng repo-basiert durch.

Ziel:
Pruefe, ob die Implementierung nach dem Agenten-Loop wirklich merge-ready ist.

Wichtig:
- Keine Implementierung.
- Keine Codeaenderungen.
- Keine Scope-Erweiterung.
- Pruefe gegen spec.md, plan.md, tasks.md und constitution.md.
- Pruefe die geaenderten Dateien, Tests, Browser-Smoke-Test-Ergebnis, RBAC, Workspace-/Tenant-Isolation, Auditability, UX und OperationRun-Semantik, soweit relevant.
- Benenne nur konkrete Findings mit Repo-Beleg.
- Gib am Ende eine klare Entscheidung: Merge-ready, merge-ready with notes, oder not merge-ready.
```