TenantAtlas/specs/333-restore-create-ux-final-productization/restore-create-state-contract.md

# Restore Create State Contract - Spec 333

This contract describes the visible product-state matrix for the Restore Create wizard. It is a preparation artifact for implementation. Runtime truth must remain centralized in `RestoreRunCreatePresenter`; Blade components render this contract and must not invent independent status, proof, gate, or next-action truth.

## Contract Columns

| Column | Meaning |
|---|---|
| State | The product state represented in the current wizard step |
| Visible status | The operator-facing state label |
| Reason | Why the state is true |
| Impact | What the state means for safe progression |
| Primary next action | The one dominant action for the operator |
| Gate state | Complete, required, blocked, warning, or unavailable |
| Can continue? | Whether the wizard may advance from this state |
| Proof claims allowed? | What the UI may claim without overclaiming |
| Diagnostics | Default diagnostic visibility |

## Central Wizard Gate Contract

`RestoreRunCreatePresenter` must expose one `wizard_gate` section. Step views, compact safety evidence, button hooks, disabled states, and blocking notifications consume this section rather than recreating gate copy locally.

Required concepts:

- `current_gate` / `current_gate_label`
- `next_gate` / `next_gate_label`
- `blocking_prerequisite` / `blocking_prerequisite_label`
- `required_action` / `required_action_label`
- `can_continue`
- `continue_label`
- `continue_disabled_reason`
- `execution_state` / `execution_label`
- `can_execute`
- `proof_state`
- `preview_state`
- `confirmation_state`

If validation and preview evidence are current but real execution prerequisites are unavailable, Step 4 may still advance to confirmation review. In that state, `next_gate_label` is `Confirmation required`, `can_continue` is `true`, `can_execute` is `false`, and `execution_label` must state that execution is unavailable until prerequisites are resolved. Step 4 must not emit a generic `Execution blocked` notification while advertising confirmation as the next gate.

## Step 1 - Select Backup Set

| State | Visible status | Reason | Impact | Primary next action | Gate state | Can continue? | Proof claims allowed? | Diagnostics |
|---|---|---|---|---|---|---|---|---|
| No backup selected | Source required | Select a completed backup set before restore validation. | Restore validation and preview cannot start without a source backup. | Select backup set. | required | no | Source backup pending; operation proof unavailable; post-run evidence unavailable. | Collapsed |
| Backup selected with no captured/restorable items | Source not usable | Selected backup contains no captured restorable items. | Restore validation cannot prove a usable restore source. | Select another backup set. | blocked | no | Source backup selected but unusable; no execution or recovery proof. | Collapsed |
| Backup selected and usable with quality/dependency issues | Source selected, review required | Source backup is usable but contains quality or dependency issues. | Validation and preview must resolve these issues before execution. | Continue to scope and resolve required mappings. | warning | yes, to scope only | Source backup usable; input quality caveat; no execution or recovery proof. | Collapsed |
| Backup selected and clean | Source selected | A usable source backup is selected. | Restore scope and validation can continue. | Continue to scope. | complete | yes | Source backup selected and input quality shown; no execution or recovery proof. | Collapsed |

Step 1 default layout:

- Restore Safety decision card
- Backup set selector
- Backup quality summary
- Full Restore Safety Gates flow
- Restore Proof panel
- Diagnostics collapsed

Step 1 must not show tenant-wide recoverability, technical startability, write-gate, hard-blocker, or claims that Graph works again.

## Step 2 - Define Restore Scope

| State | Visible status | Reason | Impact | Primary next action | Gate state | Can continue? | Proof claims allowed? | Diagnostics |
|---|---|---|---|---|---|---|---|---|
| Scope not defined | Scope required | Select all items or selected items before validation. | Validation cannot prove an undefined restore draft. | Define restore scope. | required | no | Source proof may be available; scope proof pending. | Collapsed |
| All items in scope, no mappings required | Scope ready | All restorable items remain in scope and no unresolved mappings are detected. | Validation can run for the current draft. | Run safety checks. | complete | yes | Scope selected; dependency mapping not required; no execution/recovery proof. | Collapsed |
| Selected items in scope, no mappings required | Scope ready | Selected restore items define the current draft and no unresolved mappings are detected. | Validation can run for the selected scope. | Run safety checks. | complete | yes | Scope selected; no execution/recovery proof. | Collapsed |
| Required mappings unresolved | Dependency mappings required | Target mappings are unresolved for the current draft. | Validation cannot prove the current draft until required mappings are resolved or explicitly skipped where allowed. | Resolve mappings. | blocked | no | Source and scope may be selected; dependency proof pending. | Collapsed |
| Mappings resolved | Dependency mappings resolved | Required target mappings are resolved or explicitly skipped where allowed. | Validation can run for the current draft. | Run safety checks. | complete | yes | Mapping decision recorded for draft; no execution/recovery proof. | Collapsed |
| Resolver expanded | Resolve target mappings | Operator explicitly opened mapping details. | Row-level mapping decisions are visible for review. | Select target group, enter manual object ID, or skip where supported. | required or complete by row | no while unresolved | Source/target display names and IDs as metadata; no execution/recovery proof. | Row details visible; raw payloads hidden |
| Group picker has current-environment results | Target group selection available | Cached directory groups exist for this environment. | Operator can choose a target group from cache. | Select target group. | required | returns to resolver | Cache availability only; no proof of execution safety. | Table visible |
| Group picker cache empty | No directory group cache available | TenantPilot needs cached directory groups before target mappings can be selected. | Cached target selection cannot proceed until group sync runs, unless manual fallback is supported. | Open group sync or enter object ID manually. | blocked or fallback | no cached selection | Cache unavailable; manual fallback allowed only as explicit fallback. | Empty state visible |

Step 2 default layout:

- Define restore scope card
- Scope options
- Scope impact summary
- Restore dependency mapping summary
- Resolve mappings action
- Compact Restore Safety Status
- Restore Proof panel
- Diagnostics collapsed

Step 2 default hidden content:

- full mapping details
- 20+ raw mapping fields
- full seven-gate safety flow
- repeated GUID helper text
- raw IDs as primary source labels

Mapping row identity:

- Source group display name first
- Source ID secondary
- Target group display name first when cached target selected
- Target ID secondary
- Manual fallback badge if GUID entered manually
- Skipped state if intentionally skipped

Allowed fallback:

- Unknown source group
- Source ID: `{id}`

Forbidden primary labels:

- raw GUID only
- `Unresolved (...id)`
- state label as group name
- `SKIP` as primary UX

## Step 3 - Validate

| State | Visible status | Reason | Impact | Primary next action | Gate state | Can continue? | Proof claims allowed? | Diagnostics |
|---|---|---|---|---|---|---|---|---|
| No checks run | Validation required | Run checks after scope and required mappings are complete. | Preview and execution remain unavailable until validation runs. | Run safety checks. | required | no | Validation not recorded; no preview/execution proof. | Collapsed |
| Provider credentials missing | Validation blocked | Provider credentials are not available for this environment. | Restore checks cannot run until provider connection is repaired. | Review provider connection. | blocked | no | Provider readiness currently prevents checks; no raw provider exception. | Collapsed |
| Checks finished with blockers | Validation blocked | Resolve blocking validation checks before preview. | Preview or execution cannot be trusted while blockers remain. | Review blockers. | blocked | no | Validation ran and blockers exist; no execution/recovery proof. | Blockers visible; raw details collapsed |
| Checks passed with warnings | Validation ready with warnings | Validation completed, but warnings require review before confirmation. | Preview can continue; execution remains gated by confirmation. | Review preview. | warning | yes | Validation complete with warnings; no execution/recovery proof. | Warnings visible; raw details collapsed |
| Checks passed cleanly | Validation ready | Required validation checks completed for the current scope. | Preview can be reviewed before confirmation. | Review preview. | complete | yes | Validation complete; no execution/recovery proof. | Safe checks compact |

Step 3 must not show:

- `Safety checks completed` when blockers exist
- `Graph works again`
- `Technical startability`
- `write-gate`
- `hard-blocker`
- raw provider credential exception
- raw Graph exception

Product-safe provider wording:

`Provider readiness or restore prerequisites currently prevent real execution.`

## Step 4 - Preview

| State | Visible status | Reason | Impact | Primary next action | Gate state | Can continue? | Proof claims allowed? | Diagnostics |
|---|---|---|---|---|---|---|---|---|
| Validation incomplete | Preview unavailable | Run validation before generating preview. | Preview cannot be trusted without current validation. | Run safety checks. | blocked | no | No preview proof. | Collapsed |
| Validation blockers exist | Preview blocked | Resolve blockers before preview can be generated. | Preview cannot proceed while blockers remain. | Review blockers. | blocked | no | No trusted preview proof. | Collapsed |
| Preview not generated | Preview required | Generate a normalized preview before confirmation. | Confirmation remains unavailable until preview is current. | Generate preview. | required | no | Validation may be complete; preview proof unavailable. | Collapsed |
| Preview generated with needs attention | Preview ready with review items | Preview is current and items require review. | Operator must review needs attention before confirmation. | Review preview and complete confirmation. | warning | yes if execution prerequisites allow | Current preview proof exists; no execution/recovery proof. | Needs attention visible; raw diff collapsed |
| Preview generated cleanly | Preview ready | Preview is current for the selected scope. | Confirmation is the next gate before execution can be queued. | Complete confirmation. | complete | yes if execution prerequisites allow | Current preview proof exists; no execution/recovery proof. | Details collapsed |
| Preview current but execution prerequisites unavailable | Preview ready, confirmation reviewable | Preview is current but real execution prerequisites are not available. | Confirmation can be reviewed, but real execution remains unavailable until prerequisites are resolved. | Review preview and continue to confirmation; resolve execution prerequisites before executing. | warning | yes, to confirmation only | Preview proof exists; execution proof unavailable. | Collapsed |

Preview decision summary must show:

- Total items reviewed
- Items changed
- Items unchanged
- Items requiring review
- Assignments changed
- Scope tags changed
- Blockers
- Warnings
- Next gate

Preview grouping order:

1. Needs attention
2. Changes detected
3. No changes detected
4. All reviewed items

Preview must not render by default:

- every restore item as a large card
- 100+ item cards
- raw diff JSON
- raw provider payload
- repeated `Policy change preview` label for every item

## Step 5 - Confirm & Execute

| State | Visible status | Reason | Impact | Primary next action | Gate state | Can continue? | Proof claims allowed? | Diagnostics |
|---|---|---|---|---|---|---|---|---|
| Required gates incomplete | Confirmation unavailable | Required mappings, validation, preview, or prerequisites are incomplete. | Execution cannot be queued. | Complete required gate. | blocked | no | Operation proof unavailable; post-run evidence unavailable. | Collapsed |
| Preview-only/dry-run selected | Preview-only ready | Operator is creating a preview-only restore run. | No real provider write will be queued from this state. | Create preview-only restore run. | complete for dry-run | yes if form valid | Preview-only intent; no execution/recovery proof. | Collapsed |
| Execution prerequisites ready, acknowledgement missing | Confirmation required | Execution requires explicit acknowledgement and typed confirmation where supported. | Real execution remains unavailable until confirmation is satisfied. | Acknowledge impact and type confirmation. | required | no | Operation proof unavailable; post-run evidence unavailable. | Collapsed |
| Confirmation satisfied | Ready to queue execution | Required gates are complete and operator confirmation is satisfied. | Real execution can be queued if RBAC/capability permits. | Create restore run / queue execution. | complete | yes | Execution intent may be queued; recovery still not verified until post-run evidence exists. | Collapsed |
| Actor lacks capability | Execution unavailable | Current actor is not permitted to execute restore. | Execution cannot be queued for this actor. | Review permissions or keep preview-only. | blocked | no for execution | No execution proof or recovery proof. | Collapsed |

Required safety copy before execution:

- Operation proof unavailable before execution.
- Post-run evidence unavailable before execution.
- Recovery is not verified until post-run evidence exists.

Forbidden pre-execution claims:

- Recovery verified
- Execution proof complete
- Post-run evidence available
- Customer-safe
- Healthy
- Fully restored

Execution availability requires:

- required mappings resolved or allowed skipped
- validation not blocked
- preview current
- confirmation satisfied
- RBAC/capability permits execution

## Restore Proof Panel Contract

Restore Proof is not the process flow. It shows proof basis:

| Proof item | Allowed pre-execution state | Allowed post-execution state only if repo-supported | Forbidden claim |
|---|---|---|---|
| Source backup | Selected / Available / Needs review / Blocked | N/A | source proves recovery |
| Target environment | Selected / Available | N/A | target is healthy |
| Requested by | Recorded / Unavailable | N/A | user approval beyond current action |
| Restore scope | Selected / Needs review / Blocked | N/A | scope is safe to execute without validation |
| Operation proof | Unavailable before execution | Available only after existing execution proof exists | execution proof complete before execution |
| Post-run evidence | Unavailable before execution | Available / Unavailable only after existing repo-supported result evidence exists | recovery verified before evidence |
| Diagnostics | Collapsed | Collapsed / support-gated | raw proof shown by default |

Allowed states:

- Available
- Unavailable
- Recorded
- Selected
- Needs review
- Blocked
- Collapsed

## Restore Safety Status Contract

| Step | Default safety display | Full gates visible by default? | Expansion behavior |
|---|---|---|---|
| Step 1 | Full Restore Safety Gates | yes | N/A |
| Step 2 | Compact Restore Safety Status | no | Full gates only after explicit `View safety gates` |
| Step 3 | Compact Restore Safety Status | no | Full gates only after explicit `View safety gates` |
| Step 4 | Compact Restore Safety Status | no | Full gates only after explicit `View safety gates` |
| Step 5 | Compact Restore Safety Status | no | Full gates only after explicit `View safety gates` |

Compact status must show:

- X of Y gates complete
- Next gate
- Execution state
- View safety gates

The UI must not show compact and full gates by default at the same time for Step 2+.

## Navigation / Context Contract

Actions that leave the wizard must preserve context or be clearly secondary:

| Action | Context rule | Target behavior |
|---|---|---|
| Open group sync | Use active workspace/environment; no hardcoded IDs | Open new tab if leaving wizard |
| View group sync operations | Use active workspace/environment and operation type filter if supported | Open new tab |
| Open provider connection | Use active environment provider connection route | Open new tab |
| Open operation proof | Use existing authorized OperationRun link | Open new tab if leaving wizard |
| Open evidence | Use existing authorized evidence link only if repo-supported | Open new tab |
| Open backup detail | Use existing authorized backup route only if repo-supported | Open new tab |

Rules:

- No hardcoded numeric workspace IDs.
- No 404 URLs.
- Use active workspace/environment context.
- Label actions task-specifically.
- Avoid generic primary CTAs such as `Operations`.

## Forbidden Default Copy

Default Restore Create UI must not show:

- `Graph works again`
- `Technical startability`
- `write-gate`
- `hard-blocker`
- raw provider credential exception
- raw Graph exception
- tenant as platform context when environment is meant
- recovery verified before post-run evidence
- execution proof complete before execution
- post-run evidence available before execution
- customer-safe/healthy/fully restored before proof exists