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

# Spec 335 Restore Result State Contract (Decision-First)

This contract defines the minimum decision-first states the Restore Run detail page must support.

It is intentionally derived: it may combine multiple persisted statuses into one operator-facing decision state.

## Fields (required on first screen)

- Status (label)
- Reason
- Impact
- Primary next action
- Operation proof state (OperationRun)
- Post-run evidence state (EvidenceSnapshot, repo-backed only)
- Result summary (repo-backed only)
- Diagnostics default state: collapsed

## Resolution Rules

- Operation proof is available only when the linked `operation_runs` row is same-workspace, same-managed-environment, and authorized for the current user.
- Post-run evidence is repo-backed only. It is available for the latest authorized `active` evidence snapshot for the linked operation run, same workspace, and same managed environment.
- Evidence snapshots in `queued` or `generating` state may be shown as in progress. Absent, unauthorized, or cross-workspace evidence is unavailable.
- Result attention copy remains visible, but for completed restore runs it does not override the top-level proof/evidence decision unless the persisted restore status itself is partial/error.
- Aggregate result counts may be present without item-level rows. The UI must label that as metadata-only evidence and must not show it as "0 items" when counts indicate affected or follow-up work.

## State Matrix

### 1) Not Executed (Draft / Preview Only)

- **State**: `not_executed`
- **Persisted triggers** (repo-verified):
  - `restore_runs.is_dry_run = true`, OR
  - `restore_runs.status in { draft, scoped, checked, previewed }` (pre-execution)
- **Visible status**: Not executed
- **Reason**: This record proves preview truth, not environment recovery.
- **Impact**: No execution proof or post-run evidence exists yet.
- **Primary next action**: Review preview / continue preparation (contextual to available actions)
- **Operation proof state**: Unavailable
- **Post-run evidence state**: Unavailable
- **Result summary**:
  - If `restore_runs.metadata` has counts: show them
  - Otherwise: show "Result summary unavailable" (no fake zeros)
- **Allowed proof claims**: "Preview evidence exists" (never "recovery verified")
- **Diagnostics default**: Collapsed

### 2) Execution In Progress (Queued / Running)

- **State**: `in_progress`
- **Persisted triggers** (repo-verified):
  - `restore_runs.status in { queued, running }`, OR
  - linked `operation_runs.status in { queued, running }`
- **Visible status**: Execution in progress
- **Reason**: Restore execution is currently running.
- **Impact**: Results and evidence are not final yet.
- **Primary next action**: View operation progress
- **Operation proof state**: In progress
- **Post-run evidence state**: Unavailable
- **Result summary**: show only repo-backed partial counts (if present); otherwise show "In progress"
- **Allowed proof claims**: "Execution in progress" only
- **Diagnostics default**: Collapsed

### 3) Completed (Recovery Proof Incomplete)

- **State**: `completed_proof_incomplete`
- **Persisted triggers**:
  - terminal completed restore run (`status = completed`)
  - post-run evidence snapshot not present, not active/current for the operation run, unauthorized, or cross-workspace
- **Visible status**: 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 when authorized proof exists; otherwise Review proof gap
- **Operation proof state**: Available if a scoped authorized operation run exists, otherwise Unavailable for legacy/imported rows
- **Post-run evidence state**: Unavailable
- **Result summary**: repo-backed counts from `restore_runs.metadata` when present
- **Allowed proof claims**: "Execution proof available" (never "recovery verified")
- **Diagnostics default**: Collapsed

### 4) Completed (Evidence Available)

- **State**: `completed_with_evidence`
- **Persisted triggers**:
  - terminal completed restore run
  - at least one authorized `active` evidence snapshot exists for the same `operation_run_id`, workspace, and managed environment
- **Visible status**: Completed with evidence available
- **Reason**: Execution proof and post-run evidence are available.
- **Impact**: Review evidence before treating the restore as recovery proof.
- **Primary next action**: Open evidence
- **Operation proof state**: Available
- **Post-run evidence state**: Available
- **Result summary**: repo-backed counts from `restore_runs.metadata`
- **Allowed proof claims**:
  - allowed: "Evidence snapshot available"
  - forbidden: "Recovery verified", "Healthy", "Compliant", "Customer-safe"
- **Diagnostics default**: Collapsed

### 5) Completed With Items Needing Review (Partial / Follow-Up)

- **State**: `needs_review`
- **Persisted triggers** (repo-verified via `RestoreResultAttention`):
  - `restore_runs.status in { partial, completed_with_errors }`
  - `RestoreSafetyResolver::resultAttentionForRun(...).state in { partial, completed_with_follow_up }` is still displayed as secondary result-attention copy/badging for `completed` runs, but does not supersede the top proof/evidence decision.
- **Visible status**: Completed with items needing review
- **Reason**: Some items were skipped, partially applied, or failed.
- **Impact**: Review item outcomes before relying on the result.
- **Primary next action**: Review item outcomes
- **Operation proof state**: Available (if `operation_run_id` exists), otherwise Unavailable
- **Post-run evidence state**: Available/Unavailable (repo-backed only; never implied)
- **Result summary**: show repo-backed counts (failed/skipped/partial/non_applied) when present
- **Allowed proof claims**: "Follow-up required" / "Skipped items exist" etc (no recovery claims)
- **Diagnostics default**: Collapsed

### 6) Failed

- **State**: `failed`
- **Persisted triggers** (repo-verified):
  - `restore_runs.status = failed`, OR
  - linked operation run outcome = `failed`
- **Visible status**: Restore failed
- **Reason**: The restore did not complete successfully.
- **Impact**: Some requested changes may not have been applied.
- **Primary next action**: Review failure details
- **Operation proof state**: Available (if `operation_run_id` exists); otherwise Unavailable
- **Post-run evidence state**: Unavailable (unless repo truth indicates otherwise)
- **Result summary**: show repo-backed counts when present; otherwise show "Failure details required"
- **Allowed proof claims**: "Execution failed" only; never "recovery verified"
- **Diagnostics default**: Collapsed

### 7) Cancelled / Blocked

- **State**: `blocked_or_cancelled`
- **Persisted triggers**:
  - `restore_runs.status = cancelled`, OR
  - linked operation run outcome = `blocked`
- **Visible status**: Restore blocked / cancelled
- **Reason**: Restore did not execute due to cancellation or blocker.
- **Impact**: No recovery proof exists.
- **Primary next action**: Review blocker
- **Operation proof state**: Available (if operation run exists); otherwise Unavailable
- **Post-run evidence state**: Unavailable
- **Result summary**: show "Unavailable" unless repo-backed
- **Allowed proof claims**: none beyond the above
- **Diagnostics default**: Collapsed