TenantAtlas/specs/181-restore-safety-integrity/quickstart.md

Quickstart: Restore Safety Integrity

Goal

Validate that restore wizard, restore detail, and canonical operation detail now communicate restore safety truth without overstating calmness, scope validity, or recovery completion.

This slice uses freshness policy invalidate_after_mutation for preview and checks. Inside one active wizard draft, there is no separate age-based timeout; stale is reserved for legacy or incomplete persisted evidence, while invalidated is used for explicit scope drift after a covered mutation.

Prerequisites

1. Start Sail if it is not already running.
2. Ensure the workspace has representative restore fixtures for:
   • a scope with current checks and preview
   • a scope where preview or checks become invalid after a scope change
   • a scope with warnings but no blockers
   • a real restore run that ends completed
   • a real restore run that ends partial or completed_with_follow_up
   • a restore-linked OperationRun
3. Ensure the acting user is a valid workspace member and tenant member.
4. Ensure at least one lower-privilege user exists to verify 404 versus 403 and safe degradation.

Focused Automated Verification

Run the smallest restore-related suite first:

vendor/bin/sail artisan test --compact tests/Feature/RestoreRunWizardExecuteTest.php
vendor/bin/sail artisan test --compact tests/Feature/RestoreRiskChecksWizardTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/RestorePreviewTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/RestoreRunUiEnforcementTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php
vendor/bin/sail artisan test --compact tests/Feature/RestoreAuditLoggingTest.php
vendor/bin/sail artisan test --compact tests/Feature/ExecuteRestoreRunJobTest.php
vendor/bin/sail artisan test --compact tests/Feature/RestorePreviewDiffWizardTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/Constitution/DirectStatusTransitionGuardTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/OperationRunSummaryCountsIncrementTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/Regression/RestoreRunTerminalNotificationTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/NotificationViewRunLinkTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/QueuedToastCopyTest.php

Expected new or expanded spec-scoped tests:

vendor/bin/sail artisan test --compact tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Operations/RestoreLinkedOperationDetailTest.php
vendor/bin/sail artisan test --compact tests/Unit/Support/RestoreSafety/

Use --filter for a smaller pass while iterating.

Manual Validation Pass

1. Establish current preview and checks

Open /admin/t/{tenant}/restore-runs/create and:

• choose a backup set
• choose selected scope or keep all
• run checks
• generate preview

Confirm the page shows:

• what scope is currently selected
• when preview and checks were generated
• whether each basis is current
• the difference between execution readiness and safety readiness

2. Trigger explicit invalidation

After preview and checks exist, change one scope-defining input:

• selected items
• scope mode
• group mapping
• backup set

Confirm the page no longer behaves like preview and checks were never run.

It must clearly show:

• previous preview or checks were invalidated by the change
• rerun is required
• calm execution language is suppressed

3. Verify warning suppression

Use a scope with warnings but no blockers and confirm:

• the restore may still be technically executable
• the page does not say safe, ready, or looks good in a calm way
• the operator sees one primary cautionary next step

4. Verify real execution confirmation

On the final wizard step, confirm that real execution requires:

• current checks
• current preview
• matching scope fingerprint
• hard-confirm inputs
• passing execution readiness

If any of those conditions fail, confirm the page prefers corrective guidance over calm execute messaging.

5. Verify result truth after execution

Open the restore-run detail page and confirm the first visible area answers:

• what completed
• what only partially completed
• whether follow-up is still required
• what the primary next action is
• that completed does not imply tenant recovered

6. Verify canonical operation continuity

Open the linked canonical operation detail and confirm:

• restore-specific follow-up truth is visible or reachable in one click
• the page does not reduce restore meaning to generic operation telemetry alone
• unauthorized deeper links are suppressed or explained safely

Non-Regression Checks

Confirm the feature did not change:

• tenant route and canonical route identity
• 404 versus 403 semantics for restore surfaces and linked operation surfaces
• existing write-gate and execution authorization behavior
• OperationRun lifecycle ownership and sync behavior
• existing archive, restore, rerun, and force-delete confirmation behavior
• render-time prohibition on new external calls for detail surfaces

Formatting And Final Verification

Before finalizing implementation work:

vendor/bin/sail bin pint --dirty --format agent

Then rerun the smallest affected test set and offer the full suite only after the focused restore safety pack passes.

Close the feature only after the manual validation confirms:

• operators can identify the next safe action within 15 seconds on the wizard and result surfaces
• restore-specific follow-up truth is visible or reachable from canonical operation detail within one click