TenantAtlas/specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/plan.md

# Implementation Plan: OperationRun Reconciliation Adapter Framework & Review Compose Adapter

**Branch**: `359-operationrun-reconciliation-adapter-framework-review-compose-adapter` | **Date**: 2026-06-06 | **Spec**: `specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/spec.md`  
**Input**: Feature specification from `specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/spec.md`

## Summary

Implement a narrow business-truth reconciliation seam for `OperationRun` that reuses existing service-owned lifecycle writes and existing review-compose start/monitoring UX. The slice introduces one typed adapter contract plus one `environment.review.compose` adapter, proves same-scope `EnvironmentReview` truth, recovers duplicate fingerprint collisions deterministically, and keeps restore-specific reconciliation behavior intact as existing context rather than reopening it as a second feature.

This plan must stay smaller than a universal reconciliation engine. It extends current repo seams only where current review-compose truth cannot be proven safely by the existing scheduled stale-run reconciler or the hard-coded restore adapter.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52, Filament 5.2.1, Livewire 4.1.4  
**Primary Dependencies**: existing `OperationRunService`, `OperationRun`, `OperationCatalog`, current restore adapter reconciler, current review-compose services/jobs/resources, Pest 4.3  
**Storage**: PostgreSQL `operation_runs` and `environment_reviews`; no schema change planned  
**Testing**: Pest Unit + Feature + one bounded Browser smoke; PGSQL lane required for duplicate-index/locking proof  
**Validation Lanes**: fast-feedback, confidence, pgsql, browser  
**Target Platform**: Laravel monolith in `apps/platform`  
**Project Type**: web application  
**Performance Goals**: reuse current DB-only monitoring posture, avoid new render-time Graph work, and keep adapter evaluation to scoped local DB reads only  
**Constraints**: no new `OperationRun` status/outcome field, no new review status family, no new panel/provider/asset change, no provider-boundary widening, no destructive cleanup, and no broad restore/report/evidence adapter expansion  
**Scale/Scope**: one new review-compose path on the existing adapter reconciliation seam plus the smallest local decision/result helper needed to make adapter reconciliation auditable and repeatable

## Likely Affected Repo Surfaces

- Existing reconciliation and lifecycle seams:
  - `apps/platform/app/Services/OperationRunService.php`
  - `apps/platform/app/Models/OperationRun.php`
  - `apps/platform/app/Services/Operations/OperationLifecycleReconciler.php`
  - `apps/platform/app/Services/AdapterRunReconciler.php`
  - `apps/platform/app/Support/OperationCatalog.php`
  - `apps/platform/app/Support/OperationRunType.php`
  - `apps/platform/app/Support/OperationRunStatus.php`
  - `apps/platform/app/Support/OperationRunOutcome.php`
- Existing review-compose runtime seams:
  - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewService.php`
  - `apps/platform/app/Jobs/ComposeEnvironmentReviewJob.php`
  - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`
  - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewFingerprint.php`
  - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewLifecycleService.php`
  - `apps/platform/app/Models/EnvironmentReview.php`
- Existing operator-facing surfaces likely to consume richer metadata:
  - `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`
  - `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
  - `apps/platform/app/Support/OperationRunLinks.php`
  - `apps/platform/app/Filament/Pages/Monitoring/Operations.php`
  - `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
  - `apps/platform/app/Filament/Resources/OperationRunResource.php`
  - `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`
  - `apps/platform/app/Filament/Widgets/Dashboard/RecentOperations.php`
  - `apps/platform/app/Filament/System/Pages/Ops/Runs.php`
  - `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php`
  - `apps/platform/lang/en/localization.php`
  - `apps/platform/lang/de/localization.php`
- Focused tests:
  - `apps/platform/tests/Unit/Support/Operations/Reconciliation/`
  - `apps/platform/tests/Feature/Operations/`
  - `apps/platform/tests/Feature/EnvironmentReview/`
  - `apps/platform/tests/Feature/Monitoring/`
  - `apps/platform/tests/Browser/`

## Domain And Data Implications

- `operation_runs` remains the only persisted run-lifecycle truth. Reconciliation remains a context extension, not a new status model.
- `environment_reviews` remains the only domain-truth source for review availability. The adapter proves truth from existing review rows only.
- The partial unique index `environment_reviews_fingerprint_mutable_unique` remains the core duplicate-collision constraint. The feature must adapt to it, not replace it.
- Existing mutable/superseded semantics remain authoritative:
  - mutable: `draft`, `ready`, `failed`
  - historical/terminal lineage: `published`, `archived`, `superseded`
- No migration is planned. If implementation appears to need one, that is a scope alarm and should stop for review.

## UI / Surface Guardrail Plan

- **Guardrail scope**: existing operator-facing monitoring surfaces plus existing review-start feedback
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/admin/workspaces/{workspace}/operations`
  - `/admin/workspaces/{workspace}/operations/{run}`
  - `EnvironmentReviewResource` create/refresh notifications and open-link feedback
  - tenant dashboard recent-operations widget
  - system operations list
  - environment dashboard recent/attention summaries
- **No-impact class, if applicable**: non-material existing-surface wording/state handling only
- **Native vs custom classification summary**: native Filament surfaces plus existing action notifications
- **Shared-family relevance**: monitoring-state messaging, reconciliation diagnostics, run-start feedback
- **State layers in scope**: page, detail, action feedback
- **Audience modes in scope**: operator-MSP, support-platform
- **Decision/diagnostic/raw hierarchy plan**: decision-first reconciliation result, diagnostics second, raw evidence third
- **Raw/support gating plan**: existing detail/raw context remains secondary and must never become the primary explanation
- **One-primary-action / duplicate-truth control**: keep the existing open-run/open-review actions authoritative and avoid a second local “duplicate recovered” surface
- **Handling modes by drift class or surface**:
  - review-compose succeeded from domain truth: `review-mandatory`
  - blocked/attention without safe proof: `review-mandatory`
  - any raw SQL/constraint leak: `hard-stop-candidate`
- **Repository-signal treatment**: review-mandatory
- **Special surface test profiles**: monitoring-state-page, shared-detail-family
- **Required tests or manual smoke**: Unit + Feature + PGSQL + one bounded Browser smoke
- **Exception path and spread control**: any move toward new operator-center UX, report/evidence adapter copy, or customer-facing surface changes is `reject-or-split`
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **UI/Productization coverage decision**: existing surface follow-through only
- **Coverage artifacts to update**: none by default; update existing page reports only if final visible hierarchy materially changes
- **No-impact rationale**: no route or page identity change
- **Navigation / Filament provider-panel handling**: unchanged; provider registration stays in `apps/platform/bootstrap/providers.php`
- **Screenshot or page-report need**: no new page-report identity; one bounded browser smoke screenshot is sufficient only if implementation materially changes visible wording hierarchy

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**:
  - scheduled reconciliation path
  - restore-specific adapter reconciliation precedent
  - review-compose start/complete flow
  - monitoring list/detail surfaces
  - review-create notifications
- **Shared abstractions reused**:
  - `OperationRunService::updateRunWithReconciliation()`
  - `OperationRun::reconciliation()`
  - `OperationUxPresenter`
  - `OperationRunLinks`
  - `ArtifactTruthPresenter`
  - `EnvironmentReviewResource::executeCreateReview()`
- **New abstraction introduced? why?**: yes; one local review-compose decision/result helper is introduced because the current restore-only adapter path is too hard-coded to absorb review fingerprint/scope/supersession proof safely.
- **Why the existing abstraction was sufficient or insufficient**: current abstractions already own run lifecycle and generic stale truth, but `AdapterRunReconciler` currently only knows `restore.execute`; this slice extends that seam rather than adding a parallel registry.
- **Bounded deviation / spread control**: keep the new helper local to adapter reconciliation and explicitly bounded to review-compose plus existing restore context

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes
- **Central contract reused**: current service-owned lifecycle plus current review-create queued-toast/open-run path
- **Delegated UX behaviors**:
  - create/refresh keeps the current queued toast and `Open operation` link
  - adapter completion writes terminal truth through `OperationRunService`
  - operations list/detail continue to read one reconciliation metadata shape
- **Surface-owned behavior kept local**: only review-create body copy and any additional review-available/recovered wording
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged central lifecycle mechanism
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no
- **Provider-owned seams**: N/A
- **Platform-core seams**: `OperationRun` lifecycle truth and `EnvironmentReview` artifact truth only
- **Neutral platform terms / contracts preserved**: `operation`, `reconciliation`, `review`, `workspace`, `managed environment`
- **Retained provider-specific semantics and why**: none
- **Bounded extraction or follow-up path**: none

## Authorization, Audit, And Observability

- Existing workspace-first and managed-environment entitlement checks remain unchanged.
- Adapter lookup must not widen who can see or use a review; it only determines which local record may prove the run.
- `OperationRunService` remains the owner of terminal audit emission.
- Reconciliation evidence must stay bounded to safe identifiers and state:
  - allowed: workspace ID, managed environment ID, review ID, review status, fingerprint hash, considered review IDs, timestamps
  - forbidden: raw Graph payloads, signed URLs, tokens, raw SQL errors, full snapshot blobs
- Optional operational logging may emit adapter name, run ID, type, decision, and related review ID only.

## Constitution Check

- Inventory-first: unchanged; `EnvironmentReview` remains the local artifact truth and still derives from anchored evidence snapshots.
- Read/write separation: adapter reconciliation mutates only `OperationRun`, not the provider or remote state.
- Graph contract path: unchanged; no Graph calls are introduced.
- Deterministic capabilities: unchanged; current capability checks remain authoritative.
- Workspace and tenant isolation: unchanged and still mandatory for both runs and reviews.
- Run observability: strengthened; late or duplicate review-compose work remains visible on `OperationRun` instead of being silently inferred elsewhere.
- Proportionality / anti-bloat: pass only if the adapter contract stays narrow and does not become a universal business-reconciliation engine.
- No premature abstraction: this is allowed only because queue correctness and auditability already justify a typed seam, and the repo already ships one restore-specific adapter precedent.
- Persisted truth: no new tables or persisted status families.
- Shared pattern first: reuse current run lifecycle, current monitoring/detail surfaces, and current review-start feedback.
- Filament v5 / Livewire v4 posture: unchanged; no panel/provider or asset work is allowed.

## Test Governance Check

- **Test purpose / classification by changed surface**:
  - Unit: reconciliation decisions, supported-type handling, adapter same-scope proof
  - Feature: service/job/idempotency/reconciliation metadata flow
  - Browser: visible operations/review wording smoke
- **Affected validation lanes**: fast-feedback, confidence, pgsql, browser
- **Why this lane mix is the narrowest sufficient proof**: duplicate fingerprint recovery depends on a PGSQL partial unique index and scope-safe DB truth, while visible monitoring wording needs only one bounded browser smoke rather than a broad productization run.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec359`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest -c phpunit.pgsql.xml --filter=Spec359`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec358`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: reuse existing review/evidence/run factories; do not widen default tenant/workspace setup
- **Expensive defaults or shared helper growth introduced?**: none planned
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: monitoring-state-page plus shared-detail-family; one explicit browser smoke only
- **Closing validation and reviewer handoff**: reviewers should compare ready-review reuse, ambiguous duplicate collisions, repeated create/refresh triggers, and visible operations detail wording before merge
- **Budget / baseline / trend follow-up**: none expected beyond feature-local tests
- **Review-stop questions**:
  - Did implementation add a second persisted status shape?
  - Did implementation widen into report/evidence/restore business reconciliation?
  - Can any duplicate/superseded case still remain queued/running forever?
  - Does any visible copy leak SQL/constraint wording?
- **Escalation path**: `reject-or-split` for universal reconciliation scope growth
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **Why no dedicated follow-up spec is needed**: this slice is already the follow-through over Spec 358 and must remain bounded to review-compose truth only

## Implementation Phases

### Phase 1 — Lock repo truth and convergence boundaries

- Reconfirm the current scheduled reconciler, restore-specific adapter reconciler, and review-compose seams.
- Decide whether the existing restore adapter stays as-is or is bridged behind the new contract without behavioral change.
- Freeze the current visible operations/review feedback vocabulary that must remain consistent.

### Phase 2 — Add the narrow reconciliation contract

- Extend the existing adapter reconciliation seam with one local review-compose decision/result helper and explicit supported-type handling.
- Extend or wrap `OperationRunService::updateRunWithReconciliation()` so richer metadata can be merged idempotently.
- Keep all persistence shapes unchanged.

### Phase 3 — Implement review-compose proof and recovery

- Add a same-scope review-compose adapter that proves ready/published review truth and fails closed on ambiguity.
- Integrate duplicate recovery and pre/post compose checks into `ComposeEnvironmentReviewJob`.
- Tighten `EnvironmentReviewService` repeated-trigger behavior so active review truth or active run truth is reused rather than multiplied.

### Phase 4 — Retrofit existing operator surfaces

- Keep current monitoring list/detail surfaces authoritative for reconciled review-compose explanation.
- Reuse current review-start feedback and current `Open operation` / `View review` patterns.
- Add bounded EN/DE copy only where the existing language is too generic or too technical.

### Phase 5 — Validate and hand off

- Add Unit + Feature + PGSQL + Browser proof.
- Re-run Spec 358 plus the named review/report regressions.
- Record final guardrail, smoke, and bounded-scope notes in the feature close-out entry.

## Risks and Mitigations

- **Framework creep**: mitigate by forbidding new adapter families and by treating restore/report/evidence follow-through as out of scope.
- **Scope-safety mistakes**: mitigate with explicit cross-workspace, cross-environment, and wrong-fingerprint negative tests.
- **PGSQL-only blind spots**: mitigate with an explicit `phpunit.pgsql.xml` lane for duplicate-index and lock behavior.
- **Visible copy drift**: mitigate by keeping all user-facing wording on current operations/review paths and adding one bounded browser smoke.

## Project Structure

### Documentation

```text
specs/359-operationrun-reconciliation-adapter-framework-review-compose-adapter/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md
```

### Likely Runtime Structure

```text
apps/platform/app/Services/
├── OperationRunService.php
├── AdapterRunReconciler.php
└── EnvironmentReviews/
    ├── EnvironmentReviewService.php
    ├── EnvironmentReviewComposer.php
    ├── EnvironmentReviewFingerprint.php
    └── EnvironmentReviewLifecycleService.php

apps/platform/app/Jobs/
└── ComposeEnvironmentReviewJob.php

apps/platform/app/Filament/
├── Pages/Monitoring/Operations.php
├── Pages/Operations/TenantlessOperationRunViewer.php
└── Resources/
    ├── OperationRunResource.php
    └── EnvironmentReviewResource.php
```