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:

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

First screen (default-visible) must show:

```text
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
- [x] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [x] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] 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**:
  - [x] `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:

```text
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):

```php
[
    '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.