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

Feature Specification: Spec 335 - Restore Run Detail / Post-Execution Proof Productization

• Feature Branch: 335-restore-run-detail-post-execution-proof-productization
• Created: 2026-05-29
• Status: Draft
• Type: Runtime UX productization / Restore result proof surface / no backend rewrite
• Runtime posture: Productize the existing Restore Run detail surface using repo-backed RestoreRun + OperationRun + (when present) EvidenceSnapshot. No restore engine rewrite.
• Input: User-provided draft (originally drafted as "Spec 334"; number 334-* is already used in this repo, so this package is Spec 335).

Dependency Context

This spec is intentionally downstream of Restore Create.

• Spec 332 - Product Process Flow System v1
• Spec 333 - Restore Create UX Final Productization
• Spec 329 - Evidence / Audit Log Disclosure Productization
• Spec 328 - Operations Hub Decision-First Workbench Productization
• Spec 325 - Screenshot-Anchored Strategic Target Images

Summary

Spec 333 productized the Restore Create wizard. Spec 335 productizes what happens after a restore run exists:

• What was requested?
• What executed, what was skipped, what failed?
• Is execution proof available via OperationRun?
• Is post-run evidence available (repo-backed), or missing?
• What is the next safest operator action?

The goal is to prevent Restore Run detail from reading like a raw record view, log dump, or technical payload surface.

Product Goal

The Restore Run detail page must answer:

Was this restore executed safely, and is recovery proof available?

First screen (default-visible) must show:

Status
Reason
Impact
Primary next action
OperationRun proof
Post-run evidence state
Restore result summary
Diagnostics collapsed

Raw logs, payloads, and item JSON must not be required to understand outcome.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Restore Run "View" is still a mixed detail surface where operators can miss the distinction between execution completion, execution proof, and post-run recovery evidence.
• Today's failure: "Completed" can read as "safe/verified" unless the UI explicitly frames proof and evidence boundaries and presents one decision-first outcome model.
• User-visible improvement: Restore Run detail becomes decision-first: explicit status, reason, impact, and one primary next action; execution proof and post-run evidence are shown separately with honest availability states.
• Smallest enterprise-capable version: Productize the existing view surface using derived state from existing RestoreRun.results/metadata + OperationRun link + optional EvidenceSnapshot link(s). No new restore execution behavior. No new tables or migrations.
• Explicit non-goals: No new restore engine behavior, no new Graph calls, no new OperationRun types or lifecycle semantics, no new evidence generation pipeline, no new backend "recovery verified" semantics, no new packages, no new deployment steps.
• Permanent complexity imported: A small view-model/presenter (only if needed), refined Blade/Infolist layout, focused Feature/Browser tests, and spec screenshots.
• Why now: Restore is a high-risk workflow. Spec 333 made Create safe and decision-first; the next operator moment is post-execution truth and proof.
• Why not local: This is a cross-cutting truth/presentation boundary (execution proof vs evidence) that must be made explicit once and reused; page-local ad-hoc copy will drift.
• Approval class: Core Enterprise
• Red flags triggered: Dangerous workflow UX, status/proof messaging, evidence claims. Defense: bounded UI productization only; no new truth sources; explicit boundaries; tests + screenshots.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 1 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: tenant / managed-environment operator surface
• Primary Routes:
  • /admin/workspaces/{workspace}/environments/{environment}/restore-runs/{record} (Restore Run detail)
• Data Ownership:
  • Tenant-owned: restore_runs (JSON fields preview, results, metadata) + operation_runs (execution proof) + optional evidence_snapshots (post-run evidence).
  • No new persisted entity/table.
• RBAC:
  • Existing workspace membership + tenant entitlement remains authoritative.
  • Existing Capabilities::TENANT_VIEW gates access; non-member access remains deny-as-not-found (404); member missing capability remains 403.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage

• Route/page/surface: Restore Run detail (RestoreRunResource view page; infolist + Blade entries)
• Current or new page archetype: Domain Pattern Surface (post-execution result/proof)
• Design depth: Manual Review Required (dangerous-workflow truth surface)
• Repo-truth level: repo-verified (existing view surface + existing result attention contract + existing OperationRun relation)
• Existing pattern reused: existing RestoreResultAttention truth, BADGE-001 badges, existing restore proof panel patterns, OperationRun/Evidence resources.
• New pattern required: decision-first "result contract" wrapper that includes operation proof + evidence state explicitly (no new truth sources).
• Screenshot required: yes, specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/
• Page audit required: no (existing route/archetype); screenshots are the primary proof artifact
• Customer-safe review required: no (operator surface)
• Dangerous-action review required: yes (restore workflow semantics; avoid false recovery claims)
• Coverage files updated or explicitly not needed:
  • N/A - existing route/archetype; proof via Spec 335 screenshots

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, deep links, evidence/proof viewers, diagnostics disclosure
• Systems touched:
  • RestoreSafetyResolver::resultAttentionForRun() (existing result attention truth)
  • OperationRunLinks + OperationRunResource (execution proof)
  • EvidenceSnapshotResource (post-run evidence viewer, when repo-backed)
  • BadgeRenderer domains (status + evidence badges)
• Existing pattern(s) to extend: restore "what this proves / what it does not prove" boundary copy; decision-first card hierarchy; diagnostics collapsed by default
• Allowed deviation and why: none; any new presenter must remain a thin derived view-model (no persisted truth)
• Consistency impact: restore result decision copy + proof availability labels must remain stable across view + dashboards (no parallel local wording)
• Review focus: no false "recovery verified" claim; one primary next action; diagnostics and raw payload stay collapsed/secondary; links stay tenant/workspace-safe

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: link UX only (deep-link to operation proof)
• Shared OperationRun UX contract/layer reused: OperationRunLinks (no local URL composition)
• Delegated start/completion UX behaviors: Open operation link only; no new toasts/events/dedupe
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none

Provider Boundary / Platform Core Check

N/A - no shared provider/platform boundary is changed. This is presentation/productization on existing persisted truth.

Repo-Truth First Requirement (hard requirement)

Before runtime changes, this package must include a repo truth map:

• specs/335-restore-run-detail-post-execution-proof-productization/repo-truth-map.md

The map must classify each data point as:

repo-verified | derived from existing model | foundation-real | not available | deferred

Do not invent post-run proof states that are not repo-backed.

Required UX Contract

The visible UI must expose a top-level result decision model (fields may be derived from existing contracts):

[
    'status' => 'completed_recovery_proof_incomplete',
    'status_label' => 'Completed, recovery proof incomplete',
    'reason' => 'Execution completed, but post-run evidence is not available yet.',
    'impact' => 'Do not treat this restore as verified recovery until evidence has been reviewed.',
    'primary_next_action' => 'Open operation proof',
    'primary_next_url' => '...',
    'operation_proof' => [
        'state' => 'available',
        'label' => 'Operation proof available',
        'url' => '...',
    ],
    'post_run_evidence' => [
        'state' => 'unavailable',
        'label' => 'Post-run evidence unavailable',
        'url' => null,
    ],
    'result_summary' => [
        'requested' => 10,
        'applied' => 8,
        'skipped' => 1,
        'failed' => 1,
        'needs_review' => 2,
    ],
    'diagnostics_state' => 'collapsed',
]

Exact implementation may differ, but the visible page must uphold this hierarchy and boundary.

Restore Result States

Minimum supported product states are defined in:

• specs/335-restore-run-detail-post-execution-proof-productization/restore-result-state-contract.md

The UI must not imply "recovery verified" unless repo-backed verification semantics exist.

Scope

In Scope

• Productize Restore Run detail view surface (decision-first result/proof/evidence)
• OperationRun proof panel (link + status context, not raw logs first)
• Post-run evidence availability state (link when repo-backed)
• Result summary and item outcome table (only when repo-backed)
• Diagnostics/raw details collapsed by default
• Spec 335 tests and screenshots

Out of Scope

• Restore engine / execution backend changes
• New Graph calls or provider gateway behavior
• New OperationRun semantics or model rewrites
• New evidence generation pipeline or migrations (unless explicitly justified and added to the spec first)
• New packages, env vars, scheduler/queue/storage changes
• Restore Create wizard redesign (Spec 333 owns Create UX)

Proportionality Review (mandatory when structural complexity is introduced)

This spec may introduce a small presenter/view-model.

• New source of truth?: no
• New persisted entity/table/artifact?: no (spec artifacts + screenshots only)
• New abstraction?: yes, a thin derived presenter if the page needs one decision-contract output (no persistence, no global framework)
• New enum/state/reason family?: no persisted family; any "status label" is derived display-only
• Current operator problem: post-execution restore truth/proof/evidence is not decision-first enough.
• Narrowest correct implementation: derived view-model + layout/product copy refinements on existing persisted data.
• Alternative intentionally rejected: introducing new persisted "recovery proof" models or new workflow frameworks.
• Release truth: current-release UX productization.

Compatibility posture

Pre-production: prefer replacement over shims. No legacy alias paths are introduced.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature/Livewire + Browser (plus Unit if a presenter is introduced)
• Validation lane(s): confidence + browser; formatting via Pint; whitespace guard via git diff --check
• Why sufficient: this is a user-facing operator detail surface with truth-boundary risk; Feature tests prove default-visible hierarchy; Browser smoke provides final UI proof and screenshots.

Acceptance Criteria

Product

• Restore Run detail is decision-first.
• First screen answers whether execution proof and post-run evidence are available.
• OperationRun proof is visible and linked where authorized.
• Post-run evidence state is visible and truthful.
• Result summary and item outcomes are shown only when repo-backed.
• Diagnostics are collapsed by default.

Safety

• Completed execution does not imply recovery verified.
• No false evidence claim is displayed.
• Raw payloads/logs are hidden by default.

Context / RBAC

• Workspace/environment isolation is preserved.
• Cross-workspace proof/evidence is not visible.
• No legacy /admin/t or tenant query alias is introduced.

Technical

• No backend rewrite.
• No migrations unless explicitly justified and added to this spec before implementation.
• No new packages.