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.