ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
176-backup-quality-truth
TenantAtlas/specs/181-restore-safety-integrity/tasks.md
ahmido a107e7e41b feat: restore safety integrity and queue slide-over (#210) 
## Summary
- add the Spec 181 restore-safety layer with scope fingerprinting, preview/check integrity states, execution safety snapshots, result attention, and operator-facing copy across the wizard, restore detail, and canonical operation detail
- add focused unit and feature coverage for restore-safety assessment, result attention, and restore-linked operation detail
- switch the finding exceptions queue `Inspect exception` action to a native Filament slide-over while preserving query-param-backed inline summary behavior

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

## Notes
- Spec 181 checklist is complete (`specs/181-restore-safety-integrity/checklists/requirements.md`)
- the branch still has unchecked follow-up tasks in `specs/181-restore-safety-integrity/tasks.md`: `T012`, `T018`, `T019`, `T023`, `T025`, `T029`, `T032`, `T033`, `T041`, `T042`, `T043`, `T044`
- Filament v5 / Livewire v4 compliance is preserved, no panel provider registration changes were made, no global-search behavior was added, destructive actions remain confirmation-gated, and no new Filament assets were introduced

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #210
2026-04-06 23:37:14 +00:00

20 KiB
Raw Permalink Blame History

Tasks: Restore Safety Integrity

Input: Design documents from /specs/181-restore-safety-integrity/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are REQUIRED for this feature. Use focused Pest coverage in tests/Feature/RestoreRunWizardExecuteTest.php, tests/Feature/RestoreRiskChecksWizardTest.php, tests/Feature/Filament/RestorePreviewTest.php, tests/Feature/Filament/RestoreRunUiEnforcementTest.php, tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php, tests/Feature/RestoreAuditLoggingTest.php, tests/Feature/ExecuteRestoreRunJobTest.php, tests/Feature/RestorePreviewDiffWizardTest.php, existing ops-UX constitution and notification guards under tests/Feature/OpsUx/, and new restore-safety tests under tests/Feature/Filament/, tests/Feature/Operations/, and tests/Unit/Support/RestoreSafety/. Operations: This feature reuses existing RestoreRun and OperationRun execution records. No new run type, lifecycle transition owner, terminal notification flow, or summary_counts producer is introduced; work is limited to restore-specific safety truth and canonical-detail continuity for existing restore.execute runs. RBAC: Existing tenant membership, tenant-manage capability gating, capability-registry usage, and 404 vs 403 semantics must remain unchanged across /admin/t/{tenant}/restore-runs/... and /admin/operations/{run}. Tests must cover both positive and negative access paths. Operator Surfaces: The restore wizard must show scope, integrity, execution readiness, and one corrective next step before raw preview or check details. The restore detail surface must elevate follow-up truth and next action above raw result lists. The canonical operation detail must keep restore-specific follow-up truth visible or safely linked. Filament UI Action Surfaces: No new list, bulk, or destructive actions are introduced. Existing rerun, restore, archive, and force-delete actions remain confirmation-gated and server-authorized; the wizard remains the only primary execution surface. Filament UI UX-001: The create flow remains a Filament wizard with sectioned steps, and the restore detail remains an infolist-based read surface. New safety messaging must be summary-first and diagnostics-second. Badges: Any new integrity, safety, or result-attention badge states must route through existing centralized restore badge semantics in app/Support/Badges/Domains/.

Organization: Tasks are grouped by user story so each story can be implemented and validated as an independent increment after the shared restore-safety scaffolding is in place.

Phase 1: Setup (Shared Restore-Safety Scaffolding)

Purpose: Add the narrow shared restore-safety types and test scaffolding used by every story.

  • T001 Create the shared restore-safety value objects in app/Support/RestoreSafety/RestoreScopeFingerprint.php, app/Support/RestoreSafety/PreviewIntegrityState.php, app/Support/RestoreSafety/ChecksIntegrityState.php, and app/Support/RestoreSafety/ExecutionReadinessState.php
  • T002 [P] Create the shared decision-layer types in app/Support/RestoreSafety/RestoreSafetyAssessment.php, app/Support/RestoreSafety/RestoreExecutionSafetySnapshot.php, and app/Support/RestoreSafety/RestoreResultAttention.php
  • T003 Create the central restore-safety resolver with explicit invalidate_after_mutation freshness handling and legacy-stale classification in app/Support/RestoreSafety/RestoreSafetyResolver.php
  • T004 [P] Add unit test scaffolding for the new restore-safety namespace, including current vs invalidated vs legacy stale classification, in tests/Unit/Support/RestoreSafety/RestoreScopeFingerprintTest.php, tests/Unit/Support/RestoreSafety/RestoreSafetyAssessmentTest.php, and tests/Unit/Support/RestoreSafety/RestoreResultAttentionTest.php

Phase 2: Foundational (Blocking Shared Wiring)

Purpose: Wire the shared restore-safety contract into existing restore models, badges, and Filament resource seams before story-specific behavior changes.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

  • T005 Extend restore-run basis and snapshot helpers in app/Models/RestoreRun.php
  • T006 [P] Add centralized integrity and result-attention badge mappings in app/Support/Badges/Domains/RestorePreviewDecisionBadge.php, app/Support/Badges/Domains/RestoreCheckSeverityBadge.php, and app/Support/Badges/Domains/RestoreResultStatusBadge.php
  • T007 Thread shared restore-safety page-model inputs through app/Filament/Resources/RestoreRunResource.php and app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php
  • T008 [P] Add shared helper and badge regression coverage in tests/Unit/RestoreRunTest.php, tests/Unit/Badges/RestoreUiBadgesTest.php, and tests/Unit/Badges/RestoreRunBadgesTest.php

Checkpoint: Restore pages can now consume one shared safety contract for wizard, detail, and monitoring surfaces.

Phase 3: User Story 1 - Decide Whether Real Execution Is Responsible (Priority: P1) 🎯 MVP

Goal: Make the wizard distinguish current decision evidence, technical startability, and actual safety readiness before real execution is offered calmly.

Independent Test: Open the restore wizard, generate or omit checks and preview, and verify the confirm step clearly separates current safe readiness from mere technical startability and warning-suppressed caution.

Tests for User Story 1

  • T009 [P] [US1] Extend confirm-step execution gating coverage for current evidence, missing evidence, and warning suppression in tests/Feature/RestoreRunWizardExecuteTest.php
  • T010 [P] [US1] Add wizard safety-state rendering coverage for not_generated, current, risky, and ready_with_caution scenarios in tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php

Implementation for User Story 1

  • T011 [US1] Compute preview integrity, checks integrity, execution readiness, and safety readiness in app/Filament/Resources/RestoreRunResource.php
  • T012 [US1] Enforce current fingerprint, current evidence, and hard-confirm validation before real execution queues in app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
  • T013 [US1] Render checks integrity state and one corrective next step in resources/views/filament/forms/components/restore-run-checks.blade.php
  • T014 [US1] Render preview basis truth, generated-at context, and calmness suppression in resources/views/filament/forms/components/restore-run-preview.blade.php
  • T015 [US1] Persist execution-time safety snapshot data for real restore submissions in app/Models/RestoreRun.php and app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
  • T016 [US1] Run the focused wizard safety regression pack in tests/Feature/RestoreRunWizardExecuteTest.php and tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php

Checkpoint: The wizard now answers whether the current scope is responsibly executable without collapsing warnings or missing evidence into a calm ready state.

Phase 4: User Story 2 - Notice Scope Drift Immediately (Priority: P1)

Goal: Make prior preview and checks visibly invalid when the selected restore scope changes, instead of silently falling back to a neutral state.

Independent Test: Generate preview and checks, change selected items, scope mode, backup set, or group mapping, and verify the wizard shows explicit invalidation with rerun guidance before calm execution is available again.

Tests for User Story 2

  • T017 [P] [US2] Extend scope-drift invalidation coverage for selected items, scope mode, backup set, and group mapping mutations in tests/Feature/RestoreRiskChecksWizardTest.php
  • T018 [P] [US2] Add basis-persistence and invalidation-reason coverage for prior preview and checks evidence in tests/Feature/RestoreRunWizardMetadataTest.php
  • T019 [P] [US2] Add stale-versus-invalidated start-gate regressions in tests/Feature/Hardening/RestoreStartGateStaleTest.php and tests/Feature/Hardening/RestoreStartGateUnhealthyTest.php

Implementation for User Story 2

  • T020 [US2] Preserve last-known preview and checks basis plus invalidation reasons when scope-affecting inputs change in app/Filament/Resources/RestoreRunResource.php
  • T021 [US2] Store comparison-ready scope, preview, and checks basis payloads on draft and persisted restore runs in app/Models/RestoreRun.php
  • T022 [US2] Render explicit stale and invalidated guidance instead of silent fallback in resources/views/filament/forms/components/restore-run-checks.blade.php and resources/views/filament/forms/components/restore-run-preview.blade.php
  • T023 [US2] Run the focused scope-drift regression pack in tests/Feature/RestoreRiskChecksWizardTest.php, tests/Feature/RestoreRunWizardMetadataTest.php, and tests/Feature/Hardening/RestoreStartGateStaleTest.php

Checkpoint: Scope changes now invalidate prior safety work visibly and suppress calm execution messaging until the evidence is regenerated.

Phase 5: User Story 3 - Interpret Restore Results Without Overclaiming Recovery (Priority: P2)

Goal: Make restore detail tell operators what the run meant, whether follow-up remains, and what to do next before showing raw item diagnostics.

Independent Test: Open completed, partial, failed, and completed-with-follow-up restore runs and verify the first visible detail section communicates result truth, follow-up truth, cause family, and one primary next action without implying tenant recovery.

Tests for User Story 3

  • T024 [P] [US3] Add result-attention coverage for completed, partial, failed, and completed-with-follow-up restore runs in tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php
  • T025 [P] [US3] Extend restore detail rendering assertions for basis truth and non-calm result messaging in tests/Feature/Filament/RestorePreviewTest.php

Implementation for User Story 3

  • T026 [US3] Build the restore result-attention page model from results, assignment outcomes, and execution snapshot data in app/Filament/Resources/RestoreRunResource.php
  • T027 [US3] Show preview-basis and checks-basis truth on the detail surface in resources/views/filament/infolists/entries/restore-preview.blade.php
  • T028 [US3] Elevate follow-up truth, cause family, and one primary next action above raw item lists in resources/views/filament/infolists/entries/restore-results.blade.php
  • T029 [US3] Preserve non-overclaiming restore wording for completed and partial outcomes in app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php and app/Support/Badges/Domains/RestoreResultStatusBadge.php
  • T030 [US3] Run the focused restore detail regression pack in tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php and tests/Feature/Filament/RestorePreviewTest.php

Checkpoint: Restore detail now communicates execution outcome and open follow-up work without overstating recovery certainty.

Phase 6: User Story 4 - Preserve Restore Truth In Canonical Run Monitoring (Priority: P3)

Goal: Keep restore-specific follow-up truth visible or safely reachable from the canonical operation detail page for restore-linked runs.

Independent Test: Open restore-linked operation runs from monitoring and restore surfaces and verify restore follow-up truth is visible or reachable within one click, with safe degradation when deeper restore access is unavailable.

Tests for User Story 4

  • T031 [P] [US4] Add restore-linked canonical detail coverage for visible follow-up truth and safe deep-link behavior in tests/Feature/Operations/RestoreLinkedOperationDetailTest.php
  • T032 [P] [US4] Extend restore execution sync coverage so canonical monitoring preserves restore continuation context in tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php
  • T033 [P] [US4] Extend RBAC-safe degradation coverage for restore-linked operation access and denied restore deep links in tests/Feature/Filament/RestoreRunUiEnforcementTest.php

Implementation for User Story 4

  • T034 [US4] Enrich restore-linked restore.execute operation detail payloads with restore continuation truth in app/Filament/Resources/OperationRunResource.php
  • T035 [US4] Render safe restore-detail navigation and entitled degradation states on canonical monitoring pages in app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • T036 [US4] Run the focused canonical continuation regression pack in tests/Feature/Operations/RestoreLinkedOperationDetailTest.php, tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php, and tests/Feature/Filament/RestoreRunUiEnforcementTest.php

Checkpoint: Canonical operation detail now preserves restore meaning instead of flattening the run to generic telemetry alone.

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Final consistency, formatting, and focused verification across all stories.

  • T037 [P] Review and align operator-facing restore safety copy in app/Filament/Resources/RestoreRunResource.php, app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php, resources/views/filament/forms/components/restore-run-checks.blade.php, resources/views/filament/forms/components/restore-run-preview.blade.php, and resources/views/filament/infolists/entries/restore-results.blade.php
  • T038 [P] Run shared helper and badge verification in tests/Unit/Support/RestoreSafety/RestoreScopeFingerprintTest.php, tests/Unit/Support/RestoreSafety/RestoreSafetyAssessmentTest.php, tests/Unit/Support/RestoreSafety/RestoreResultAttentionTest.php, and tests/Unit/Badges/RestoreUiBadgesTest.php
  • T039 Run formatting with vendor/bin/sail bin pint --dirty --format agent as required by specs/181-restore-safety-integrity/quickstart.md
  • T040 Run the final focused verification pack from specs/181-restore-safety-integrity/quickstart.md against tests/Feature/RestoreRunWizardExecuteTest.php, tests/Feature/RestoreRiskChecksWizardTest.php, tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php, tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php, tests/Feature/Operations/RestoreLinkedOperationDetailTest.php, and tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php
  • T041 [P] Extend invalidation audit-derivability coverage in tests/Feature/RestoreAuditLoggingTest.php and tests/Feature/RestoreRunWizardMetadataTest.php
  • T042 [P] Extend restore execution and preview-diff non-regression coverage in tests/Feature/ExecuteRestoreRunJobTest.php and tests/Feature/RestorePreviewDiffWizardTest.php
  • T043 [P] Run ops-UX constitution and notification guard coverage in tests/Feature/OpsUx/Constitution/DirectStatusTransitionGuardTest.php, tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php, tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php, tests/Feature/OpsUx/OperationRunSummaryCountsIncrementTest.php, tests/Feature/OpsUx/Regression/RestoreRunTerminalNotificationTest.php, tests/Feature/OpsUx/NotificationViewRunLinkTest.php, and tests/Feature/OpsUx/QueuedToastCopyTest.php
  • T044 Run the manual validation pass in specs/181-restore-safety-integrity/quickstart.md to verify the 15-second and one-click operator success criteria

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): Starts immediately and establishes the shared restore-safety types.
  • Foundational (Phase 2): Depends on Setup and blocks all story work until restore models, badges, and resource seams consume the shared contract.
  • User Story 1 (Phase 3): Starts after Foundational and delivers the first operator-safe execution decision surface.
  • User Story 2 (Phase 4): Starts after Foundational and should follow User Story 1 closely because it reuses the same wizard safety contract while hardening scope invalidation.
  • User Story 3 (Phase 5): Starts after Foundational and depends on the shared execution-snapshot and result-attention contract introduced in earlier phases.
  • User Story 4 (Phase 6): Starts after User Story 3 because canonical monitoring reuses restore result-attention truth.
  • Polish (Phase 7): Starts after the desired user stories are complete.

User Story Dependencies

  • US1: Depends only on Setup and Foundational work.
  • US2: Depends on Setup and Foundational work and should reuse the wizard safety contract delivered in US1.
  • US3: Depends on Setup and Foundational work plus the execution-snapshot plumbing from US1.
  • US4: Depends on Setup and Foundational work plus the restore result-attention contract from US3.

Within Each User Story

  • Tests should be added or updated before the corresponding behavior change is considered complete.
  • Shared resource and model wiring should land before Blade rendering tasks for the same story.
  • Story-level focused test runs should pass before moving to the next priority slice.

Parallel Opportunities

  • T002 and T004 can run in parallel after the core namespace shape from T001 is agreed.
  • T006 and T008 can run in parallel after T005 defines the shared restore-run basis helpers.
  • T009 and T010 can run in parallel for US1.
  • T017, T018, and T019 can run in parallel for US2.
  • T024 and T025 can run in parallel for US3.
  • T031, T032, and T033 can run in parallel for US4.
  • T037 and T038 can run in parallel once feature code is stable.
  • T041, T042, and T043 can run in parallel during final verification.

Parallel Example: User Story 1

# Story 1 tests in parallel:
Task: T009 tests/Feature/RestoreRunWizardExecuteTest.php
Task: T010 tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php

# Story 1 implementation split after expectations are locked:
Task: T011 app/Filament/Resources/RestoreRunResource.php
Task: T014 resources/views/filament/forms/components/restore-run-preview.blade.php

Parallel Example: User Story 2

# Story 2 regressions in parallel:
Task: T017 tests/Feature/RestoreRiskChecksWizardTest.php
Task: T018 tests/Feature/RestoreRunWizardMetadataTest.php
Task: T019 tests/Feature/Hardening/RestoreStartGateStaleTest.php

# Story 2 implementation split after invalidation rules are fixed:
Task: T020 app/Filament/Resources/RestoreRunResource.php
Task: T022 resources/views/filament/forms/components/restore-run-checks.blade.php

Parallel Example: User Story 3

# Story 3 tests in parallel:
Task: T024 tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php
Task: T025 tests/Feature/Filament/RestorePreviewTest.php

# Story 3 implementation split after attention-model assertions are clear:
Task: T026 app/Filament/Resources/RestoreRunResource.php
Task: T028 resources/views/filament/infolists/entries/restore-results.blade.php

Parallel Example: User Story 4

# Story 4 tests in parallel:
Task: T031 tests/Feature/Operations/RestoreLinkedOperationDetailTest.php
Task: T032 tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php
Task: T033 tests/Feature/Filament/RestoreRunUiEnforcementTest.php

# Story 4 implementation split after restore-continuation expectations are set:
Task: T034 app/Filament/Resources/OperationRunResource.php
Task: T035 app/Filament/Pages/Operations/TenantlessOperationRunViewer.php

Implementation Strategy

MVP First

  • Complete Phase 1 and Phase 2.
  • Deliver User Story 1 and User Story 2 as the minimum safe restore-decision slice.
  • Validate that the wizard now distinguishes current evidence, invalidated evidence, and warning-suppressed caution before real execution is offered calmly.

Incremental Delivery

  • Add User Story 3 next to harden restore detail truth and follow-up guidance.
  • Add User Story 4 last to preserve restore meaning on canonical monitoring without duplicating persistence.

Verification Finish

  • Run Pint on touched files.
  • Run the focused restore safety pack from quickstart.md.
  • Run the manual quickstart validation pass for the 15-second and one-click operator outcomes.
  • Offer the broader suite only after the focused pack passes.