TenantAtlas/specs/335-restore-run-detail-post-execution-proof-productization/repo-truth-map.md

Spec 335 Repo Truth Map - Restore Run Detail / Post-Execution Proof

This file documents the repo-backed truth needed to productize the Restore Run detail/result/proof surface.

Legend:

• repo-verified: directly confirmed in code/migrations/tests in this repo
• derived from existing model: computed/derived from existing persisted fields
• foundation-real: persisted model exists, but linkage for this workflow may not be produced today
• not available: no repo-backed data exists today
• deferred: requires additional repo inspection before implementation

RestoreRun Model (repo-verified)

Source:

• apps/platform/app/Models/RestoreRun.php
• apps/platform/database/migrations/2025_12_10_000150_create_restore_runs_table.php
• apps/platform/database/migrations/2026_02_10_115908_add_operation_run_id_to_restore_runs_table.php

Key fields:

• managed_environment_id (tenant/environment)
• workspace_id (tenant-owned isolation)
• backup_set_id
• requested_by (nullable)
• is_dry_run (boolean; "preview-only")
• status (string, see RestoreRunStatus)
• requested_items (json array of backup item ids; nullable)
• preview (json; nullable)
• results (json; nullable)
• metadata (json; nullable)
• failure_reason (nullable)
• started_at / completed_at (nullable)
• operation_run_id (nullable; FK to operation_runs)

Relationships (repo-verified):

• $restoreRun->tenant() -> ManagedEnvironment via managed_environment_id
• $restoreRun->backupSet() -> BackupSet via backup_set_id (withTrashed)
• $restoreRun->operationRun() -> OperationRun via operation_run_id

RestoreRun Statuses (repo-verified)

Source:

• apps/platform/app/Support/RestoreRunStatus.php

Values:

• pre-execution/draft: draft, scoped, checked, previewed, pending
• execution: queued, running
• terminal: completed, partial, failed, cancelled
• legacy/compat: aborted, completed_with_errors

Implementation note:

• Spec 335 must map multiple persisted statuses into a smaller UI-facing decision model (derived), without inventing new persisted truth.

Restore Results Shape (repo-verified)

Primary persistence source:

• apps/platform/app/Services/Intune/RestoreService.php (result assembly + restore_runs.results + restore_runs.metadata)

Persisted shape:

• restore_runs.results is stored as:
  • results.foundations: list of foundation entries
  • results.items: map keyed by backup_item_id (values are item outcome arrays)

Counts / summary (repo-verified):

• restore_runs.metadata includes (at least):
  • total, succeeded, failed, skipped, partial, non_applied, foundations_skipped
  • scope_basis, check_basis, preview_basis (see RestoreRun helpers)
  • execution_safety_snapshot (used by result/preview surfaces)

Derived availability classification:

• Result summary counts: derived from existing model (from metadata)
• Item outcome table: derived from existing model (from results.items and related metadata)
• Summary counts and item rows are independent. If metadata counts exist but results.items is empty, the UI must label the state as metadata-only rather than implying zero affected items.

Restore Result Attention Contract (repo-verified)

Sources:

• apps/platform/app/Support/RestoreSafety/RestoreSafetyResolver.php (resultAttentionForRun)
• apps/platform/app/Support/RestoreSafety/RestoreResultAttention.php
• UI: apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php
• Tests: apps/platform/tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php

Contract fields (repo-verified):

• state in { not_executed, completed, partial, failed, completed_with_follow_up }
• summary
• primary_next_action
• primary_cause_family
• recovery_claim_boundary (notably enforces "completed != recovery proven")
• tone

Spec 335 UX use:

• RestoreResultAttention remains the source for result attention copy and recovery-claim boundaries.
• OperationRun proof state and post-run evidence state are derived by the Restore Run detail presenter, not persisted into this contract.

OperationRun Proof (repo-verified)

Sources:

• apps/platform/app/Models/OperationRun.php
• apps/platform/app/Support/OperationRunStatus.php
• apps/platform/app/Support/OperationRunOutcome.php

RestoreRun link (repo-verified):

• restore_runs.operation_run_id -> operation_runs.id

Notes:

• OperationRun "proof" is repo-real for restore runs that have operation_run_id.
• UI link helpers exist (repo-verified): apps/platform/app/Support/OperationRunLinks.php and Filament OperationRunResource.
• apps/platform/app/Observers/RestoreRunObserver.php and apps/platform/app/Listeners/SyncRestoreRunToOperationRun.php create/sync adapter OperationRun rows from previewed onward. Legacy/imported rows can still have no linked operation and must render proof as unavailable.
• Restore Run detail proof links must be same-workspace/same-managed-environment and authorized through the existing OperationRun view policy before a link is shown.

EvidenceSnapshot (post-run evidence) (foundation-real)

Sources:

• apps/platform/app/Models/EvidenceSnapshot.php
• apps/platform/database/migrations/2026_03_19_000000_create_evidence_snapshots_table.php
• Filament: apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php

Linkage:

• Evidence snapshots can be linked to an OperationRun via evidence_snapshots.operation_run_id.
• Evidence snapshots are tenant-scoped: (workspace_id, managed_environment_id) and have status + completeness_state.

Evidence availability for restore runs:

• Model + viewer exist (foundation-real).
• Restore execution does not guarantee an evidence snapshot. Absence is rendered as "Post-run evidence unavailable" and never as verified recovery.
• The Restore Run detail presenter resolves evidence by linked operation_run_id, same workspace_id, same managed_environment_id, and statuses active, generating, or queued.
• If multiple snapshots exist for the operation run, the presenter links the latest active snapshot when present, otherwise the latest queued/generating snapshot as in-progress evidence.
• Evidence links require the current user to have Capabilities::EVIDENCE_VIEW for the tenant and EvidenceSnapshotResource::canView($snapshot).

Current Restore Run Detail UI (repo-verified)

Primary surface:

• Filament page: apps/platform/app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php
• Infolist schema: apps/platform/app/Filament/Resources/RestoreRunResource.php::infolist()

Custom entries already in use:

• Preview entry view: apps/platform/resources/views/filament/infolists/entries/restore-preview.blade.php
• Results entry view: apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php

Spec 335 implementation target:

• The detail page uses a derived presenter-backed decision card and proof/evidence aside. No new persisted proof state is introduced.

Existing Tests (repo-verified)

Most relevant existing coverage:

• Result attention rendering: apps/platform/tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php
• Restore Run UI enforcement / access semantics: apps/platform/tests/Feature/Filament/RestoreRunUiEnforcementTest.php
• Dashboard deep-link copy (subheading): ViewRestoreRun::getSubheading() covered indirectly by feature tests

Browser tests exist for Restore Create (Spec 332/333), not for Restore Run detail productization yet.

Permissions / Capabilities (repo-verified)

RestoreRunResource access checks:

• apps/platform/app/Filament/Resources/RestoreRunResource.php::canViewAny() uses:
  • membership + Capabilities::TENANT_VIEW

Detail record resolution:

• RestoreRunResource::resolveScopedRecordOrFail() routes through tenant-owned record resolution, preserving tenant/workspace scoping.

Open Truth Questions

• None for Spec 335 implementation. Evidence generation itself remains out of scope; the page only reflects repo-backed snapshots that already exist.