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