TenantAtlas/specs/335-restore-run-detail-post-execution-proof-productization/plan.md

Implementation Plan: Spec 335 - Restore Run Detail / Post-Execution Proof Productization

• Branch: 335-restore-run-detail-post-execution-proof-productization
• Date: 2026-05-29
• Spec: specs/335-restore-run-detail-post-execution-proof-productization/spec.md
• Input: User-provided draft + repo inspection for truth (RestoreRun/OperationRun/EvidenceSnapshot + current Filament view implementation)

Summary

Refactor the Restore Run detail surface into a decision-first post-execution result/proof/evidence view.

This work is UI/productization only:

• derive a top-level "restore result decision" contract from existing persisted fields (restore_runs.results, restore_runs.metadata, restore_runs.operation_run_id) and (when present) linked evidence_snapshots
• render one default-visible hierarchy: status/reason/impact/next action first; proof/evidence state explicit; diagnostics collapsed
• keep raw payloads and diagnostics behind disclosure
• preserve RBAC, tenant/workspace isolation, and existing route/context behavior

No restore execution backend changes are in scope.

Technical Context

• Language/Version: PHP 8.4.x
• Primary Dependencies: Laravel 12.x, Filament v5, Livewire v4
• Storage: PostgreSQL (tenant-owned restore_runs, operation_runs, evidence_snapshots)
• Testing: Pest v4 + Livewire component testing; Browser tests for smoke/screenshots
• Validation Lanes: confidence + browser
• Target Platform: Laravel Sail (local); Dokploy (deploy) posture unchanged
• Project Type: Laravel monolith under apps/platform
• Performance Goals: avoid new expensive queries; prefer existing eager loads; only query evidence snapshots when an operation_run_id exists
• Constraints: no new packages; no migrations unless explicitly justified and approved in-spec
• Scale/Scope: one Filament view surface + related presenters/blade entries + tests/screenshots

UI / Surface Guardrail Plan

• Guardrail scope: changed operator-facing detail surface (dangerous workflow result/proof)
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • Restore Run detail view (RestoreRunResource view page)
  • Restore result presentation (existing infolist entry view: filament/infolists/entries/restore-results.blade.php)
  • Restore proof/evidence presentation (new or reused proof-aside surface)
• Native vs custom classification summary: native Filament page with shared primitives + a small amount of custom Blade in infolist entries
• Shared-family relevance: status messaging + proof/evidence deep links; diagnostics disclosure; shared OperationRun/Evidence viewers
• State layers in scope: page + detail + URL (optional dashboard context param already exists)
• Audience modes in scope: operator-MSP; no customer-facing change
• Decision/diagnostic/raw hierarchy plan: decision-first; diagnostics collapsed and secondary
• Raw/support gating plan: collapsed disclosures; never default-show raw payloads, exception text, or Graph error details as primary message
• One-primary-action / duplicate-truth control: exactly one dominant next action in the decision card; avoid repeating equivalent banners/cards in multiple sections
• Handling modes: review-mandatory (truth boundary / dangerous-workflow UX)
• Special surface test profiles: shared-detail-family + dangerous workflow proof surface
• Required tests or manual smoke: Feature/Livewire tests for contract visibility + RBAC/isolation; Browser smoke for screenshots and dark mode
• Exception path and spread control: if evidence is not repo-backed for restore runs, UI must state "unavailable" (do not invent)
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage
• UI/Productization coverage decision: existing route/archetype; cover via Spec 335 screenshots + Feature/Browser tests

Shared Pattern & System Fit

• Cross-cutting feature marker: yes (proof/evidence link semantics, decision-first status hierarchy)
• Systems touched:
  • App\Support\RestoreSafety\RestoreSafetyResolver (result attention truth)
  • App\Support\Badges\BadgeRenderer (status/evidence badge semantics)
  • App\Support\OperationRunLinks + OperationRunResource (proof deep link)
  • EvidenceSnapshotResource (evidence deep link, when present)
• Shared abstractions reused: reuse existing copy/badges and link resolvers; do not create new global status frameworks
• New abstraction introduced?: optional, narrow presenter for the Restore Run detail decision contract (derived only, no persistence)
• Bounded deviation / spread control: any presenter must live feature-locally and remain a pure derived view-model (no caching, no global registry)

OperationRun UX Impact

• Link UX only: the Restore Run detail page will expose "Operation proof" and deep-link to the existing OperationRun view.
• No start/enqueue/dedupe semantics change.
• URLs must be generated via existing link helpers (OperationRunLinks / Filament resource getUrl(...)) to preserve workspace/environment context.

Data / Migrations

• No migrations planned.
• No new persisted fields planned.
• Evidence is read-only: if evidence snapshots are present for the linked operation_run_id, show them; otherwise show honest "unavailable".

Implementation Approach

Phase 1 - Repo Truth (pre-work)

• Document restore run model fields/statuses and result structures in repo-truth-map.md.
• Document the visible result/proof state machine in restore-result-state-contract.md.
• Confirm existing Restore Run view implementation and tests (current infolist entries and RestoreResultAttentionSurfaceTest).

Phase 2 - Result Presenter / View Model (derived only)

• If needed, introduce a derived presenter that returns the UI contract:
  • status label + reason + impact + primary next action
  • operation proof state + URL (when authorized)
  • post-run evidence state + URL (when repo-backed)
  • result summary counts (from restore_runs.metadata and restore_runs.results)
  • diagnostics default = collapsed

Phase 3 - Detail Page UI

• Switch Restore Run view from "entries list" toward a main/aside layout:
  • Main: decision card + result summary + item outcomes (table) + secondary run details
  • Aside: proof panel (source backup, target environment, requested by, operation proof, post-run evidence, audit trail) + diagnostics disclosure
• Ensure raw payloads remain behind disclosure.

Phase 4 - Proof/Evidence Links

• Operation proof:
  • show status and link to OperationRun view when the restore run is linked to an operation run
  • show "unavailable" when no operation run exists
• Evidence:
  • query evidence snapshots for the restore run's operation_run_id (tenant-scoped) and surface state + link when present
  • otherwise show "unavailable" (no fake "recovery verified")

Phase 5 - Tests + Browser Screenshots

• Add/extend Feature tests to assert:
  • decision question and status label for key states
  • operation proof and evidence states are explicit
  • diagnostics collapsed by default; raw payload not visible by default
  • tenant/workspace isolation and capability gating (deny-as-not-found vs forbidden semantics preserved)
• Add a Browser smoke/screenshot test that captures the required screenshot set under the Spec 335 artifact path.

Validation Commands

Planned (narrow) commands for implementation review:

cd apps/platform

./vendor/bin/sail artisan test \
  tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php \
  tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php \
  --compact

cd apps/platform

./vendor/bin/sail php vendor/bin/pest \
  tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php \
  --compact

cd apps/platform

./vendor/bin/sail pint --dirty
git diff --check