TenantAtlas/specs/011-restore-run-wizard/spec.md

# Feature Specification: Restore Run Wizard (011)

**Feature Branch**: `feat/011-restore-run-wizard`  
**Created**: 2025-12-30  
**Status**: Draft  
**Input**: Restore Run Wizard requirements (Safety First / Defensive Restore)

## Overview
Implement **Restore Runs** as a **multi-step Wizard** (instead of a single “Create Restore Run” form) to enforce **Safety First / Defensive Restore**.

Restore is a high-risk workflow. The wizard must guide admins through explicit checkpoints:
source selection → scoping → safety checks → preview → confirmation + execution.

## Problem Statement
The current Restore Run creation is a single form that can lead to:
- picking the wrong backup source
- restoring too broad a scope unintentionally
- executing without a structured “risk + preview + explicit confirmation” flow

## Goals
- Make restore a **deliberate, stepwise** process with strong defaults.
- Make **dry-run** the default, and keep “Execute” disabled until all safety gates are satisfied.
- Add **server-side safety/conflict checks** and persist results for auditability.
- Provide a **preview** (diff summary at minimum) before allowing execution.

## Non-Goals (v1)
- Approval workflows / multi-person approvals (but design must not block future addition).
- Perfect diff UX parity with Intune (basic normalized diff output is enough).
- A generic wizard framework (restore-specific implementation is fine).

---

## UX Principles
- **Dry-run default = ON**
- Wizard progression should slow the user down and force explicit decisions.
- “Execute” stays disabled until:
  - Preview has been completed
  - No blocking checks exist
  - “I reviewed the impact” checkbox is checked
  - Tenant hard-confirm matches (Highlander principle)

---

## Wizard Steps

### Step 1 — Select Backup Set (Source of Truth)
**Question:** “What are we restoring from?”

**Inputs**
- Backup Set (required)

**Read-only**
- Snapshot timestamp
- Tenant name
- Count of policies/items
- Types (Config / Security / Scripts …)

**Validation**
- `backup_set_id` is required
- Changing the backup set resets downstream state (scope, checks, preview, confirmation)

### Step 2 — Define Restore Scope (Selectivity)
**Question:** “What exactly should be restored?”

**Inputs**
- Scope mode: `all` (default) or `selected`
- If `selected`: item multiselect with search + select all

**UI**
- Prefer grouped by **type** and **platform**
- Mark “preview-only” types clearly
- Foundations should be discoverable (scope tags, assignment filters, notification templates)

**Notes**
- “Empty = all” only when scope mode is `all` (not when `selected`)

### Step 3 — Safety & Conflict Checks (Defensive Layer)
**Question:** “Is this dangerous?”

**Checks (server-side, persisted)**
- Target policy missing in target tenant?
- Target policy newer than backup? (staleness / overwrite risk)
- Assignments conflicts (e.g., mapping required / orphaned groups)
- Scope tag conflicts (mapping required / missing)
- Preview-only policies included in scope (should be warned and auto-dry-run)

**Severity**
- ❌ blocking
- ⚠️ warning
- ✅ safe

**Rules**
- Blocking checks prevent execution.
- Wizard may allow proceeding to preview, but must never allow execute while blockers exist.

### Step 4 — Preview (Dry-Run Simulation)
**Question:** “What would happen?”

**Outputs**
- Diff summary (at minimum):
  - X policies changed
  - Y assignments changed
  - Z scope tags changed
- Per-item normalized diff (nice-to-have for v1, but plan for it)

**Defaults**
- “Preview only (Dry-run)” is ON by default

### Step 5 — Confirm & Execute (Point of No Return)
**Question:** “Do you really want to do this?”

**Confirmations**
- Checkbox: “I reviewed the impact”
- Tenant hard-confirm input (must match tenant display identifier)
- Environment badge (Prod/Test) highly visible (frozen at run start for audit)

**Rules**
- Execute disabled if:
  - `dry_run = true`
  - blockers exist
  - tenant confirm mismatch
  - acknowledgement unchecked

---

## Domain Model (v1-aligned)
We already have a `restore_runs` aggregate (`restore_runs` table) with:
- `backup_set_id`, `requested_items`, `preview`, `results`, `status`, `metadata`, timestamps, and `group_mapping`.

**v1 approach**
- Keep the existing primary key type (bigint) to avoid a disruptive migration.
- Extend the lifecycle/status semantics and persist wizard computations (checks + diff summaries) in structured fields:
  - Prefer adding dedicated JSON columns only if needed; otherwise use `metadata` for wizard state.

### RestoreRun Lifecycle (proposed statuses)
`draft → scoped → checked → previewed → queued → running → completed|partial|failed|cancelled`

### Persisted Wizard State (minimum)
- `backup_set_id` (existing)
- `requested_items` (selected IDs, existing)
- `metadata.scope_mode` (`all|selected`)
- `metadata.environment` (`prod|test`)
- `metadata.highlander_label` (tenant identifier string, frozen)
- `metadata.check_summary` + `metadata.check_results` (Step 3)
- `metadata.preview_summary` + `metadata.preview_diffs` (Step 4; diffs may be truncated/limited)
- `metadata.confirmed_at`, `metadata.confirmed_by` (Step 5)

---

## Services / Responsibilities
- **RestoreScopeBuilder**: build selectable restore items (grouped, searchable), include foundations & mark preview-only.
- **RestoreRiskChecker**: run safety checks, return structured results + summary.
- **RestoreDiffGenerator**: generate diff summary (and optionally per-item diffs) for preview.
- **RestoreExecutor**: execute restore (idempotent, tenant/run locking), write detailed outcomes.
- **RestoreRunPolicy**: enforce invariants (no execution without preview + confirmations).

---

## User Scenarios & Testing *(mandatory)*

### User Story 1 — Wizard-driven Restore Run (Priority: P1)
As an admin, I can create a restore run via a 5-step wizard and I cannot accidentally execute without preview + explicit confirmations.

**Why this priority**: This is the safety foundation; without it, restore remains risky UX.

**Independent Test**: In Filament, create a restore run with dry-run, see checks + preview, and confirm execute stays disabled until gates satisfied.

**Acceptance Scenarios**
1. **Given** I select a backup set, **When** I move to the next step, **Then** scope/check/preview state is reset when I change the backup set again.
2. **Given** I keep dry-run enabled, **When** I reach Step 5, **Then** Execute is disabled.
3. **Given** I disable dry-run, **When** I have not completed preview, **Then** Execute is disabled.

---

### User Story 2 — Safety Checks block execution (Priority: P1)
As an admin, I see blocking vs warning checks, and execution is blocked when blockers exist.

**Why this priority**: Defensive restore requires an explicit risk layer.

**Independent Test**: Create a scope that triggers a blocking check and verify execution cannot proceed.

**Acceptance Scenarios**
1. **Given** a blocking check exists, **When** I reach Step 5, **Then** Execute remains disabled and blockers are visible.
2. **Given** only warnings exist, **When** I acknowledge impact and hard-confirm tenant, **Then** I can execute (dry-run off).

---

### User Story 3 — Preview diff summary (Priority: P2)
As an admin, I can preview what would change before executing restore.

**Why this priority**: A restore without preview is operationally unsafe.

**Independent Test**: Run Step 4 preview and verify diff summary is computed and persisted on the RestoreRun.

**Acceptance Scenarios**
1. **Given** I scoped items, **When** I run preview, **Then** I see a summary (changed policies count) and it persists on the restore run.

---

## Edge Cases
- Very large backup sets (hundreds/thousands of items): selection/search must remain responsive.
- Switching backup set mid-flow resets downstream state safely.
- Policies not present in target tenant: shown as warning/blocker depending on restore mode.
- RBAC-limited tenant setup: checks must clearly show “inventory/restore may be partial”.

---

## Functional Requirements
- **FR-011.1**: System MUST implement Restore Run creation as a 5-step wizard in Filament.
- **FR-011.2**: System MUST default `dry_run = true` and prevent execution while dry-run is enabled.
- **FR-011.3**: System MUST run server-side safety checks and persist results (summary + details) for audit.
- **FR-011.4**: System MUST generate at least a diff summary on preview and persist it.
- **FR-011.5**: System MUST require explicit acknowledgement + tenant hard-confirm before allowing execution.
- **FR-011.6**: System MUST freeze environment badge and tenant label for audit on run creation.
- **FR-011.7**: System MUST keep execution disabled if any blocking checks exist.
- **FR-011.8**: System MUST record execution outcomes and leave an auditable trail (existing audit log patterns).

---

## Success Criteria
- **SC-011.1**: Admins can only execute after preview + confirmations; no accidental execution path exists.
- **SC-011.2**: Blocking checks reliably prevent execution.
- **SC-011.3**: Preview produces a persisted summary for every run.