ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a5b7300ca9
TenantAtlas/specs/390-restore-readiness-resolution-adapter-v1/plan.md
ahmido c0c3286a80 feat: add restore readiness resolution adapter improvements (#461) 
Automated PR created by Codex via Gitea API.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #461
2026-06-20 12:51:12 +00:00

16 KiB
Raw Blame History

Implementation Plan: Restore Readiness Resolution Adapter v1

Branch: 390-restore-readiness-resolution-adapter-v1 Spec: specs/390-restore-readiness-resolution-adapter-v1/spec.md Created: 2026-06-20 Mode: Mode B - Restore-local guidance on existing Restore surfaces

Summary

Implement a Restore-owned readiness adapter that derives decision-first guidance from existing Restore state and shows the operator the next safe preparation or inspection action. The adapter must reuse existing RestoreRun, RestoreSafetyResolver, Restore Preview, confirmation, OperationRun, tenant scoping, and Filament surfaces.

The v1 implementation must not create a generic resolution engine, adapter registry, new persistence table, global search surface, or automatic execution path. Persisted generic resolution cases are deferred because current repo truth shows only review-publication-specific resolution persistence.

Technical Context

Language/Version: PHP 8.4.15 Framework: Laravel 12.52.0 Admin UI: Filament 5.2.1 Reactive UI: Livewire 4.1.4 Testing: Pest 4.3.1 / PHPUnit 12 Database: PostgreSQL Local dev: Laravel Sail first Package constraints: Do not add dependencies without explicit approval.

Relevant existing code:

  • apps/platform/app/Models/RestoreRun.php
  • apps/platform/app/Support/RestoreSafety/RestoreSafetyResolver.php
  • apps/platform/app/Support/RestoreRunStatus.php
  • apps/platform/app/Filament/Resources/RestoreRunResource.php
  • apps/platform/app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
  • apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php
  • apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php
  • apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php
  • apps/platform/app/Support/Auth/Capabilities.php

Relevant completed context specs:

  • specs/386-review-publication-resolution-workflow-v1/
  • specs/387-review-publication-resolution-decision-ux-v1/
  • specs/388-resolution-proof-currentness-contract-v1/
  • specs/389-governance-inbox-resolution-intake-v1/

These specs inform the decision-first pattern only. Their completed artifacts and review-publication persistence must not be rewritten.

Constitution Check

  • Workspace first: Pass. Guidance is scoped to existing workspace/tenant/environment RestoreRun surfaces.
  • RBAC first: Pass with implementation requirement. View guidance must require view access; mutating preparation actions must require manage access server-side.
  • Audit first: Pass with implementation requirement. User-triggered preparation mutations must preserve existing operation/audit evidence paths.
  • Restore safety: Pass. Execution remains controlled by existing safety gates, confirmation, and OperationRun execution truth.
  • Spec before code: Pass. This plan and tasks define implementation boundaries before app code changes.
  • Proportionality review: Pass. New local state/action contracts are allowed; new persistence and generic frameworks are not.

Filament v5 / Livewire v4 Compliance Plan

  • Filament work must use Filament v5 APIs only.
  • Livewire v4.0+ is required and present.
  • Laravel 11+ panel providers must remain registered through bootstrap/providers.php; this feature does not require a new panel provider.
  • RestoreRunResource already has a View page, satisfying the global-search hard rule if it remains globally searchable. If implementation touches global search behavior, explicitly verify or disable search.
  • Destructive actions must use Action::make(...)->action(...) plus ->requiresConfirmation(). This feature should not add destructive actions.
  • Navigation-only actions must use ->url(...) and must not be described as confirmed modal actions unless Filament v5 docs are verified.
  • No new heavy global assets are planned. If assets are registered despite this plan, deploy must run cd apps/platform && php artisan filament:assets.
  • Test pages/widgets/actions as Livewire components, not static resource classes.

UI / Productization Guardrails

The feature touches existing operational UI, not marketing or landing content.

Required UI behavior:

  • Use compact decision-first copy that fits existing Filament panel density.
  • Keep Restore Wizard as the preparation input owner.
  • Keep Restore Preview as the preview owner.
  • Keep RestoreRun View as a status/evidence inspection surface, not a new workflow hub.
  • Keep OperationRun links as evidence links only.
  • Avoid a top-level dashboard, nav item, global search result, or notification center integration.
  • Avoid visible instructional walls of text.
  • Avoid implying that a preparation action executes or approves a restore.

UI coverage to update during implementation if the visible surface materially changes:

  • Durable UI/productization coverage registry artifacts under docs/ui-ux-enterprise-audit/ for the changed RestoreRun create/view surfaces.
  • Existing UI coverage/report for RestoreRun create/view where those artifacts exist.
  • docs/ui-ux-enterprise-audit/target-experience-briefs/restore-safety-workflow.md if existing documentation requires alignment, or an explicit checked target-brief no-change note inside the coverage update.
  • Browser smoke notes for blocked, stale, ready, and read-only states.

Do not claim No UI surface impact for this feature unless the spec is updated first with a checked rationale. The default implementation path is to update UI coverage artifacts because RestoreRun create/view behavior changes.

Shared Pattern and System Fit

This feature may introduce a Restore-specific support namespace, for example:

  • apps/platform/app/Support/RestoreReadinessResolution/

Allowed local contracts:

  • Restore readiness summary value object.
  • Restore reason/action identifiers.
  • Restore next-action planner.
  • Restore guidance basis/fingerprint helper.
  • Restore presenter adapter that converts readiness summaries into Filament-safe display data.

Disallowed contracts:

  • Generic ActionResolution model or table.
  • Generic adapter registry.
  • Generic status taxonomy shared across unrelated domains.
  • Review-publication resolution persistence reuse.
  • Provider-specific Graph execution logic in the readiness layer.

Data Model / Storage Plan

No database migration is expected.

Implementation must use existing persisted data:

  • restore_runs.requested_items
  • restore_runs.preview
  • restore_runs.results
  • restore_runs.metadata
  • restore_runs.group_mapping
  • restore_runs.operation_run_id
  • backup_sets
  • operation_runs

If implementation discovers that persistence is required to satisfy acceptance criteria, stop and update spec.md, plan.md, and tasks.md before creating any migration. The update must include a new proportionality review and rollback/forward plan.

OperationRun UX Impact

OperationRun remains execution/evidence truth.

Implementation must:

  • Reuse the central OperationRun Start UX Contract for any OperationRun-linked evidence or operation-entry affordance.
  • Reuse existing OperationRun links/presenters where available.
  • Show queued/running RestoreRun states as execution states, not preparation states.
  • Avoid creating OperationRun records from the readiness guidance layer.
  • Avoid queuing database notifications from the readiness guidance layer. Queued/terminal notifications remain owned by the existing lifecycle mechanism unless this spec is updated first.
  • Avoid duplicate operation status rendering that conflicts with existing OperationRun UX.
  • Treat this feature as deep-link/inspect-only for OperationRun. It must not create, queue, deduplicate, resume, block, or complete OperationRun records.

Provider Boundary

The touched seam is platform-core presentation over existing RestoreRun, BackupSet, RestoreSafetyResolver, and OperationRun data. Provider-owned semantics remain inside existing Restore services, Graph contract registry, and provider integration seams.

The readiness adapter is provider-neutral within the current RestoreRun domain. It must not call Microsoft Graph directly and must not assume provider-specific restore capabilities beyond existing RestoreRun/BackupSet/preview data. Any provider-specific hotspot discovered during implementation must be resolved in-feature by keeping it behind existing provider-owned seams, or escalated as a follow-up spec if it would leak into platform-core contracts or vocabulary.

Provider expansion or provider-specific readiness plugins require a later spec.

Security and Authorization Plan

Implementation must:

  • Reuse existing workspace/tenant/environment scoping traits and policies used by RestoreRunResource.
  • Require tenant view capability for inspection.
  • Require tenant manage capability for existing Restore wizard mutating preparation actions.
  • Keep V1 readiness guidance passive. If a later implementation exposes a guidance-owned mutating action, reject stale actions server-side when the basis/fingerprint no longer matches.
  • Avoid leaking inaccessible backup payload details, environment names, or OperationRun links.
  • Preserve existing 403/404 distinction as used by existing RestoreRun pages.

Testing Plan

Unit Tests

Add focused tests for:

  • Readiness summary derivation for missing checks.
  • Readiness summary derivation for stale checks.
  • Readiness summary derivation for missing preview.
  • Readiness summary derivation for stale preview.
  • Ready state with current checks and preview.
  • Execution state for queued/running RestoreRun.
  • Historical state for completed/partial/failed/cancelled/aborted RestoreRun.
  • Deterministic next safe action ordering.
  • Basis/fingerprint mismatch handling.

Feature / Filament Tests

Add or update tests for:

  • RestoreRun create wizard guidance in blocked, stale, and ready states.
  • RestoreRun view guidance for persisted records.
  • Read-only user can inspect permitted readiness details but cannot invoke mutating preparation actions.
  • Manage user can invoke allowed preparation action through existing Restore action path.
  • Existing final execution still requires confirmation and safety gate inputs.
  • Global search hard rule remains satisfied or disabled if touched.

Browser Smoke

Use the repository browser smoke pattern if the UI change is visible:

  • Authorized manage user sees blocked guidance and next safe action.
  • Authorized manage user sees stale preview guidance.
  • Authorized manage user sees ready-for-confirmation guidance.
  • Read-only user sees inspection-only affordances.
  • No visible copy implies automatic execution.

Test Governance / Runtime Impact

Implementation must keep test scope proportional:

  • Unit lane proves Restore-local derivation and side-effect-free behavior.
  • Feature/Filament lane proves authorization, wizard/view rendering, stale-action rejection, and execution-gate preservation.
  • Browser lane is limited to feature-local visible workflow smoke for blocked, stale, ready, and read-only states.
  • Fixture/context setup must stay opt-in and use existing factories/helpers. Do not introduce broad provider/workspace/membership defaults.
  • No new heavy-governance test family is expected. If implementation creates one, stop and update the spec/plan/tasks first.
  • Query-count validation must compare the Restore create/view render against the pre-feature fixture baseline and stay within the spec budget.
  • Expected lane decision: keep. Escalate as document-in-feature only if measured runtime or fixture cost materially changes; use follow-up-spec for recurring structural cost.

Validation Commands

Preferred full validation:

cd apps/platform && ./vendor/bin/sail artisan test
cd apps/platform && ./vendor/bin/sail pint --dirty

Focused validation should be added to implementation notes once concrete test paths exist.

Project Structure

Expected implementation paths:

apps/platform/app/Support/RestoreReadinessResolution/
apps/platform/app/Filament/Resources/RestoreRunResource.php
apps/platform/app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php
apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php
apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php
apps/platform/tests/Unit/Support/RestoreReadinessResolution/
apps/platform/tests/Feature/Filament/
apps/platform/tests/Feature/Restore/

Spec-package implementation support artifacts to create during implementation:

specs/390-restore-readiness-resolution-adapter-v1/artifacts/current-restore-flow-inventory.md
specs/390-restore-readiness-resolution-adapter-v1/contracts/restore-readiness-state-matrix.md
specs/390-restore-readiness-resolution-adapter-v1/contracts/restore-requirement-map.md
specs/390-restore-readiness-resolution-adapter-v1/contracts/restore-ui-copy-contract.md

No expected paths:

apps/platform/database/migrations/*restore_readiness*
apps/platform/app/Models/*ResolutionCase*
apps/platform/app/Models/*ResolutionStep*
apps/platform/app/Support/ActionResolution/
apps/platform/app/Filament/Resources/*Resolution*

Implementation Phases

Phase 0 - Repo Verification

Verify current RestoreRun surfaces, policies, presenters, RestoreSafetyResolver methods, OperationRun link helpers, and test fixture patterns. Record findings in artifacts/current-restore-flow-inventory.md.

Phase 1 - Local Contracts

Define Restore-local readiness states, reasons, next-action identifiers, and copy rules. Record the state matrix, requirement map, and UI copy contract in spec-package contract files before app code changes.

Phase 2 - Readiness Derivation

Implement a side-effect-free readiness resolver/planner that consumes existing Restore state and safety resolver outputs. Unit test all state transitions and next-action priority.

Phase 3 - Stale Basis Protection

Implement a guidance basis/fingerprint helper and verify stale basis comparison. V1 does not expose guidance-owned mutating preparation actions; existing Restore wizard actions remain the mutation owners. Any future guidance-owned mutating action must reject stale attempts with a clear notification and no mutation.

Phase 4 - Create Wizard Integration

Integrate guidance into the existing RestoreRun create wizard/presenter without replacing the wizard. Keep controls compact and use existing action semantics.

Phase 5 - Persisted RestoreRun View Integration

Add local status/evidence guidance to the existing RestoreRun view page. Do not create persisted resolution cases.

Phase 6 - Authorization and Evidence

Verify view/manage split, OperationRun link access, and no data leakage for inaccessible related records.

Phase 7 - Validation

Run unit, feature, Filament, browser smoke, Pint, and static diff checks. Update coverage notes only where repo conventions require it.

Complexity Tracking

Potential complexity Status Mitigation
New state/reason family Accepted Keep Restore-local and documented in contracts.
Generic resolution persistence Rejected Defer to later spec.
Adapter registry Rejected Use direct Restore-local support classes.
Extra navigation/global search Rejected Existing Restore surfaces only.
Execution bypass risk Rejected Existing confirmation/safety gates remain mandatory.
UI sprawl Controlled Decision-first compact guidance only.

Deployment Plan

Default deployment impact:

  • No migration.
  • No environment variable.
  • No new queue worker.
  • No new scheduler.
  • No new storage volume.
  • No new global frontend asset.

Validation and rollout:

  • Validate in local Sail.
  • Validate on Staging before Production because Restore is an Intune-critical workflow.
  • Production promotion only after confirming no-auto-execute behavior, authorization behavior, and stale guidance rejection.

Stop Conditions

Stop implementation and update the spec before continuing if any of the following becomes necessary:

  • A new database table or migration.
  • A generic resolution case abstraction.
  • Reuse of review-publication resolution persistence for Restore.
  • A new global navigation or dashboard surface.
  • A new provider-specific restore backend.
  • Direct Microsoft Graph calls from readiness derivation.
  • Any execution path that bypasses existing final confirmation.