ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
bcec737cd4
TenantAtlas/specs/437-exchange-comparable-promotion-slice-1/plan.md
Ahmed Darrazi bcec737cd4 spec: add exchange comparable promotion slice 1
2026-07-09 21:10:02 +02:00

17 KiB
Raw Blame History

Implementation Plan: Spec 437 - Exchange Comparable Promotion Slice 1

Branch: feat/437-exchange-comparable-promotion-slice-1 | Date: 2026-07-09 | Spec: spec.md Input: Feature specification from specs/437-exchange-comparable-promotion-slice-1/spec.md

Summary

Derive deterministic machine-comparable payloads for exactly transportRule, remoteDomain, and inboundConnector from immutable Spec 436 Exchange PowerShell content-backed evidence. The builder must consume only normalized_payload as material input, require a valid SHA-256 payload_hash plus content-backed/captured provenance gates, preserve existing evidence rows, keep persisted coverage state unchanged, represent protected values through redacted presence/count/safe-state semantics, emit stable identity as a scoped app-keyed HMAC anchor, enforce value policies for exact safe fields, keep compare-shape/source contract metadata hash-relevant, and add no renderable output, certification, restore, UI, customer output, jobs, schedules, listeners, migrations, tenant_id, new OperationRun type, or Exchange-specific compare table.

Technical Context

Language/Version: PHP 8.4 / Laravel 12 Primary Dependencies: Laravel, Pest 4, existing TenantConfiguration Coverage v2 services Storage: Existing PostgreSQL-backed Coverage v2 tables are read only for this slice; no migration, comparable artifact persistence, or persisted coverage-level promotion planned Testing: Pest unit and feature tests Validation Lanes: fast-feedback and confidence; browser N/A Target Platform: Laravel Sail locally, Dokploy/container deployment for staging/production Project Type: Laravel monolith under apps/platform Performance Goals: deterministic in-memory comparable derivation with no remote/provider calls Constraints: normalized-payload-only material input, valid SHA-256 payload hash and content-backed/captured provenance required, evidence immutability, no persisted coverage_level = comparable, protected config redaction, exact safe field value policies, scoped HMAC identity anchors, no rendered surface Scale/Scope: exactly three Exchange PowerShell resource types

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 Coverage v2 evidence/compare semantics only.
  • State layers in scope: none.
  • Audience modes in scope: N/A.
  • Decision/diagnostic/raw hierarchy plan: N/A at UI layer; raw/provider/protected values must not enter comparable output.
  • Raw/support gating plan: raw evidence remains internal storage only; comparable output contains no raw/protected exact values and does not update persisted coverage/readiness state.
  • One-primary-action / duplicate-truth control: N/A.
  • Handling modes by drift class or surface: hard stop if any rendered surface, route, action, report, download, or customer output appears.
  • Repository-signal treatment: review-mandatory for any accidental UI/read-model/customer/report/trigger file change.
  • 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.
  • UI/Productization coverage decision: No UI surface impact.
  • Coverage artifacts to update: none.
  • No-impact rationale: comparable-only backend service and tests.
  • Navigation / Filament provider-panel handling: no changes.
  • Screenshot or page-report need: no.

Product Surface Contract Plan

  • Product Surface Contract reference: docs/product/standards/product-surface-contract.md checked for no-rendered-surface path.
  • No-legacy posture: canonical bounded addition; no aliases, fallback readers, hidden routes, duplicate UI, old labels, or legacy fixtures.
  • Page archetype and surface budget plan: N/A.
  • Technical Annex and deep-link demotion plan: N/A at runtime; OperationRun/evidence/raw IDs/source keys/payloads are not rendered.
  • Canonical status vocabulary plan: N/A - no product status vocabulary.
  • 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/437-exchange-comparable-promotion-slice-1/implementation-report.md.

Filament / Livewire / Deployment Posture

  • Livewire v4 compliance: unchanged; no Livewire/Filament code changes.
  • Panel provider registration location: unchanged; no panel provider registration change. Laravel panel 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: focused unit and feature tests only; browser N/A.
  • Deployment impact: no env vars, migrations, queues, scheduler, storage, assets, routes, jobs, listeners, or commands.

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes, backend Coverage v2 comparable semantics.
  • Systems touched: existing TenantConfiguration evidence/comparable service layer.
  • Shared abstractions reused: Spec 436 normalized evidence payloads; existing evidence models; existing hash/provenance metadata; app-keyed HMAC identity anchoring.
  • New abstraction introduced? why?: bounded ExchangePowerShellComparablePayloadBuilder because existing generic/ExchangeTeams compare paths do not enforce Spec 436 normalized-payload-only material input, required content-backed provenance, target-specific protected-value safety, exact safe field value policies, scoped identity HMAC anchoring, and no persisted coverage-level promotion for this slice.
  • Why the existing abstraction was sufficient or insufficient: Evidence storage is sufficient. Existing generic/ExchangeTeams comparable normalizers are insufficient and forbidden for this input path.
  • Bounded deviation / spread control: provider-specific builder stays local to Exchange PowerShell evidence for three types; no platform-core status/persistence/UI/customer seam change.

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.

OperationRun implementation posture:

  • Do not add or modify OperationRunType or OperationCatalog.
  • Do not use Exchange PowerShell invocation runs as comparable owners.
  • Do not use OperationRun context as input.
  • Do not store comparable payloads, deltas, raw output, transcripts, protected config, or customer text in OperationRun context/messages/notifications.

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: yes.
  • Provider-owned seams: Exchange PowerShell comparable payload builder and target-specific safe field mapping.
  • Platform-core seams: Coverage v2 evidence remains source truth; ownership remains workspace + managed environment + provider connection.
  • Neutral platform terms / contracts preserved: evidence, comparable payload, normalized payload, resource type, workload, provider connection, managed environment, operation run provenance.
  • Retained provider-specific semantics and why: transportRule, remoteDomain, inboundConnector, Exchange PowerShell source metadata, and protected Exchange config semantics are required for this bounded slice.
  • Bounded extraction or follow-up path: Spec 438 internal render model is separate.

Constitution Check

Principle / Gate Result Notes
Inventory-first / evidence truth PASS Comparable derives only when immutable evidence is content-backed/captured and does not promote persisted evidence coverage level.
Read/write separation PASS No provider writes, restore, apply, destructive action, or UI action.
Graph contract path PASS No Graph or Exchange call in Spec 437.
Deterministic capabilities PASS Comparable derivation is deterministic and testable.
Workspace isolation PASS No new ownership truth; evidence scope remains existing workspace/managed-environment/provider connection.
RBAC-UX PASS No routes/actions/resources/global search.
OperationRun truth PASS No new OperationRun type; context not input.
Evidence anchor contract PASS No fallback-to-latest or OperationRun-as-proof.
Data minimization PASS Raw/protected values excluded from comparable payloads; unexpected exact protected/sensitive values block output.
Product Surface PASS N/A - no rendered UI surface changed.
Customer output PASS No customer output, reports, Review Packs, PDFs, or customer claims.
Provider boundary PASS Provider-specific builder is bounded and local.
Test governance PASS Unit/Feature only; Browser N/A.
Proportionality PASS One bounded helper; no persistence/status/UI framework.
TCM/Coverage v2 cutover guard PASS No legacy adapters, fallback readers, dual writes, tenant_id, or customer claims.

Test Governance Check

  • Test purpose / classification by changed surface: Unit for builder/comparator determinism and redaction; Feature for evidence immutability and no-promotion/no-surface guards.
  • Affected validation lanes: fast-feedback, confidence.
  • Why this lane mix is the narrowest sufficient proof: Spec 437 changes backend comparable behavior only; no browser/render/provider execution lane is needed.
  • Narrowest proving command(s):
    • cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec437 --compact
    • targeted regressions listed in Phase 6.
  • Fixture / helper / factory / seed / context cost risks: reuse existing TenantConfiguration evidence factories/helpers; avoid global defaults.
  • 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: reviewer must verify valid payload hash and content-backed/captured provenance gates, scoped HMAC identity anchors, exact safe field value policies, no raw payload/context input, no evidence mutation, no UI/customer/trigger/persistence expansion, and exact target scope.
  • Budget / baseline / trend follow-up: none.
  • Review-stop questions: lane fit, redaction, evidence immutability, no-product-surface, no-mini-platform.
  • Escalation path: none unless implementation requires renderable, persistence, UI, or migration; then amend/split.
  • Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
  • Why no dedicated follow-up spec is needed: comparable-only builder is the dedicated bounded slice; renderable is already deferred to Spec 438.

Project Structure

Documentation

specs/437-exchange-comparable-promotion-slice-1/
|-- checklists/
|   `-- requirements.md
|-- implementation-report.md
|-- plan.md
|-- spec.md
`-- tasks.md

Source Code

Likely runtime paths if implementation proceeds:

apps/platform/app/Services/TenantConfiguration/
|-- ExchangePowerShellComparablePayloadBuilder.php
`-- ExchangePowerShellCoverageComparator.php  # only if needed

apps/platform/tests/Unit/Support/TenantConfiguration/
`-- Spec437ExchangeComparablePayloadBuilderTest.php

apps/platform/tests/Feature/TenantConfiguration/
`-- Spec437ExchangeComparablePromotionFeatureTest.php

Structure Decision: Use existing TenantConfiguration service/test locations. Do not create new base folders, migrations, routes, UI surfaces, jobs, listeners, schedules, commands, or customer-output paths.

Complexity Tracking

Violation Why Needed Simpler Alternative Rejected Because
New bounded builder helper Required to enforce normalized-payload-only input and protected Exchange target semantics. Reusing generic/ExchangeTeams normalizer would violate Spec 437 input and redaction gates.

Proportionality Review

  • Current operator problem: Future compare/render/certification work cannot safely proceed until Exchange evidence can be compared without leaking protected configuration or overclaiming readiness.
  • Existing structure is insufficient because: Existing generic/ExchangeTeams comparable path predates Spec 436 normalized evidence and includes broader renderable behavior that Spec 437 explicitly defers.
  • Narrowest correct implementation: One local builder for three concrete Exchange PowerShell target types; comparator only if needed; no persisted comparable artifact or coverage-level promotion.
  • Ownership cost created: Focused tests and future review burden around redaction/determinism.
  • Alternative intentionally rejected: Raw payload compare, normalized provider payload compare outside Spec 436 evidence, and ExchangeTeamsComparablePayloadNormalizer reuse.
  • Release truth: Current-release prerequisite for the Exchange roadmap.

Phase 0 - Preflight

  • Capture branch and HEAD.
  • Capture git status --short.
  • Confirm Spec 436 PASS/merge-ready or merged at current base.
  • Confirm target types content-backed.
  • Confirm comparable-only scope.
  • Confirm renderable deferred.
  • Confirm no UI/jobs/schedules/listeners/migration scope.
  • Confirm no hard-gate stop condition.

Deliverable: Preflight documented in implementation-report.md.

Phase 1 - Comparable Builder

  • Add Exchange PowerShell comparable payload builder.
  • Use normalized_payload only.
  • Require a valid SHA-256 payload_hash, evidence_state = content_backed, coverage_level = content_backed, and capture_outcome = captured.
  • Forbid raw payload/stdout/stderr/transcript input.
  • Forbid OperationRun context input.
  • Add deterministic output shape.

Deliverable: Comparable builder exists and is covered by unit tests.

Phase 2 - Target Comparable Payloads

  • Add transportRule comparable payload.
  • Add remoteDomain comparable payload.
  • Add inboundConnector comparable payload.
  • Encode protected config using redacted presence/count/safe-state semantics.
  • Block unexpected exact protected/sensitive values rather than sanitizing them through.
  • Validate exact safe fields by target-specific value policy before output.
  • Emit stable identity through scoped HMAC anchors instead of exact values or unsalted hashes.
  • Keep compare-shape and normalizer contract metadata hash-relevant; exclude run/evidence provenance from comparable hash.
  • Exclude volatile fields.

Deliverable: Three target comparable payloads.

Phase 3 - Determinism / Delta Semantics

  • Prove deterministic comparable payload.
  • Prove material changes produce changed comparable payload or machine deltas.
  • Prove volatile changes ignored.
  • Prove provider ordering deterministic.
  • Add comparator only if repo architecture requires it.

Deliverable: Comparable semantics are deterministic.

Phase 4 - Safety / Immutability

  • Prove evidence rows are not mutated.
  • Prove persisted coverage/resource/resource-type state is not promoted to comparable.
  • Prove no raw payload leaks.
  • Prove OperationRun context is not compare input.
  • Prove no renderable/customer/cert/restore state.

Deliverable: Comparable promotion without overclaim.

Phase 5 - Product Surface Guard

  • Prove no UI/routes/jobs/schedules/listeners.
  • Prove no report/review-pack/PDF/customer output.
  • Prove browser N/A.

Deliverable: No product surface changed.

Phase 6 - Regression / Report

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

Deliverable: Spec 437 implementation report.

Rollout Considerations

  • No migration or deployment flag.
  • No queue/scheduler/storage/asset change.
  • No filament:assets requirement introduced by this spec.
  • Comparable derivation remains internal backend behavior until a later spec explicitly adds render/read-model/customer surfaces.

Risk Controls

  • Hard stop on raw payload/context input.
  • Hard stop on protected exact value leakage.
  • Hard stop on missing content-backed/captured provenance.
  • Hard stop on invalid payload hash or malformed exact safe field values.
  • Hard stop on evidence mutation.
  • Hard stop on UI/read-model/customer/report/trigger/migration expansion.
  • Hard stop on new OperationRun type or tenant_id ownership truth.
  • Use static/no-surface tests in addition to behavior tests.