diff --git a/apps/platform/app/Filament/Resources/RestoreRunResource.php b/apps/platform/app/Filament/Resources/RestoreRunResource.php index 72e59137..1c9bc11c 100644 --- a/apps/platform/app/Filament/Resources/RestoreRunResource.php +++ b/apps/platform/app/Filament/Resources/RestoreRunResource.php @@ -9,6 +9,7 @@ use App\Filament\Concerns\WorkspaceScopedEnvironmentRoutes; use App\Filament\Resources\RestoreRunResource\Pages; use App\Filament\Resources\RestoreRunResource\Presenters\RestoreRunCreatePresenter; +use App\Filament\Resources\RestoreRunResource\Presenters\RestoreRunDetailPresenter; use App\Jobs\BulkRestoreRunDeleteJob; use App\Jobs\BulkRestoreRunForceDeleteJob; use App\Jobs\BulkRestoreRunRestoreJob; @@ -300,7 +301,7 @@ public static function resolveScopedRecordOrFail(int|string $key): Model { return static::resolveTenantOwnedRecordOrFail( $key, - parent::getEloquentQuery()->withTrashed()->with('backupSet'), + parent::getEloquentQuery()->withTrashed()->with(['backupSet', 'operationRun', 'tenant']), ); } @@ -1671,38 +1672,43 @@ public static function infolist(Schema $schema): Schema { return $schema ->schema([ - Infolists\Components\TextEntry::make('backupSet.name')->label('Backup set'), - Infolists\Components\TextEntry::make('status') - ->badge() - ->formatStateUsing(BadgeRenderer::label(BadgeDomain::RestoreRunStatus)) - ->color(BadgeRenderer::color(BadgeDomain::RestoreRunStatus)) - ->icon(BadgeRenderer::icon(BadgeDomain::RestoreRunStatus)) - ->iconColor(BadgeRenderer::iconColor(BadgeDomain::RestoreRunStatus)), - Infolists\Components\TextEntry::make('counts') - ->label('Counts') - ->state(function (RestoreRun $record): string { - $meta = $record->metadata ?? []; - $total = (int) ($meta['total'] ?? 0); - $succeeded = (int) ($meta['succeeded'] ?? 0); - $failed = (int) ($meta['failed'] ?? 0); - - return sprintf('Total: %d • Applied: %d • Failed items: %d', $total, $succeeded, $failed); - }), - Infolists\Components\TextEntry::make('is_dry_run') - ->label('Dry-run') - ->formatStateUsing(fn ($state) => $state ? 'Yes' : 'No') - ->badge(), - Infolists\Components\TextEntry::make('requested_by'), - Infolists\Components\TextEntry::make('started_at')->dateTime(), - Infolists\Components\TextEntry::make('completed_at')->dateTime(), - Infolists\Components\ViewEntry::make('preview') - ->label('Preview') - ->view('filament.infolists.entries.restore-preview') - ->state(fn (RestoreRun $record): array => static::detailPreviewState($record)), Infolists\Components\ViewEntry::make('results') - ->label('Results') + ->label('Post-execution proof') ->view('filament.infolists.entries.restore-results') - ->state(fn (RestoreRun $record): array => static::detailResultsState($record)), + ->state(fn (RestoreRun $record): array => static::detailResultsState($record)) + ->columnSpanFull(), + Section::make('Technical preview evidence') + ->description('Secondary pre-execution context. The post-execution proof decision above is the operator-facing source of truth.') + ->schema([ + Infolists\Components\ViewEntry::make('preview') + ->hiddenLabel() + ->view('filament.infolists.entries.restore-preview') + ->state(fn (RestoreRun $record): array => static::detailPreviewState($record)), + ]) + ->collapsible() + ->collapsed() + ->columnSpanFull(), + Section::make('Technical record metadata') + ->description('Raw lifecycle fields for audit and support. Use the proof decision above for restore outcome status.') + ->schema([ + Infolists\Components\TextEntry::make('backupSet.name')->label('Backup set'), + Infolists\Components\TextEntry::make('status') + ->label('Record lifecycle') + ->badge() + ->formatStateUsing(fn ($state): string => Str::headline((string) $state)) + ->color('gray'), + Infolists\Components\TextEntry::make('is_dry_run') + ->label('Preview-only flag') + ->formatStateUsing(fn ($state) => $state ? 'Yes' : 'No') + ->badge(), + Infolists\Components\TextEntry::make('requested_by')->placeholder('Not recorded'), + Infolists\Components\TextEntry::make('started_at')->dateTime()->placeholder('—'), + Infolists\Components\TextEntry::make('completed_at')->dateTime()->placeholder('—'), + ]) + ->columns(3) + ->collapsible() + ->collapsed() + ->columnSpanFull(), ]); } @@ -2680,11 +2686,7 @@ private static function detailPreviewState(RestoreRun $record): array */ private static function detailResultsState(RestoreRun $record): array { - return [ - 'results' => is_array($record->results) ? $record->results : [], - 'resultAttention' => static::restoreSafetyResolver()->resultAttentionForRun($record)->toArray(), - 'executionSafetySnapshot' => $record->executionSafetySnapshot(), - ]; + return app(RestoreRunDetailPresenter::class)->forRun($record); } private static function restoreSafetyResolver(): RestoreSafetyResolver diff --git a/apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php b/apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php new file mode 100644 index 00000000..8c4d348f --- /dev/null +++ b/apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunDetailPresenter.php @@ -0,0 +1,628 @@ + + */ + public function forRun(RestoreRun $restoreRun): array + { + $restoreRun->loadMissing(['backupSet', 'operationRun', 'tenant']); + + $attention = $this->restoreSafetyResolver->resultAttentionForRun($restoreRun); + $operationRun = $this->scopedOperationRun($restoreRun); + $operationProof = $this->operationProof($operationRun); + $postRunEvidence = $this->postRunEvidence($restoreRun, $operationRun); + $decision = $this->decision($restoreRun, $attention, $operationProof, $postRunEvidence); + $resultSummary = $this->resultSummary($restoreRun); + $itemOutcomes = $this->itemOutcomes($restoreRun); + $foundationOutcomes = $this->foundationOutcomes($restoreRun); + $itemOutcomeEvidence = $this->itemOutcomeEvidence($itemOutcomes, $resultSummary); + + return [ + 'decision' => $decision, + 'operationProof' => $operationProof, + 'postRunEvidence' => $postRunEvidence, + 'resultSummary' => $resultSummary, + 'itemOutcomeEvidence' => $itemOutcomeEvidence, + 'itemOutcomes' => $itemOutcomes, + 'foundationOutcomes' => $foundationOutcomes, + 'diagnostics' => [ + 'state' => 'collapsed', + 'summary' => 'Diagnostics are secondary. Raw restore payloads, provider request IDs, and low-level execution details stay out of the first decision path.', + 'execution_basis' => $this->executionBasis($restoreRun), + 'items_requiring_attention' => count(array_filter( + $itemOutcomes, + static fn (array $item): bool => (bool) ($item['needs_attention'] ?? false), + )), + ], + 'runContext' => [ + 'backup_set' => $restoreRun->backupSet?->name ?? 'Backup set unavailable', + 'target_environment' => $restoreRun->tenant?->name ?? 'Environment unavailable', + 'requested_by' => filled($restoreRun->requested_by) ? (string) $restoreRun->requested_by : 'Not recorded', + 'started_at' => $restoreRun->started_at?->toDayDateTimeString(), + 'completed_at' => $restoreRun->completed_at?->toDayDateTimeString(), + 'dry_run' => (bool) $restoreRun->is_dry_run, + ], + 'results' => is_array($restoreRun->results) ? $restoreRun->results : [], + 'resultAttention' => $attention->toArray(), + 'executionSafetySnapshot' => $restoreRun->executionSafetySnapshot(), + ]; + } + + /** + * @param array $operationProof + * @param array $postRunEvidence + * @return array + */ + private function decision( + RestoreRun $restoreRun, + RestoreResultAttention $attention, + array $operationProof, + array $postRunEvidence, + ): array { + $state = $this->decisionState($restoreRun, $attention, $operationProof, $postRunEvidence); + + $copy = match ($state) { + 'not_executed' => [ + 'status_label' => 'Not executed', + 'reason' => 'This record proves preview truth, not environment recovery.', + 'impact' => 'No execution proof or post-run evidence exists yet.', + 'primary_next_action' => 'Review preview', + 'primary_next_url' => null, + 'tone' => 'gray', + 'icon' => 'heroicon-m-eye', + ], + 'in_progress' => [ + 'status_label' => 'Execution in progress', + 'reason' => 'Restore execution is currently running.', + 'impact' => 'Results and post-run evidence are not final yet.', + 'primary_next_action' => 'View operation progress', + 'primary_next_url' => $operationProof['url'] ?? null, + 'tone' => 'info', + 'icon' => 'heroicon-m-arrow-path', + ], + 'completed_with_evidence' => [ + 'status_label' => 'Completed with evidence available', + 'reason' => 'Execution proof and post-run evidence are available.', + 'impact' => 'Review evidence before treating this restore as recovery proof.', + 'primary_next_action' => 'Open evidence', + 'primary_next_url' => $postRunEvidence['url'] ?? null, + 'tone' => 'success', + 'icon' => 'heroicon-m-shield-check', + ], + 'needs_review' => [ + 'status_label' => 'Completed with items needing review', + 'reason' => $attention->summary, + 'impact' => 'Review item outcomes before relying on the result.', + 'primary_next_action' => 'Review item outcomes', + 'primary_next_url' => null, + 'tone' => 'warning', + 'icon' => 'heroicon-m-exclamation-triangle', + ], + 'failed' => [ + 'status_label' => 'Restore failed', + 'reason' => 'The restore did not complete successfully.', + 'impact' => 'Some requested changes may not have been applied.', + 'primary_next_action' => 'Review failure details', + 'primary_next_url' => null, + 'tone' => 'danger', + 'icon' => 'heroicon-m-x-circle', + ], + 'blocked_or_cancelled' => [ + 'status_label' => 'Restore blocked / cancelled', + 'reason' => 'Restore did not execute due to cancellation or blocker.', + 'impact' => 'No recovery proof exists.', + 'primary_next_action' => 'Review blocker', + 'primary_next_url' => $operationProof['url'] ?? null, + 'tone' => 'warning', + 'icon' => 'heroicon-m-no-symbol', + ], + default => [ + 'status_label' => 'Completed, recovery proof incomplete', + 'reason' => 'Execution completed, but post-run evidence is not available yet.', + 'impact' => 'Do not treat this restore as verified recovery until evidence has been reviewed.', + 'primary_next_action' => filled($operationProof['url'] ?? null) ? 'Open operation proof' : 'Review proof gap', + 'primary_next_url' => $operationProof['url'] ?? null, + 'tone' => 'warning', + 'icon' => 'heroicon-m-shield-exclamation', + ], + }; + + return [ + 'state' => $state, + ...$copy, + 'question' => 'Was this restore executed safely, and is recovery proof available?', + 'attention_summary' => $attention->summary, + 'primary_cause_family' => RestoreSafetyCopy::primaryCauseFamily($attention->primaryCauseFamily), + 'result_next_action' => RestoreSafetyCopy::primaryNextAction($attention->primaryNextAction), + 'recovery_claim_boundary' => RestoreSafetyCopy::recoveryBoundary($attention->recoveryClaimBoundary), + ]; + } + + /** + * @param array $operationProof + * @param array $postRunEvidence + */ + private function decisionState( + RestoreRun $restoreRun, + RestoreResultAttention $attention, + array $operationProof, + array $postRunEvidence, + ): string { + $status = RestoreRunStatus::fromString((string) $restoreRun->status); + + if ($restoreRun->is_dry_run || in_array($status, [ + RestoreRunStatus::Draft, + RestoreRunStatus::Scoped, + RestoreRunStatus::Checked, + RestoreRunStatus::Previewed, + ], true)) { + return 'not_executed'; + } + + if (in_array($status, [RestoreRunStatus::Queued, RestoreRunStatus::Running], true) + || ($operationProof['state'] ?? null) === 'in_progress') { + return 'in_progress'; + } + + if ($status === RestoreRunStatus::Failed || ($operationProof['outcome'] ?? null) === OperationRunOutcome::Failed->value) { + return 'failed'; + } + + if (in_array($status, [RestoreRunStatus::Cancelled, RestoreRunStatus::Aborted], true) + || ($operationProof['outcome'] ?? null) === OperationRunOutcome::Blocked->value) { + return 'blocked_or_cancelled'; + } + + if (in_array($status, [RestoreRunStatus::Partial, RestoreRunStatus::CompletedWithErrors], true)) { + return 'needs_review'; + } + + if (($postRunEvidence['state'] ?? null) === 'available') { + return 'completed_with_evidence'; + } + + return 'completed_proof_incomplete'; + } + + /** + * @return array + */ + private function operationProof(?OperationRun $operationRun): array + { + if (! $operationRun instanceof OperationRun) { + return [ + 'state' => 'unavailable', + 'label' => 'Operation proof unavailable', + 'url' => null, + 'status' => null, + 'outcome' => null, + 'status_badge' => $this->statusBadge('gray', 'Unavailable', 'heroicon-m-minus-circle'), + 'outcome_badge' => null, + 'identifier' => null, + ]; + } + + $status = (string) $operationRun->status; + $outcome = (string) $operationRun->outcome; + $state = in_array($status, [OperationRunStatus::Queued->value, OperationRunStatus::Running->value], true) + ? 'in_progress' + : 'available'; + + return [ + 'state' => $state, + 'label' => $state === 'in_progress' ? 'Operation proof in progress' : 'Operation proof available', + 'url' => OperationRunLinks::tenantlessView($operationRun), + 'status' => $status, + 'outcome' => $outcome, + 'status_badge' => $this->badge(BadgeDomain::OperationRunStatus, $status), + 'outcome_badge' => $this->badge(BadgeDomain::OperationRunOutcome, $outcome), + 'identifier' => OperationRunLinks::identifier($operationRun), + ]; + } + + /** + * @return array + */ + private function postRunEvidence(RestoreRun $restoreRun, ?OperationRun $operationRun): array + { + if (! $operationRun instanceof OperationRun || ! $this->canViewEvidence($restoreRun)) { + return [ + 'state' => 'unavailable', + 'label' => 'Post-run evidence unavailable', + 'url' => null, + 'status' => null, + 'completeness' => null, + 'status_badge' => $this->statusBadge('gray', 'Unavailable', 'heroicon-m-minus-circle'), + 'completeness_badge' => null, + 'identifier' => null, + ]; + } + + $snapshots = EvidenceSnapshot::query() + ->where('operation_run_id', (int) $operationRun->getKey()) + ->where('workspace_id', (int) $restoreRun->workspace_id) + ->where('managed_environment_id', (int) $restoreRun->managed_environment_id) + ->whereIn('status', [ + EvidenceSnapshotStatus::Active->value, + EvidenceSnapshotStatus::Generating->value, + EvidenceSnapshotStatus::Queued->value, + ]) + ->latest('id') + ->get(); + + $snapshot = $snapshots->firstWhere('status', EvidenceSnapshotStatus::Active->value) + ?? $snapshots->first(); + + if (! $snapshot instanceof EvidenceSnapshot || ! EvidenceSnapshotResource::canView($snapshot)) { + return [ + 'state' => 'unavailable', + 'label' => 'Post-run evidence unavailable', + 'url' => null, + 'status' => null, + 'completeness' => null, + 'status_badge' => $this->statusBadge('gray', 'Unavailable', 'heroicon-m-minus-circle'), + 'completeness_badge' => null, + 'identifier' => null, + ]; + } + + $state = $snapshot->status === EvidenceSnapshotStatus::Active->value ? 'available' : 'in_progress'; + + return [ + 'state' => $state, + 'label' => $state === 'available' ? 'Post-run evidence available' : 'Post-run evidence in progress', + 'url' => EvidenceSnapshotResource::getUrl('view', ['record' => $snapshot], tenant: $restoreRun->tenant), + 'status' => (string) $snapshot->status, + 'completeness' => (string) $snapshot->completeness_state, + 'status_badge' => $this->badge(BadgeDomain::EvidenceSnapshotStatus, (string) $snapshot->status), + 'completeness_badge' => $this->badge(BadgeDomain::EvidenceCompleteness, (string) $snapshot->completeness_state), + 'identifier' => 'Evidence snapshot #'.$snapshot->getKey(), + ]; + } + + private function scopedOperationRun(RestoreRun $restoreRun): ?OperationRun + { + $operationRun = $restoreRun->operationRun; + + if (! $operationRun instanceof OperationRun) { + return null; + } + + if ((int) $operationRun->workspace_id !== (int) $restoreRun->workspace_id + || (int) $operationRun->managed_environment_id !== (int) $restoreRun->managed_environment_id) { + return null; + } + + $user = auth()->user(); + + if (! $user instanceof User || ! Gate::forUser($user)->allows('view', $operationRun)) { + return null; + } + + return $operationRun; + } + + private function canViewEvidence(RestoreRun $restoreRun): bool + { + $user = auth()->user(); + $tenant = $restoreRun->tenant; + + return $user instanceof User + && $tenant !== null + && $user->can(Capabilities::EVIDENCE_VIEW, $tenant); + } + + /** + * @return array + */ + private function resultSummary(RestoreRun $restoreRun): array + { + $metadata = is_array($restoreRun->metadata) ? $restoreRun->metadata : []; + $keys = ['total', 'succeeded', 'failed', 'skipped', 'partial', 'non_applied']; + $available = collect($keys)->contains( + static fn (string $key): bool => array_key_exists($key, $metadata) && is_numeric($metadata[$key]), + ); + + if (! $available) { + return [ + 'available' => false, + 'message' => 'Result summary unavailable', + 'counts' => [], + ]; + } + + $counts = [ + 'requested' => $this->numericCount($metadata, 'total'), + 'applied' => $this->numericCount($metadata, 'succeeded'), + 'failed' => $this->numericCount($metadata, 'failed'), + 'skipped' => $this->numericCount($metadata, 'skipped'), + 'partial' => $this->numericCount($metadata, 'partial'), + 'non_applied' => $this->numericCount($metadata, 'non_applied'), + ]; + + $reviewValues = array_filter([ + $counts['failed'], + $counts['skipped'], + $counts['partial'], + $counts['non_applied'], + ], static fn (?int $value): bool => $value !== null); + + $counts['needs_review'] = $reviewValues === [] ? null : array_sum($reviewValues); + + return [ + 'available' => true, + 'message' => 'Repo-backed result counts from restore metadata.', + 'counts' => $counts, + ]; + } + + /** + * @param list> $itemOutcomes + * @param array $resultSummary + * @return array + */ + private function itemOutcomeEvidence(array $itemOutcomes, array $resultSummary): array + { + if ($itemOutcomes !== []) { + return [ + 'state' => 'available', + 'label' => count($itemOutcomes).' item '.(count($itemOutcomes) === 1 ? 'record' : 'records'), + 'tone' => 'gray', + 'message' => 'Per-item outcome rows are available for review.', + ]; + } + + if (($resultSummary['available'] ?? false) === true) { + return [ + 'state' => 'summary_only', + 'label' => 'Metadata counts only', + 'tone' => 'warning', + 'message' => 'Aggregate restore counts are available, but item-level outcome rows are not stored for this run. Use the OperationRun proof and aggregate counts for follow-up.', + ]; + } + + return [ + 'state' => 'unavailable', + 'label' => 'No item records', + 'tone' => 'gray', + 'message' => 'No aggregate counts or item-level outcome rows are available for this run.', + ]; + } + + /** + * @param array $metadata + */ + private function numericCount(array $metadata, string $key): ?int + { + return array_key_exists($key, $metadata) && is_numeric($metadata[$key]) + ? (int) $metadata[$key] + : null; + } + + /** + * @return list> + */ + private function itemOutcomes(RestoreRun $restoreRun): array + { + $results = is_array($restoreRun->results) ? $restoreRun->results : []; + $items = is_array($results['items'] ?? null) ? array_values($results['items']) : []; + + return collect($items) + ->filter(static fn (mixed $item): bool => is_array($item)) + ->map(function (array $item, int $index): array { + $status = $this->stringValue($item['status'] ?? null, 'unknown'); + $assignmentSummary = is_array($item['assignment_summary'] ?? null) ? $item['assignment_summary'] : []; + $settingsApply = is_array($item['settings_apply'] ?? null) ? $item['settings_apply'] : []; + + return [ + 'name' => $this->itemName($item, $index), + 'type' => $this->stringValue($item['policy_type'] ?? null, 'Policy'), + 'platform' => $this->stringValue($item['platform'] ?? null, '—'), + 'status' => $status, + 'status_badge' => $this->badge(BadgeDomain::RestoreResultStatus, $status), + 'restore_mode' => $this->stringValue($item['restore_mode'] ?? null, null), + 'reason' => $this->safeReason($item), + 'assignments' => $this->summaryLine($assignmentSummary, [ + 'success' => 'applied', + 'failed' => 'failed', + 'skipped' => 'not applied', + ]), + 'settings' => $this->summaryLine($settingsApply, [ + 'applied' => 'applied', + 'failed' => 'failed', + 'manual_required' => 'manual', + ]), + 'needs_attention' => in_array($status, ['failed', 'partial', 'manual_required', 'skipped'], true), + 'diagnostics' => $this->itemDiagnostics($item), + ]; + }) + ->values() + ->all(); + } + + /** + * @return list> + */ + private function foundationOutcomes(RestoreRun $restoreRun): array + { + $results = is_array($restoreRun->results) ? $restoreRun->results : []; + $foundations = is_array($results['foundations'] ?? null) ? array_values($results['foundations']) : []; + + return collect($foundations) + ->filter(static fn (mixed $item): bool => is_array($item)) + ->map(function (array $item, int $index): array { + $decision = $this->stringValue($item['decision'] ?? null, 'unknown'); + $reason = $this->safeReason($item); + + return [ + 'name' => $this->stringValue($item['sourceName'] ?? $item['sourceId'] ?? null, 'Foundation '.($index + 1)), + 'type' => $this->stringValue($item['type'] ?? null, 'foundation'), + 'target' => $this->stringValue($item['targetName'] ?? null, null), + 'decision' => $decision, + 'decision_badge' => $this->badge( + BadgeDomain::RestorePreviewDecision, + $decision === 'dry_run' ? 'dry_run' : $decision, + ), + 'reason' => $this->safeFoundationReason($item), + 'needs_attention' => in_array($decision, ['failed', 'skipped'], true), + ]; + }) + ->values() + ->all(); + } + + /** + * @return array + */ + private function itemDiagnostics(array $item): array + { + $diagnostics = []; + + foreach (['graph_error_message', 'graph_error_code', 'graph_request_id', 'graph_client_request_id', 'graph_method', 'graph_path'] as $key) { + if (filled($item[$key] ?? null)) { + $diagnostics[] = Str::headline($key).' recorded'; + } + } + + return array_values(array_unique($diagnostics)); + } + + /** + * @param array $item + */ + private function itemName(array $item, int $index): string + { + foreach (['policy_display_name', 'display_name', 'policy_identifier', 'policy_id'] as $key) { + if (filled($item[$key] ?? null)) { + return (string) $item[$key]; + } + } + + return 'Policy '.($index + 1); + } + + /** + * @param array $item + */ + private function safeReason(array $item): ?string + { + $reason = $this->stringValue($item['reason'] ?? null, null); + + if ($reason === null) { + return null; + } + + return match ($reason) { + 'preview_only' => 'Preview only. This item was not applied during execution.', + default => Str::headline($reason), + }; + } + + /** + * @param array $item + */ + private function safeFoundationReason(array $item): ?string + { + $reason = $this->stringValue($item['reason'] ?? null, null); + + if ($reason === null) { + return null; + } + + return match ($reason) { + 'preview_only' => 'Preview only. This foundation type is not applied during execution.', + default => Str::headline($reason), + }; + } + + /** + * @param array $summary + * @param array $labels + */ + private function summaryLine(array $summary, array $labels): ?string + { + $parts = []; + + foreach ($labels as $key => $label) { + if (array_key_exists($key, $summary) && is_numeric($summary[$key])) { + $parts[] = ((int) $summary[$key]).' '.$label; + } + } + + return $parts === [] ? null : implode(' • ', $parts); + } + + private function executionBasis(RestoreRun $restoreRun): string + { + $snapshot = $restoreRun->executionSafetySnapshot(); + $safetyState = $snapshot['safety_state'] ?? null; + + if (! is_string($safetyState) || $safetyState === '') { + return 'No execution safety snapshot was recorded.'; + } + + return 'Execution basis: '.RestoreSafetyCopy::safetyStateLabel($safetyState).'.'; + } + + private function stringValue(mixed $value, ?string $fallback): ?string + { + return is_string($value) && trim($value) !== '' ? trim($value) : $fallback; + } + + /** + * @return array{label:string,color:string,icon:?string,iconColor:?string} + */ + private function badge(BadgeDomain $domain, ?string $state): array + { + $spec = BadgeRenderer::spec($domain, $state); + + return [ + 'label' => $spec->label, + 'color' => $spec->color, + 'icon' => $spec->icon, + 'iconColor' => $spec->iconColor, + ]; + } + + /** + * @return array{label:string,color:string,icon:?string,iconColor:?string} + */ + private function statusBadge(string $color, string $label, ?string $icon = null): array + { + return [ + 'label' => $label, + 'color' => $color, + 'icon' => $icon, + 'iconColor' => $color, + ]; + } +} diff --git a/apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php b/apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php index 559f2fd7..138894cb 100644 --- a/apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php +++ b/apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php @@ -1,452 +1,384 @@ @php - $state = $getState() ?? []; - $state = is_array($state) ? $state : []; - $resultAttention = is_array($state['resultAttention'] ?? null) ? $state['resultAttention'] : []; - $executionSafetySnapshot = is_array($state['executionSafetySnapshot'] ?? null) ? $state['executionSafetySnapshot'] : []; - $state = is_array($state['results'] ?? null) ? $state['results'] : $state; - $isFoundationEntry = function ($item) { - return is_array($item) && array_key_exists('decision', $item) && array_key_exists('sourceId', $item); - }; + $surface = $getState() ?? []; + $surface = is_array($surface) ? $surface : []; - if (is_array($state) && array_key_exists('items', $state)) { - $foundationItems = collect($state['foundations'] ?? [])->filter($isFoundationEntry); - $policyItems = collect($state['items'] ?? [])->values(); - $results = $state; - } else { - $results = $state; - $foundationItems = collect($results)->filter($isFoundationEntry); - $policyItems = collect($results)->reject($isFoundationEntry); - } + $decision = is_array($surface['decision'] ?? null) ? $surface['decision'] : []; + $operationProof = is_array($surface['operationProof'] ?? null) ? $surface['operationProof'] : []; + $postRunEvidence = is_array($surface['postRunEvidence'] ?? null) ? $surface['postRunEvidence'] : []; + $resultSummary = is_array($surface['resultSummary'] ?? null) ? $surface['resultSummary'] : []; + $summaryCounts = is_array($resultSummary['counts'] ?? null) ? $resultSummary['counts'] : []; + $itemOutcomeEvidence = is_array($surface['itemOutcomeEvidence'] ?? null) ? $surface['itemOutcomeEvidence'] : []; + $itemOutcomes = collect(is_array($surface['itemOutcomes'] ?? null) ? $surface['itemOutcomes'] : []); + $foundationOutcomes = collect(is_array($surface['foundationOutcomes'] ?? null) ? $surface['foundationOutcomes'] : []); + $diagnostics = is_array($surface['diagnostics'] ?? null) ? $surface['diagnostics'] : []; + $runContext = is_array($surface['runContext'] ?? null) ? $surface['runContext'] : []; + $resultAttention = is_array($surface['resultAttention'] ?? null) ? $surface['resultAttention'] : []; - $tenant = rescue(fn () => \App\Models\ManagedEnvironment::current(), null); - $groupLabelResolver = $tenant ? app(\App\Services\Directory\EntraGroupLabelResolver::class) : null; + $attentionSpec = \App\Support\Badges\BadgeRenderer::spec( + \App\Support\Badges\BadgeDomain::RestoreResultStatus, + $resultAttention['state'] ?? ($decision['state'] ?? 'not_executed') + ); - $formatGroupId = function ($groupId, $fallbackName = null) use ($tenant, $groupLabelResolver) { - if (! is_string($groupId) || $groupId === '') { - return null; - } + $summaryCards = [ + 'requested' => 'Requested', + 'applied' => 'Applied', + 'failed' => 'Failed', + 'skipped' => 'Skipped', + 'needs_review' => 'Needs review', + ]; - $cachedName = null; - - if ($tenant && $groupLabelResolver) { - $cached = $groupLabelResolver->lookupMany($tenant, [$groupId]); - $cachedName = $cached[strtolower($groupId)] ?? null; - } - - $name = is_string($fallbackName) && $fallbackName !== '' ? $fallbackName : null; - - return \App\Services\Directory\EntraGroupLabelResolver::formatLabel($cachedName ?? $name, $groupId); - }; + $formatCount = static fn (mixed $value): string => is_numeric($value) ? number_format((int) $value) : '—'; @endphp -@if ($foundationItems->isEmpty() && $policyItems->isEmpty()) -

No restore results have been recorded yet.

-@else - @php - $needsAttention = (bool) ($resultAttention['follow_up_required'] ?? false) - || $policyItems->contains(function ($item) { - $status = $item['status'] ?? null; +
+
+
+ + {{ $decision['status_label'] ?? 'Restore result unavailable' }} + - return in_array($status, ['partial', 'manual_required'], true); - }); - $attentionSpec = \App\Support\Badges\BadgeRenderer::spec( - \App\Support\Badges\BadgeDomain::RestoreResultStatus, - $resultAttention['state'] ?? ($needsAttention ? 'completed_with_follow_up' : 'completed') - ); - $executionBasisLabel = \App\Support\RestoreSafety\RestoreSafetyCopy::safetyStateLabel( - is_string($executionSafetySnapshot['safety_state'] ?? null) ? $executionSafetySnapshot['safety_state'] : null - ); - $primaryNextAction = \App\Support\RestoreSafety\RestoreSafetyCopy::primaryNextAction( - is_string($resultAttention['primary_next_action'] ?? null) ? $resultAttention['primary_next_action'] : 'review_result' - ); - $primaryCauseFamily = \App\Support\RestoreSafety\RestoreSafetyCopy::primaryCauseFamily( - is_string($resultAttention['primary_cause_family'] ?? null) ? $resultAttention['primary_cause_family'] : 'none' - ); - $recoveryBoundary = \App\Support\RestoreSafety\RestoreSafetyCopy::recoveryBoundary( - is_string($resultAttention['recovery_claim_boundary'] ?? null) - ? $resultAttention['recovery_claim_boundary'] - : 'run_completed_not_recovery_proven' - ); - @endphp + + {{ $attentionSpec->label }} + +
-
-
-
- - {{ $attentionSpec->label }} - - @if (($executionSafetySnapshot['safety_state'] ?? null) !== null) - - Execution basis: {{ $executionBasisLabel }} - +
+
+
+

Primary operator question

+

+ {{ $decision['question'] ?? 'Was this restore executed safely, and is recovery proof available?' }} +

+
+ +
+
+

Reason

+

{{ $decision['reason'] ?? 'Restore result reason unavailable.' }}

+ @if (filled($decision['attention_summary'] ?? null)) +

{{ $decision['attention_summary'] }}

+ @endif +
+
+

Impact

+

{{ $decision['impact'] ?? 'Review restore details before relying on this record.' }}

+
+
+

Primary next action

+

{{ $decision['primary_next_action'] ?? 'Review restore details' }}

+
+
+
+ +
+

Dominant action

+ @if (filled($decision['primary_next_url'] ?? null)) + + {{ $decision['primary_next_action'] ?? 'Open detail' }} + + @else +
+ {{ $decision['primary_next_action'] ?? 'Review restore details' }} +
@endif -
- -
-
-
What this run proves
-
{{ $resultAttention['summary'] ?? 'Restore result truth is unavailable.' }}
-
-
-
Primary next step
-
{{ $primaryNextAction }}
-
-
- -
-
-
Main follow-up driver
-
{{ $primaryCauseFamily }}
-
-
-
What this record does not prove
-
{{ $recoveryBoundary }}
+
+

Result next step: {{ $decision['result_next_action'] ?? 'Review the completed restore details.' }}

+

Main follow-up driver: {{ $decision['primary_cause_family'] ?? 'No dominant cause recorded' }}

+

Boundary: {{ $decision['recovery_claim_boundary'] ?? 'Target environment recovery is not proven.' }}

+
- @if ($foundationItems->isNotEmpty()) -
-
Foundations
- @foreach ($foundationItems as $item) +
+
+
+
+
+

Restore result summary

+

{{ $resultSummary['message'] ?? 'Result summary unavailable' }}

+
+ Repo-backed +
+ + @if (($resultSummary['available'] ?? false) === true) +
+ @foreach ($summaryCards as $key => $label) +
+

{{ $label }}

+

{{ $formatCount($summaryCounts[$key] ?? null) }}

+
+ @endforeach +
+ @else +
+ Result summary unavailable. No fake zero counts are shown. +
+ @endif +
+ +
+
+
+

Item outcomes

+

Per-item results are table-first. Item diagnostics stay behind row disclosure.

+
+ + {{ $itemOutcomeEvidence['label'] ?? ($itemOutcomes->count().' items') }} + +
+ + @if ($itemOutcomes->isEmpty()) +
+ {{ $itemOutcomeEvidence['message'] ?? 'No item outcomes have been recorded yet.' }} +
+ @else +
+
+ + + + + + + + + + + + @foreach ($itemOutcomes as $item) + @php + $statusBadge = is_array($item['status_badge'] ?? null) ? $item['status_badge'] : []; + $diagnostics = collect(is_array($item['diagnostics'] ?? null) ? $item['diagnostics'] : []); + @endphp + + + + + + + + @endforeach + +
ItemStatusAssignmentsSettingsReview reason
+
{{ $item['name'] ?? 'Policy' }}
+
{{ $item['type'] ?? 'Policy' }} @if (($item['platform'] ?? '—') !== '—') • {{ $item['platform'] }} @endif
+ 		+ + {{ $statusBadge['label'] ?? 'Unknown' }} + + @if (filled($item['restore_mode'] ?? null)) +
{{ \Illuminate\Support\Str::headline($item['restore_mode']) }}
+ @endif + 		{{ $item['assignments'] ?? '—' }}{{ $item['settings'] ?? '—' }} +
{{ $item['reason'] ?? (($item['needs_attention'] ?? false) ? 'Review required' : 'No follow-up recorded') }}
+ @if ($diagnostics->isNotEmpty()) +
+ Diagnostics recorded +
    + @foreach ($diagnostics as $diagnostic) +
  • {{ $diagnostic }}
    • + @endforeach +
+
+ @endif +
+
+
+ @endif +
+ + @if ($foundationOutcomes->isNotEmpty()) +
+

Foundations

+
+ + + + + + + + + + + @foreach ($foundationOutcomes as $foundation) + @php + $decisionBadge = is_array($foundation['decision_badge'] ?? null) ? $foundation['decision_badge'] : []; + @endphp + + + + + + + @endforeach + +
FoundationDecisionTargetReason
+
{{ $foundation['name'] ?? 'Foundation' }}
+
{{ $foundation['type'] ?? 'foundation' }}
+ 		+ + {{ $decisionBadge['label'] ?? 'Unknown' }} + + {{ $foundation['target'] ?? '—' }}{{ $foundation['reason'] ?? '—' }}
+
+
+ @endif +
+ +
-@endif +
diff --git a/apps/platform/tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php b/apps/platform/tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php new file mode 100644 index 00000000..21711610 --- /dev/null +++ b/apps/platform/tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php @@ -0,0 +1,195 @@ +browser()->timeout(60_000); + +uses(RefreshDatabase::class); + +function spec335BrowserScreenshotName(string $name): string +{ + return 'spec335-restore-run-detail-'.$name; +} + +function spec335BrowserLoginUrl(User $user, ManagedEnvironment $tenant, string $redirect): string +{ + return route('admin.local.smoke-login', [ + 'email' => $user->email, + 'tenant' => $tenant->external_id, + 'workspace' => $tenant->workspace->slug, + 'redirect' => $redirect, + ]); +} + +function spec335BrowserViewPath(ManagedEnvironment $tenant, RestoreRun $restoreRun): string +{ + $url = RestoreRunResource::getUrl('view', ['record' => $restoreRun], panel: 'admin', tenant: $tenant); + + return parse_url($url, PHP_URL_PATH) ?: '/admin'; +} + +function spec335BrowserBackupSet(ManagedEnvironment $tenant): BackupSet +{ + return BackupSet::factory()->create([ + 'managed_environment_id' => (int) $tenant->getKey(), + 'name' => 'Spec335 Browser Backup', + 'status' => 'completed', + 'item_count' => 4, + ]); +} + +function spec335BrowserOperationRun(ManagedEnvironment $tenant, string $outcome = OperationRunOutcome::Succeeded->value): OperationRun +{ + return OperationRun::factory()->forTenant($tenant)->create([ + 'type' => OperationRunType::RestoreExecute->value, + 'status' => OperationRunStatus::Completed->value, + 'outcome' => $outcome, + 'completed_at' => now(), + ]); +} + +function spec335BrowserCompletedRestoreRun(ManagedEnvironment $tenant, BackupSet $backupSet, OperationRun $operationRun): RestoreRun +{ + return RestoreRun::factory()->for($tenant, 'tenant')->for($backupSet)->create([ + 'status' => 'completed', + 'operation_run_id' => (int) $operationRun->getKey(), + 'requested_by' => 'Spec335 Browser Operator', + 'results' => [ + 'foundations' => [], + 'items' => [ + [ + 'status' => 'applied', + 'policy_identifier' => 'Spec335 Browser Policy', + 'policy_type' => 'settingsCatalogPolicy', + 'platform' => 'windows', + 'assignment_summary' => [ + 'success' => 1, + 'failed' => 0, + 'skipped' => 1, + ], + 'settings_apply' => [ + 'applied' => 4, + 'failed' => 0, + 'manual_required' => 0, + ], + 'graph_error_message' => 'browser raw payload should stay hidden', + ], + ], + ], + 'metadata' => [ + 'total' => 4, + 'succeeded' => 3, + 'failed' => 0, + 'skipped' => 1, + 'partial' => 0, + 'non_applied' => 1, + 'execution_safety_snapshot' => [ + 'safety_state' => 'ready_with_caution', + ], + ], + 'completed_at' => now(), + ]); +} + +it('Spec335 smokes restore run detail post-execution proof states and screenshots', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $backupSet = spec335BrowserBackupSet($tenant); + + $draftRun = RestoreRun::factory()->for($tenant, 'tenant')->for($backupSet)->create([ + 'status' => 'draft', + 'is_dry_run' => true, + 'results' => [], + 'metadata' => [], + 'started_at' => null, + 'completed_at' => null, + ]); + + $completedOperation = spec335BrowserOperationRun($tenant); + $completedRun = spec335BrowserCompletedRestoreRun($tenant, $backupSet, $completedOperation); + + $failedOperation = spec335BrowserOperationRun($tenant, OperationRunOutcome::Failed->value); + $failedRun = RestoreRun::factory()->for($tenant, 'tenant')->for($backupSet)->create([ + 'status' => 'failed', + 'operation_run_id' => (int) $failedOperation->getKey(), + 'results' => [ + 'foundations' => [], + 'items' => [ + [ + 'status' => 'failed', + 'policy_identifier' => 'Spec335 Failed Browser Policy', + 'policy_type' => 'settingsCatalogPolicy', + 'platform' => 'windows', + ], + ], + ], + 'metadata' => [ + 'total' => 1, + 'succeeded' => 0, + 'failed' => 1, + ], + 'completed_at' => now(), + ]); + + $page = visit(spec335BrowserLoginUrl($user, $tenant, spec335BrowserViewPath($tenant, $draftRun))) + ->resize(1440, 1100) + ->waitForText('Was this restore executed safely, and is recovery proof available?') + ->assertSee('Not executed') + ->assertSee('Operation proof unavailable') + ->assertSee('Post-run evidence unavailable') + ->assertScript('document.querySelector("[data-testid=\"restore-run-diagnostics\"]")?.open === false', true) + ->assertNoJavaScriptErrors() + ->assertNoConsoleLogs() + ->screenshot(true, spec335BrowserScreenshotName('01-restore-run-draft')); + + $page = visit(spec335BrowserViewPath($tenant, $completedRun)) + ->resize(1440, 1100) + ->waitForText('Completed, recovery proof incomplete') + ->assertSee('Operation proof available') + ->assertSee('Post-run evidence unavailable') + ->assertSee('Restore result summary') + ->assertSee('Item outcomes') + ->assertSee('Spec335 Browser Policy') + ->assertDontSee('browser raw payload should stay hidden') + ->assertScript('document.querySelector("[data-testid=\"restore-run-diagnostics\"]")?.open === false', true) + ->assertNoJavaScriptErrors() + ->assertNoConsoleLogs() + ->screenshot(true, spec335BrowserScreenshotName('02-restore-run-completed-proof-incomplete')); + + $page->screenshot(true, spec335BrowserScreenshotName('03-restore-run-operation-proof')); + + $page->screenshot(true, spec335BrowserScreenshotName('04-restore-run-evidence-unavailable')); + + $page->screenshot(true, spec335BrowserScreenshotName('05-restore-run-item-outcomes')); + + $page->screenshot(true, spec335BrowserScreenshotName('07-restore-run-diagnostics-collapsed')); + + visit(spec335BrowserViewPath($tenant, $failedRun)) + ->resize(1440, 1100) + ->waitForText('Restore failed') + ->assertSee('Review failure details') + ->assertSee('Spec335 Failed Browser Policy') + ->assertScript('document.querySelector("[data-testid=\"restore-run-diagnostics\"]")?.open === false', true) + ->assertNoJavaScriptErrors() + ->assertNoConsoleLogs() + ->screenshot(true, spec335BrowserScreenshotName('06-restore-run-failed-if-supported')); + + visit(spec335BrowserLoginUrl($user, $tenant, spec335BrowserViewPath($tenant, $completedRun))) + ->inDarkMode() + ->resize(1440, 1100) + ->waitForText('Completed, recovery proof incomplete') + ->assertSee('Operation proof available') + ->assertNoJavaScriptErrors() + ->assertNoConsoleLogs() + ->screenshot(true, spec335BrowserScreenshotName('08-restore-run-dark-mode')); +}); diff --git a/apps/platform/tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php b/apps/platform/tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php new file mode 100644 index 00000000..166bcf9c --- /dev/null +++ b/apps/platform/tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php @@ -0,0 +1,234 @@ +create([ + 'managed_environment_id' => (int) $tenant->getKey(), + 'name' => 'Spec335 Backup Set', + 'status' => 'completed', + 'item_count' => 10, + ]); +} + +function spec335RestoreOperationRun(ManagedEnvironment $tenant, string $outcome = OperationRunOutcome::Succeeded->value): OperationRun +{ + return OperationRun::factory()->forTenant($tenant)->create([ + 'type' => OperationRunType::RestoreExecute->value, + 'status' => OperationRunStatus::Completed->value, + 'outcome' => $outcome, + 'completed_at' => now(), + 'context' => [ + 'restore_run_id' => 999, + ], + ]); +} + +function spec335CompletedRestoreRun(ManagedEnvironment $tenant, BackupSet $backupSet, ?OperationRun $operationRun = null): RestoreRun +{ + return RestoreRun::factory()->for($tenant, 'tenant')->for($backupSet)->create([ + 'status' => 'completed', + 'operation_run_id' => $operationRun?->getKey(), + 'requested_by' => 'Spec335 Operator', + 'results' => [ + 'foundations' => [], + 'items' => [ + 10 => [ + 'status' => 'applied', + 'policy_identifier' => 'Spec335 Completed Policy', + 'policy_type' => 'settingsCatalogPolicy', + 'platform' => 'windows', + 'assignment_summary' => [ + 'success' => 2, + 'failed' => 0, + 'skipped' => 1, + ], + 'settings_apply' => [ + 'applied' => 8, + 'failed' => 0, + 'manual_required' => 0, + ], + 'graph_error_message' => 'raw payload should stay hidden', + 'graph_request_id' => 'raw-request-id-should-stay-hidden', + ], + ], + ], + 'metadata' => [ + 'total' => 10, + 'succeeded' => 8, + 'failed' => 1, + 'skipped' => 1, + 'partial' => 0, + 'non_applied' => 1, + 'execution_safety_snapshot' => [ + 'safety_state' => 'ready_with_caution', + 'follow_up_boundary' => 'run_completed_not_recovery_proven', + ], + ], + 'completed_at' => now(), + ]); +} + +it('renders the decision-first restore run detail with proof incomplete boundaries', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $this->actingAs($user); + Filament::setTenant($tenant, true); + + $backupSet = spec335BackupSet($tenant); + $operationRun = spec335RestoreOperationRun($tenant); + $restoreRun = spec335CompletedRestoreRun($tenant, $backupSet, $operationRun); + + Livewire::test(ViewRestoreRun::class, ['record' => $restoreRun->getKey()]) + ->assertSee('Was this restore executed safely, and is recovery proof available?') + ->assertSee('Completed, recovery proof incomplete') + ->assertSee('Do not treat this restore as verified recovery until evidence has been reviewed.') + ->assertSee('Operation proof available') + ->assertSee('Open operation proof') + ->assertSee(OperationRunLinks::identifier($operationRun)) + ->assertSee('Post-run evidence unavailable') + ->assertSee('Restore result summary') + ->assertSee('Requested') + ->assertSee('10') + ->assertSee('Needs review') + ->assertSee('3') + ->assertSee('Item outcomes') + ->assertSee('Spec335 Completed Policy') + ->assertSee('Diagnostics collapsed') + ->assertDontSee('raw payload should stay hidden') + ->assertDontSee('raw-request-id-should-stay-hidden') + ->assertDontSee('Recovery verified') + ->assertDontSee('Healthy') + ->assertDontSee('Customer-safe'); +}); + +it('explains metadata-only follow-up counts when item outcome rows are absent', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $this->actingAs($user); + Filament::setTenant($tenant, true); + + $backupSet = spec335BackupSet($tenant); + $operationRun = spec335RestoreOperationRun($tenant); + $restoreRun = spec335CompletedRestoreRun($tenant, $backupSet, $operationRun); + $restoreRun->forceFill([ + 'results' => [ + 'foundations' => [], + 'items' => [], + ], + ])->save(); + + Livewire::test(ViewRestoreRun::class, ['record' => $restoreRun->getKey()]) + ->assertSee('Needs review') + ->assertSee('3') + ->assertSee('Metadata counts only') + ->assertSee('Aggregate restore counts are available, but item-level outcome rows are not stored for this run.') + ->assertDontSee('0 items'); +}); + +it('links repo-backed post-run evidence when an authorized snapshot exists', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $this->actingAs($user); + Filament::setTenant($tenant, true); + + $backupSet = spec335BackupSet($tenant); + $operationRun = spec335RestoreOperationRun($tenant); + $restoreRun = spec335CompletedRestoreRun($tenant, $backupSet, $operationRun); + + $snapshot = EvidenceSnapshot::query()->create([ + 'managed_environment_id' => (int) $tenant->getKey(), + 'workspace_id' => (int) $tenant->workspace_id, + 'operation_run_id' => (int) $operationRun->getKey(), + 'status' => EvidenceSnapshotStatus::Active->value, + 'completeness_state' => EvidenceCompletenessState::Complete->value, + 'summary' => ['finding_count' => 0], + 'generated_at' => now(), + ]); + + Livewire::test(ViewRestoreRun::class, ['record' => $restoreRun->getKey()]) + ->assertSee('Completed with evidence available') + ->assertSee('Post-run evidence available') + ->assertSee('Evidence snapshot #'.$snapshot->getKey()) + ->assertSee(EvidenceSnapshotResource::getUrl('view', ['record' => $snapshot], tenant: $tenant), false); +}); + +it('shows unavailable operation proof when a completed restore run has no linked operation', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $this->actingAs($user); + Filament::setTenant($tenant, true); + + $restoreRun = RestoreRun::withoutEvents( + fn (): RestoreRun => spec335CompletedRestoreRun($tenant, spec335BackupSet($tenant)), + ); + + Livewire::test(ViewRestoreRun::class, ['record' => $restoreRun->getKey()]) + ->assertSee('Completed, recovery proof incomplete') + ->assertSee('Operation proof unavailable') + ->assertSee('Post-run evidence unavailable') + ->assertDontSee('Open operation'); +}); + +it('does not leak cross-workspace operation or evidence links', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $this->actingAs($user); + Filament::setTenant($tenant, true); + + $foreignTenant = ManagedEnvironment::factory()->create(); + $foreignOperationRun = spec335RestoreOperationRun($foreignTenant); + $foreignSnapshot = EvidenceSnapshot::query()->create([ + 'managed_environment_id' => (int) $foreignTenant->getKey(), + 'workspace_id' => (int) $foreignTenant->workspace_id, + 'operation_run_id' => (int) $foreignOperationRun->getKey(), + 'status' => EvidenceSnapshotStatus::Active->value, + 'completeness_state' => EvidenceCompletenessState::Complete->value, + 'summary' => ['finding_count' => 0], + 'generated_at' => now(), + ]); + + $restoreRun = spec335CompletedRestoreRun($tenant, spec335BackupSet($tenant), $foreignOperationRun); + + Livewire::test(ViewRestoreRun::class, ['record' => $restoreRun->getKey()]) + ->assertSee('Operation proof unavailable') + ->assertSee('Post-run evidence unavailable') + ->assertDontSee(OperationRunLinks::tenantlessView($foreignOperationRun), false) + ->assertDontSee(EvidenceSnapshotResource::getUrl('view', ['record' => $foreignSnapshot], tenant: $foreignTenant), false); +}); + +it('preserves restore run view authorization semantics', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $this->actingAs($user); + + $restoreRun = spec335CompletedRestoreRun($tenant, spec335BackupSet($tenant)); + + $this->withSession([WorkspaceContext::SESSION_KEY => (int) $tenant->workspace_id]) + ->get(RestoreRunResource::getUrl('view', ['record' => $restoreRun], panel: 'admin', tenant: $tenant)) + ->assertOk(); + + $otherTenant = ManagedEnvironment::factory()->create(); + [$otherUser] = createUserWithTenant($otherTenant, role: 'owner'); + + $this->actingAs($otherUser) + ->withSession([WorkspaceContext::SESSION_KEY => (int) $otherTenant->workspace_id]) + ->get(RestoreRunResource::getUrl('view', ['record' => $restoreRun], panel: 'admin', tenant: $tenant)) + ->assertNotFound(); +}); diff --git a/apps/platform/tests/Unit/Filament/RestoreRunDetailPresenterDeterminismTest.php b/apps/platform/tests/Unit/Filament/RestoreRunDetailPresenterDeterminismTest.php new file mode 100644 index 00000000..81439e8e --- /dev/null +++ b/apps/platform/tests/Unit/Filament/RestoreRunDetailPresenterDeterminismTest.php @@ -0,0 +1,102 @@ +actingAs($user); + Filament::setTenant($tenant, true); + + $backupSet = BackupSet::factory()->create([ + 'managed_environment_id' => (int) $tenant->getKey(), + ]); + + $operationRun = OperationRun::factory()->forTenant($tenant)->create([ + 'type' => OperationRunType::RestoreExecute->value, + 'status' => OperationRunStatus::Completed->value, + 'outcome' => OperationRunOutcome::Succeeded->value, + 'completed_at' => now(), + ]); + + $restoreRun = RestoreRun::factory()->for($tenant, 'tenant')->for($backupSet)->create([ + 'status' => 'completed', + 'operation_run_id' => (int) $operationRun->getKey(), + 'metadata' => [ + 'total' => 1, + 'succeeded' => 1, + 'failed' => 0, + 'skipped' => 0, + 'partial' => 0, + 'non_applied' => 0, + ], + ]); + + $presenter = app(RestoreRunDetailPresenter::class); + + $first = $presenter->forRun($restoreRun->fresh(['backupSet', 'operationRun', 'tenant'])); + + expect(data_get($first, 'decision.state'))->toBe('completed_proof_incomplete') + ->and(data_get($first, 'operationProof.state'))->toBe('available') + ->and(data_get($first, 'postRunEvidence.state'))->toBe('unavailable'); + + EvidenceSnapshot::query()->create([ + 'managed_environment_id' => (int) $tenant->getKey(), + 'workspace_id' => (int) $tenant->workspace_id, + 'operation_run_id' => (int) $operationRun->getKey(), + 'status' => EvidenceSnapshotStatus::Active->value, + 'completeness_state' => EvidenceCompletenessState::Complete->value, + 'summary' => ['finding_count' => 0], + 'generated_at' => now(), + ]); + + $second = $presenter->forRun($restoreRun->fresh(['backupSet', 'operationRun', 'tenant'])); + + expect(data_get($second, 'decision.state'))->toBe('completed_with_evidence') + ->and(data_get($second, 'postRunEvidence.state'))->toBe('available') + ->and(data_get($second, 'postRunEvidence.identifier'))->toContain('Evidence snapshot #'); +}); + +it('does not expose operation proof from another workspace or environment', function (): void { + [$user, $tenant] = createUserWithTenant(role: 'owner'); + $this->actingAs($user); + Filament::setTenant($tenant, true); + + $backupSet = BackupSet::factory()->create([ + 'managed_environment_id' => (int) $tenant->getKey(), + ]); + + $foreignTenant = \App\Models\ManagedEnvironment::factory()->create(); + $foreignOperationRun = OperationRun::factory()->forTenant($foreignTenant)->create([ + 'type' => OperationRunType::RestoreExecute->value, + 'status' => OperationRunStatus::Completed->value, + 'outcome' => OperationRunOutcome::Succeeded->value, + 'completed_at' => now(), + ]); + + $restoreRun = RestoreRun::factory()->for($tenant, 'tenant')->for($backupSet)->create([ + 'status' => 'completed', + 'operation_run_id' => (int) $foreignOperationRun->getKey(), + ]); + + $surface = app(RestoreRunDetailPresenter::class) + ->forRun($restoreRun->fresh(['backupSet', 'operationRun', 'tenant'])); + + expect(data_get($surface, 'operationProof.state'))->toBe('unavailable') + ->and(data_get($surface, 'operationProof.url'))->toBeNull() + ->and(data_get($surface, 'postRunEvidence.state'))->toBe('unavailable'); +}); diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/.gitkeep b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/.gitkeep @@ -0,0 +1 @@ + diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/01-restore-run-draft.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/01-restore-run-draft.png new file mode 100644 index 00000000..8fa55a4c Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/01-restore-run-draft.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/02-restore-run-completed-proof-incomplete.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/02-restore-run-completed-proof-incomplete.png new file mode 100644 index 00000000..74f62ed3 Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/02-restore-run-completed-proof-incomplete.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/03-restore-run-operation-proof.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/03-restore-run-operation-proof.png new file mode 100644 index 00000000..ab48b5a3 Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/03-restore-run-operation-proof.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/04-restore-run-evidence-unavailable.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/04-restore-run-evidence-unavailable.png new file mode 100644 index 00000000..ab48b5a3 Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/04-restore-run-evidence-unavailable.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/05-restore-run-item-outcomes.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/05-restore-run-item-outcomes.png new file mode 100644 index 00000000..ab48b5a3 Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/05-restore-run-item-outcomes.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/06-restore-run-failed-if-supported.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/06-restore-run-failed-if-supported.png new file mode 100644 index 00000000..f4c07259 Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/06-restore-run-failed-if-supported.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/07-restore-run-diagnostics-collapsed.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/07-restore-run-diagnostics-collapsed.png new file mode 100644 index 00000000..ab48b5a3 Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/07-restore-run-diagnostics-collapsed.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/08-restore-run-dark-mode.png b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/08-restore-run-dark-mode.png new file mode 100644 index 00000000..253a3f29 Binary files /dev/null and b/specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/08-restore-run-dark-mode.png differ diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/checklists/requirements.md b/specs/335-restore-run-detail-post-execution-proof-productization/checklists/requirements.md new file mode 100644 index 00000000..8664e205 --- /dev/null +++ b/specs/335-restore-run-detail-post-execution-proof-productization/checklists/requirements.md @@ -0,0 +1,41 @@ +# Specification Quality Checklist: Spec 335 - Restore Run Detail / Post-Execution Proof Productization + +**Purpose**: Validate specification completeness and quality before implementation planning and execution. +**Created**: 2026-05-29 +**Feature**: `specs/335-restore-run-detail-post-execution-proof-productization/spec.md` + +## Content Quality + +- [x] No application implementation is included in the preparation artifacts. +- [x] Focused on operator value, safety, proof visibility, and post-execution decision support. +- [x] All mandatory repository sections are completed. +- [x] Spec preserves TenantPilot terminology and workspace/environment route context. + +## Requirement Completeness + +- [x] No `[NEEDS CLARIFICATION]` markers remain. +- [x] Requirements are testable and unambiguous. +- [x] Acceptance criteria are explicit and safety-focused. +- [x] Scope is clearly bounded to Restore Run detail productization. +- [x] Dependencies and assumptions are identified. + +## Constitution / Guardrail Alignment + +- [x] Spec Candidate Check is filled and passes SPEC-GATE-001. +- [x] UI Surface Impact and UI/Productization Coverage are filled for the changed detail surface. +- [x] Proportionality review rejects new persisted truth, enums/status families, and backend rewrites; any presenter is derived-only. +- [x] RBAC, workspace/environment isolation, and proof/evidence boundary semantics are addressed. +- [x] Test governance and validation lanes are explicit. + +## Feature Readiness + +- [x] `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, and `restore-result-state-contract.md` exist. +- [x] Tasks are ordered, small, verifiable, and implementation-ready. +- [x] Screenshot artifacts path is present. +- [x] Close alternatives and follow-up candidates are kept out of scope. + +## Notes + +- EvidenceSnapshot is model-real, but restore-linked evidence availability must remain repo-truthful (unavailable unless linked evidence exists). +- Implementation must not claim recovery is verified unless the repo introduces explicit verification semantics (out of scope here). + diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/plan.md b/specs/335-restore-run-detail-post-execution-proof-productization/plan.md new file mode 100644 index 00000000..0cb7505c --- /dev/null +++ b/specs/335-restore-run-detail-post-execution-proof-productization/plan.md @@ -0,0 +1,148 @@ +# Implementation Plan: Spec 335 - Restore Run Detail / Post-Execution Proof Productization + +- **Branch**: `335-restore-run-detail-post-execution-proof-productization` +- **Date**: 2026-05-29 +- **Spec**: `specs/335-restore-run-detail-post-execution-proof-productization/spec.md` +- **Input**: User-provided draft + repo inspection for truth (RestoreRun/OperationRun/EvidenceSnapshot + current Filament view implementation) + +## Summary + +Refactor the Restore Run detail surface into a decision-first post-execution result/proof/evidence view. + +This work is UI/productization only: + +- derive a top-level "restore result decision" contract from existing persisted fields (`restore_runs.results`, `restore_runs.metadata`, `restore_runs.operation_run_id`) and (when present) linked `evidence_snapshots` +- render one default-visible hierarchy: status/reason/impact/next action first; proof/evidence state explicit; diagnostics collapsed +- keep raw payloads and diagnostics behind disclosure +- preserve RBAC, tenant/workspace isolation, and existing route/context behavior + +No restore execution backend changes are in scope. + +## Technical Context + +- **Language/Version**: PHP 8.4.x +- **Primary Dependencies**: Laravel 12.x, Filament v5, Livewire v4 +- **Storage**: PostgreSQL (tenant-owned `restore_runs`, `operation_runs`, `evidence_snapshots`) +- **Testing**: Pest v4 + Livewire component testing; Browser tests for smoke/screenshots +- **Validation Lanes**: confidence + browser +- **Target Platform**: Laravel Sail (local); Dokploy (deploy) posture unchanged +- **Project Type**: Laravel monolith under `apps/platform` +- **Performance Goals**: avoid new expensive queries; prefer existing eager loads; only query evidence snapshots when an `operation_run_id` exists +- **Constraints**: no new packages; no migrations unless explicitly justified and approved in-spec +- **Scale/Scope**: one Filament view surface + related presenters/blade entries + tests/screenshots + +## UI / Surface Guardrail Plan + +- **Guardrail scope**: changed operator-facing detail surface (dangerous workflow result/proof) +- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: + - Restore Run detail view (`RestoreRunResource` view page) + - Restore result presentation (existing infolist entry view: `filament/infolists/entries/restore-results.blade.php`) + - Restore proof/evidence presentation (new or reused proof-aside surface) +- **Native vs custom classification summary**: native Filament page with shared primitives + a small amount of custom Blade in infolist entries +- **Shared-family relevance**: status messaging + proof/evidence deep links; diagnostics disclosure; shared OperationRun/Evidence viewers +- **State layers in scope**: page + detail + URL (optional dashboard context param already exists) +- **Audience modes in scope**: operator-MSP; no customer-facing change +- **Decision/diagnostic/raw hierarchy plan**: decision-first; diagnostics collapsed and secondary +- **Raw/support gating plan**: collapsed disclosures; never default-show raw payloads, exception text, or Graph error details as primary message +- **One-primary-action / duplicate-truth control**: exactly one dominant next action in the decision card; avoid repeating equivalent banners/cards in multiple sections +- **Handling modes**: review-mandatory (truth boundary / dangerous-workflow UX) +- **Special surface test profiles**: shared-detail-family + dangerous workflow proof surface +- **Required tests or manual smoke**: Feature/Livewire tests for contract visibility + RBAC/isolation; Browser smoke for screenshots and dark mode +- **Exception path and spread control**: if evidence is not repo-backed for restore runs, UI must state "unavailable" (do not invent) +- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage +- **UI/Productization coverage decision**: existing route/archetype; cover via Spec 335 screenshots + Feature/Browser tests + +## Shared Pattern & System Fit + +- **Cross-cutting feature marker**: yes (proof/evidence link semantics, decision-first status hierarchy) +- **Systems touched**: + - `App\Support\RestoreSafety\RestoreSafetyResolver` (result attention truth) + - `App\Support\Badges\BadgeRenderer` (status/evidence badge semantics) + - `App\Support\OperationRunLinks` + `OperationRunResource` (proof deep link) + - `EvidenceSnapshotResource` (evidence deep link, when present) +- **Shared abstractions reused**: reuse existing copy/badges and link resolvers; do not create new global status frameworks +- **New abstraction introduced?**: optional, narrow presenter for the Restore Run detail decision contract (derived only, no persistence) +- **Bounded deviation / spread control**: any presenter must live feature-locally and remain a pure derived view-model (no caching, no global registry) + +## OperationRun UX Impact + +- Link UX only: the Restore Run detail page will expose "Operation proof" and deep-link to the existing OperationRun view. +- No start/enqueue/dedupe semantics change. +- URLs must be generated via existing link helpers (`OperationRunLinks` / Filament resource `getUrl(...)`) to preserve workspace/environment context. + +## Data / Migrations + +- No migrations planned. +- No new persisted fields planned. +- Evidence is read-only: if evidence snapshots are present for the linked `operation_run_id`, show them; otherwise show honest "unavailable". + +## Implementation Approach + +### Phase 1 - Repo Truth (pre-work) + +- Document restore run model fields/statuses and result structures in `repo-truth-map.md`. +- Document the visible result/proof state machine in `restore-result-state-contract.md`. +- Confirm existing Restore Run view implementation and tests (current infolist entries and `RestoreResultAttentionSurfaceTest`). + +### Phase 2 - Result Presenter / View Model (derived only) + +- If needed, introduce a derived presenter that returns the UI contract: + - status label + reason + impact + primary next action + - operation proof state + URL (when authorized) + - post-run evidence state + URL (when repo-backed) + - result summary counts (from `restore_runs.metadata` and `restore_runs.results`) + - diagnostics default = collapsed + +### Phase 3 - Detail Page UI + +- Switch Restore Run view from "entries list" toward a main/aside layout: + - Main: decision card + result summary + item outcomes (table) + secondary run details + - Aside: proof panel (source backup, target environment, requested by, operation proof, post-run evidence, audit trail) + diagnostics disclosure +- Ensure raw payloads remain behind disclosure. + +### Phase 4 - Proof/Evidence Links + +- Operation proof: + - show status and link to OperationRun view when the restore run is linked to an operation run + - show "unavailable" when no operation run exists +- Evidence: + - query evidence snapshots for the restore run's `operation_run_id` (tenant-scoped) and surface state + link when present + - otherwise show "unavailable" (no fake "recovery verified") + +### Phase 5 - Tests + Browser Screenshots + +- Add/extend Feature tests to assert: + - decision question and status label for key states + - operation proof and evidence states are explicit + - diagnostics collapsed by default; raw payload not visible by default + - tenant/workspace isolation and capability gating (deny-as-not-found vs forbidden semantics preserved) +- Add a Browser smoke/screenshot test that captures the required screenshot set under the Spec 335 artifact path. + +## Validation Commands + +Planned (narrow) commands for implementation review: + +```bash +cd apps/platform + +./vendor/bin/sail artisan test \ + tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php \ + tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php \ + --compact +``` + +```bash +cd apps/platform + +./vendor/bin/sail php vendor/bin/pest \ + tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php \ + --compact +``` + +```bash +cd apps/platform + +./vendor/bin/sail pint --dirty +git diff --check +``` + diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/repo-truth-map.md b/specs/335-restore-run-detail-post-execution-proof-productization/repo-truth-map.md new file mode 100644 index 00000000..ad5f5bd1 --- /dev/null +++ b/specs/335-restore-run-detail-post-execution-proof-productization/repo-truth-map.md @@ -0,0 +1,187 @@ +# 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. diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/restore-result-state-contract.md b/specs/335-restore-run-detail-post-execution-proof-productization/restore-result-state-contract.md new file mode 100644 index 00000000..9805fbb8 --- /dev/null +++ b/specs/335-restore-run-detail-post-execution-proof-productization/restore-result-state-contract.md @@ -0,0 +1,142 @@ +# Spec 335 Restore Result State Contract (Decision-First) + +This contract defines the minimum decision-first states the Restore Run detail page must support. + +It is intentionally derived: it may combine multiple persisted statuses into one operator-facing decision state. + +## Fields (required on first screen) + +- Status (label) +- Reason +- Impact +- Primary next action +- Operation proof state (OperationRun) +- Post-run evidence state (EvidenceSnapshot, repo-backed only) +- Result summary (repo-backed only) +- Diagnostics default state: collapsed + +## Resolution Rules + +- Operation proof is available only when the linked `operation_runs` row is same-workspace, same-managed-environment, and authorized for the current user. +- Post-run evidence is repo-backed only. It is available for the latest authorized `active` evidence snapshot for the linked operation run, same workspace, and same managed environment. +- Evidence snapshots in `queued` or `generating` state may be shown as in progress. Absent, unauthorized, or cross-workspace evidence is unavailable. +- Result attention copy remains visible, but for completed restore runs it does not override the top-level proof/evidence decision unless the persisted restore status itself is partial/error. +- Aggregate result counts may be present without item-level rows. The UI must label that as metadata-only evidence and must not show it as "0 items" when counts indicate affected or follow-up work. + +## State Matrix + +### 1) Not Executed (Draft / Preview Only) + +- **State**: `not_executed` +- **Persisted triggers** (repo-verified): + - `restore_runs.is_dry_run = true`, OR + - `restore_runs.status in { draft, scoped, checked, previewed }` (pre-execution) +- **Visible status**: Not executed +- **Reason**: This record proves preview truth, not environment recovery. +- **Impact**: No execution proof or post-run evidence exists yet. +- **Primary next action**: Review preview / continue preparation (contextual to available actions) +- **Operation proof state**: Unavailable +- **Post-run evidence state**: Unavailable +- **Result summary**: + - If `restore_runs.metadata` has counts: show them + - Otherwise: show "Result summary unavailable" (no fake zeros) +- **Allowed proof claims**: "Preview evidence exists" (never "recovery verified") +- **Diagnostics default**: Collapsed + +### 2) Execution In Progress (Queued / Running) + +- **State**: `in_progress` +- **Persisted triggers** (repo-verified): + - `restore_runs.status in { queued, running }`, OR + - linked `operation_runs.status in { queued, running }` +- **Visible status**: Execution in progress +- **Reason**: Restore execution is currently running. +- **Impact**: Results and evidence are not final yet. +- **Primary next action**: View operation progress +- **Operation proof state**: In progress +- **Post-run evidence state**: Unavailable +- **Result summary**: show only repo-backed partial counts (if present); otherwise show "In progress" +- **Allowed proof claims**: "Execution in progress" only +- **Diagnostics default**: Collapsed + +### 3) Completed (Recovery Proof Incomplete) + +- **State**: `completed_proof_incomplete` +- **Persisted triggers**: + - terminal completed restore run (`status = completed`) + - post-run evidence snapshot not present, not active/current for the operation run, unauthorized, or cross-workspace +- **Visible status**: Completed, recovery proof incomplete +- **Reason**: Execution completed, but post-run evidence is not available yet. +- **Impact**: Do not treat this restore as verified recovery until evidence has been reviewed. +- **Primary next action**: Open operation proof when authorized proof exists; otherwise Review proof gap +- **Operation proof state**: Available if a scoped authorized operation run exists, otherwise Unavailable for legacy/imported rows +- **Post-run evidence state**: Unavailable +- **Result summary**: repo-backed counts from `restore_runs.metadata` when present +- **Allowed proof claims**: "Execution proof available" (never "recovery verified") +- **Diagnostics default**: Collapsed + +### 4) Completed (Evidence Available) + +- **State**: `completed_with_evidence` +- **Persisted triggers**: + - terminal completed restore run + - at least one authorized `active` evidence snapshot exists for the same `operation_run_id`, workspace, and managed environment +- **Visible status**: Completed with evidence available +- **Reason**: Execution proof and post-run evidence are available. +- **Impact**: Review evidence before treating the restore as recovery proof. +- **Primary next action**: Open evidence +- **Operation proof state**: Available +- **Post-run evidence state**: Available +- **Result summary**: repo-backed counts from `restore_runs.metadata` +- **Allowed proof claims**: + - allowed: "Evidence snapshot available" + - forbidden: "Recovery verified", "Healthy", "Compliant", "Customer-safe" +- **Diagnostics default**: Collapsed + +### 5) Completed With Items Needing Review (Partial / Follow-Up) + +- **State**: `needs_review` +- **Persisted triggers** (repo-verified via `RestoreResultAttention`): + - `restore_runs.status in { partial, completed_with_errors }` + - `RestoreSafetyResolver::resultAttentionForRun(...).state in { partial, completed_with_follow_up }` is still displayed as secondary result-attention copy/badging for `completed` runs, but does not supersede the top proof/evidence decision. +- **Visible status**: Completed with items needing review +- **Reason**: Some items were skipped, partially applied, or failed. +- **Impact**: Review item outcomes before relying on the result. +- **Primary next action**: Review item outcomes +- **Operation proof state**: Available (if `operation_run_id` exists), otherwise Unavailable +- **Post-run evidence state**: Available/Unavailable (repo-backed only; never implied) +- **Result summary**: show repo-backed counts (failed/skipped/partial/non_applied) when present +- **Allowed proof claims**: "Follow-up required" / "Skipped items exist" etc (no recovery claims) +- **Diagnostics default**: Collapsed + +### 6) Failed + +- **State**: `failed` +- **Persisted triggers** (repo-verified): + - `restore_runs.status = failed`, OR + - linked operation run outcome = `failed` +- **Visible status**: Restore failed +- **Reason**: The restore did not complete successfully. +- **Impact**: Some requested changes may not have been applied. +- **Primary next action**: Review failure details +- **Operation proof state**: Available (if `operation_run_id` exists); otherwise Unavailable +- **Post-run evidence state**: Unavailable (unless repo truth indicates otherwise) +- **Result summary**: show repo-backed counts when present; otherwise show "Failure details required" +- **Allowed proof claims**: "Execution failed" only; never "recovery verified" +- **Diagnostics default**: Collapsed + +### 7) Cancelled / Blocked + +- **State**: `blocked_or_cancelled` +- **Persisted triggers**: + - `restore_runs.status = cancelled`, OR + - linked operation run outcome = `blocked` +- **Visible status**: Restore blocked / cancelled +- **Reason**: Restore did not execute due to cancellation or blocker. +- **Impact**: No recovery proof exists. +- **Primary next action**: Review blocker +- **Operation proof state**: Available (if operation run exists); otherwise Unavailable +- **Post-run evidence state**: Unavailable +- **Result summary**: show "Unavailable" unless repo-backed +- **Allowed proof claims**: none beyond the above +- **Diagnostics default**: Collapsed diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/spec.md b/specs/335-restore-run-detail-post-execution-proof-productization/spec.md new file mode 100644 index 00000000..7f4f1b7a --- /dev/null +++ b/specs/335-restore-run-detail-post-execution-proof-productization/spec.md @@ -0,0 +1,267 @@ +# Feature Specification: Spec 335 - Restore Run Detail / Post-Execution Proof Productization + +- **Feature Branch**: `335-restore-run-detail-post-execution-proof-productization` +- **Created**: 2026-05-29 +- **Status**: Draft +- **Type**: Runtime UX productization / Restore result proof surface / no backend rewrite +- **Runtime posture**: Productize the existing Restore Run detail surface using repo-backed `RestoreRun` + `OperationRun` + (when present) `EvidenceSnapshot`. No restore engine rewrite. +- **Input**: User-provided draft (originally drafted as "Spec 334"; number `334-*` is already used in this repo, so this package is Spec 335). + +## Dependency Context + +This spec is intentionally downstream of Restore Create. + +- Spec 332 - Product Process Flow System v1 +- Spec 333 - Restore Create UX Final Productization +- Spec 329 - Evidence / Audit Log Disclosure Productization +- Spec 328 - Operations Hub Decision-First Workbench Productization +- Spec 325 - Screenshot-Anchored Strategic Target Images + +## Summary + +Spec 333 productized the Restore Create wizard. Spec 335 productizes what happens after a restore run exists: + +- What was requested? +- What executed, what was skipped, what failed? +- Is execution proof available via `OperationRun`? +- Is post-run evidence available (repo-backed), or missing? +- What is the next safest operator action? + +The goal is to prevent Restore Run detail from reading like a raw record view, log dump, or technical payload surface. + +## Product Goal + +The Restore Run detail page must answer: + +```text +Was this restore executed safely, and is recovery proof available? +``` + +First screen (default-visible) must show: + +```text +Status +Reason +Impact +Primary next action +OperationRun proof +Post-run evidence state +Restore result summary +Diagnostics collapsed +``` + +Raw logs, payloads, and item JSON must not be required to understand outcome. + +## Spec Candidate Check *(mandatory - SPEC-GATE-001)* + +- **Problem**: Restore Run "View" is still a mixed detail surface where operators can miss the distinction between execution completion, execution proof, and post-run recovery evidence. +- **Today's failure**: "Completed" can read as "safe/verified" unless the UI explicitly frames proof and evidence boundaries and presents one decision-first outcome model. +- **User-visible improvement**: Restore Run detail becomes decision-first: explicit status, reason, impact, and one primary next action; execution proof and post-run evidence are shown separately with honest availability states. +- **Smallest enterprise-capable version**: Productize the existing view surface using derived state from existing `RestoreRun.results/metadata` + `OperationRun` link + optional `EvidenceSnapshot` link(s). No new restore execution behavior. No new tables or migrations. +- **Explicit non-goals**: No new restore engine behavior, no new Graph calls, no new `OperationRun` types or lifecycle semantics, no new evidence generation pipeline, no new backend "recovery verified" semantics, no new packages, no new deployment steps. +- **Permanent complexity imported**: A small view-model/presenter (only if needed), refined Blade/Infolist layout, focused Feature/Browser tests, and spec screenshots. +- **Why now**: Restore is a high-risk workflow. Spec 333 made Create safe and decision-first; the next operator moment is post-execution truth and proof. +- **Why not local**: This is a cross-cutting truth/presentation boundary (execution proof vs evidence) that must be made explicit once and reused; page-local ad-hoc copy will drift. +- **Approval class**: Core Enterprise +- **Red flags triggered**: Dangerous workflow UX, status/proof messaging, evidence claims. Defense: bounded UI productization only; no new truth sources; explicit boundaries; tests + screenshots. +- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 1 | **Gesamt: 11/12** +- **Decision**: approve + +## Spec Scope Fields *(mandatory)* + +- **Scope**: tenant / managed-environment operator surface +- **Primary Routes**: + - `/admin/workspaces/{workspace}/environments/{environment}/restore-runs/{record}` (Restore Run detail) +- **Data Ownership**: + - Tenant-owned: `restore_runs` (JSON fields `preview`, `results`, `metadata`) + `operation_runs` (execution proof) + optional `evidence_snapshots` (post-run evidence). + - No new persisted entity/table. +- **RBAC**: + - Existing workspace membership + tenant entitlement remains authoritative. + - Existing `Capabilities::TENANT_VIEW` gates access; non-member access remains deny-as-not-found (404); member missing capability remains 403. + +## UI Surface Impact *(mandatory - UI-COV-001)* + +Does this spec add, remove, rename, or materially change any reachable UI surface? + +- [ ] No UI surface impact +- [x] Existing page changed +- [ ] New page/route added +- [ ] Navigation changed +- [ ] Filament panel/provider surface changed +- [ ] New modal/drawer/wizard/action added +- [x] New table/form/state added +- [ ] Customer-facing surface changed +- [ ] Dangerous action changed +- [x] Status/evidence/review presentation changed +- [x] Workspace/environment context presentation changed + +## UI/Productization Coverage + +- **Route/page/surface**: Restore Run detail (`RestoreRunResource` view page; infolist + Blade entries) +- **Current or new page archetype**: Domain Pattern Surface (post-execution result/proof) +- **Design depth**: Manual Review Required (dangerous-workflow truth surface) +- **Repo-truth level**: repo-verified (existing view surface + existing result attention contract + existing `OperationRun` relation) +- **Existing pattern reused**: existing `RestoreResultAttention` truth, BADGE-001 badges, existing restore proof panel patterns, OperationRun/Evidence resources. +- **New pattern required**: decision-first "result contract" wrapper that includes operation proof + evidence state explicitly (no new truth sources). +- **Screenshot required**: yes, `specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/` +- **Page audit required**: no (existing route/archetype); screenshots are the primary proof artifact +- **Customer-safe review required**: no (operator surface) +- **Dangerous-action review required**: yes (restore workflow semantics; avoid false recovery claims) +- **Coverage files updated or explicitly not needed**: + - [x] `N/A - existing route/archetype; proof via Spec 335 screenshots` + +## Cross-Cutting / Shared Pattern Reuse + +- **Cross-cutting feature?**: yes +- **Interaction class(es)**: status messaging, deep links, evidence/proof viewers, diagnostics disclosure +- **Systems touched**: + - `RestoreSafetyResolver::resultAttentionForRun()` (existing result attention truth) + - `OperationRunLinks` + `OperationRunResource` (execution proof) + - `EvidenceSnapshotResource` (post-run evidence viewer, when repo-backed) + - `BadgeRenderer` domains (status + evidence badges) +- **Existing pattern(s) to extend**: restore "what this proves / what it does not prove" boundary copy; decision-first card hierarchy; diagnostics collapsed by default +- **Allowed deviation and why**: none; any new presenter must remain a thin derived view-model (no persisted truth) +- **Consistency impact**: restore result decision copy + proof availability labels must remain stable across view + dashboards (no parallel local wording) +- **Review focus**: no false "recovery verified" claim; one primary next action; diagnostics and raw payload stay collapsed/secondary; links stay tenant/workspace-safe + +## OperationRun UX Impact + +- **Touches OperationRun start/completion/link UX?**: link UX only (deep-link to operation proof) +- **Shared OperationRun UX contract/layer reused**: `OperationRunLinks` (no local URL composition) +- **Delegated start/completion UX behaviors**: `Open operation` link only; no new toasts/events/dedupe +- **Queued DB-notification policy**: `N/A` +- **Terminal notification path**: `N/A` +- **Exception required?**: none + +## Provider Boundary / Platform Core Check + +N/A - no shared provider/platform boundary is changed. This is presentation/productization on existing persisted truth. + +## Repo-Truth First Requirement *(hard requirement)* + +Before runtime changes, this package must include a repo truth map: + +- `specs/335-restore-run-detail-post-execution-proof-productization/repo-truth-map.md` + +The map must classify each data point as: + +```text +repo-verified | derived from existing model | foundation-real | not available | deferred +``` + +Do not invent post-run proof states that are not repo-backed. + +## Required UX Contract + +The visible UI must expose a top-level result decision model (fields may be derived from existing contracts): + +```php +[ + 'status' => 'completed_recovery_proof_incomplete', + 'status_label' => 'Completed, recovery proof incomplete', + 'reason' => 'Execution completed, but post-run evidence is not available yet.', + 'impact' => 'Do not treat this restore as verified recovery until evidence has been reviewed.', + 'primary_next_action' => 'Open operation proof', + 'primary_next_url' => '...', + 'operation_proof' => [ + 'state' => 'available', + 'label' => 'Operation proof available', + 'url' => '...', + ], + 'post_run_evidence' => [ + 'state' => 'unavailable', + 'label' => 'Post-run evidence unavailable', + 'url' => null, + ], + 'result_summary' => [ + 'requested' => 10, + 'applied' => 8, + 'skipped' => 1, + 'failed' => 1, + 'needs_review' => 2, + ], + 'diagnostics_state' => 'collapsed', +] +``` + +Exact implementation may differ, but the visible page must uphold this hierarchy and boundary. + +## Restore Result States + +Minimum supported product states are defined in: + +- `specs/335-restore-run-detail-post-execution-proof-productization/restore-result-state-contract.md` + +The UI must not imply "recovery verified" unless repo-backed verification semantics exist. + +## Scope + +### In Scope + +- Productize Restore Run detail view surface (decision-first result/proof/evidence) +- OperationRun proof panel (link + status context, not raw logs first) +- Post-run evidence availability state (link when repo-backed) +- Result summary and item outcome table (only when repo-backed) +- Diagnostics/raw details collapsed by default +- Spec 335 tests and screenshots + +### Out of Scope + +- Restore engine / execution backend changes +- New Graph calls or provider gateway behavior +- New `OperationRun` semantics or model rewrites +- New evidence generation pipeline or migrations (unless explicitly justified and added to the spec first) +- New packages, env vars, scheduler/queue/storage changes +- Restore Create wizard redesign (Spec 333 owns Create UX) + +## Proportionality Review *(mandatory when structural complexity is introduced)* + +This spec may introduce a small presenter/view-model. + +- **New source of truth?**: no +- **New persisted entity/table/artifact?**: no (spec artifacts + screenshots only) +- **New abstraction?**: yes, a thin derived presenter if the page needs one decision-contract output (no persistence, no global framework) +- **New enum/state/reason family?**: no persisted family; any "status label" is derived display-only +- **Current operator problem**: post-execution restore truth/proof/evidence is not decision-first enough. +- **Narrowest correct implementation**: derived view-model + layout/product copy refinements on existing persisted data. +- **Alternative intentionally rejected**: introducing new persisted "recovery proof" models or new workflow frameworks. +- **Release truth**: current-release UX productization. + +### Compatibility posture + +Pre-production: prefer replacement over shims. No legacy alias paths are introduced. + +## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* + +- **Test purpose / classification**: Feature/Livewire + Browser (plus Unit if a presenter is introduced) +- **Validation lane(s)**: confidence + browser; formatting via Pint; whitespace guard via `git diff --check` +- **Why sufficient**: this is a user-facing operator detail surface with truth-boundary risk; Feature tests prove default-visible hierarchy; Browser smoke provides final UI proof and screenshots. + +## Acceptance Criteria + +### Product + +- Restore Run detail is decision-first. +- First screen answers whether execution proof and post-run evidence are available. +- OperationRun proof is visible and linked where authorized. +- Post-run evidence state is visible and truthful. +- Result summary and item outcomes are shown only when repo-backed. +- Diagnostics are collapsed by default. + +### Safety + +- Completed execution does not imply recovery verified. +- No false evidence claim is displayed. +- Raw payloads/logs are hidden by default. + +### Context / RBAC + +- Workspace/environment isolation is preserved. +- Cross-workspace proof/evidence is not visible. +- No legacy `/admin/t` or tenant query alias is introduced. + +### Technical + +- No backend rewrite. +- No migrations unless explicitly justified and added to this spec before implementation. +- No new packages. diff --git a/specs/335-restore-run-detail-post-execution-proof-productization/tasks.md b/specs/335-restore-run-detail-post-execution-proof-productization/tasks.md new file mode 100644 index 00000000..a35587eb --- /dev/null +++ b/specs/335-restore-run-detail-post-execution-proof-productization/tasks.md @@ -0,0 +1,127 @@ +# Tasks: Spec 335 - Restore Run Detail / Post-Execution Proof Productization + +**Input**: + +- `specs/335-restore-run-detail-post-execution-proof-productization/spec.md` +- `specs/335-restore-run-detail-post-execution-proof-productization/plan.md` +- `specs/335-restore-run-detail-post-execution-proof-productization/repo-truth-map.md` +- `specs/335-restore-run-detail-post-execution-proof-productization/restore-result-state-contract.md` + +**Tests**: Required. This spec changes an operator-facing dangerous-workflow detail surface and must prove decision-first truth boundaries. + +## Test Governance Checklist + +- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior. +- [x] New or changed tests stay in the smallest honest family, and browser additions are explicit. +- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default. +- [x] Planned validation commands cover the change without pulling in unrelated lane cost. +- [x] The dangerous-workflow proof/evidence surface profile is explicit. +- [x] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR. + +## Phase 1: Repo Truth (blocks runtime changes) + +**Purpose**: Freeze repo truth for RestoreRun results/proof/evidence before changing UI. + +- [x] T001 Re-read `spec.md`, `plan.md`, and this `tasks.md`. +- [x] T002 Verify current Restore Run view implementation and state sources: + - `apps/platform/app/Filament/Resources/RestoreRunResource.php` (infolist + `detailResultsState`) + - `apps/platform/resources/views/filament/infolists/entries/restore-results.blade.php` + - `apps/platform/app/Support/RestoreSafety/RestoreSafetyResolver.php` (`resultAttentionForRun`) +- [x] T003 Update/confirm `repo-truth-map.md` is accurate for: + - `RestoreRun` model fields + `RestoreRunStatus` values + - results shape (`results.foundations`, `results.items`) and summary counts (`metadata.total/succeeded/failed/skipped/partial/non_applied`) + - `operation_run_id` relationship + current OperationRun outcome/status behavior + - Evidence snapshot availability (query path, status/completeness enums) +- [x] T004 Update/confirm `restore-result-state-contract.md` is aligned to repo truth (no invented evidence/proof states). + +## Phase 2: Restore Run Detail Presenter (derived view-model, optional) + +**Purpose**: Ensure one decision-first UI contract drives the view surface. + +- [x] T005 Decide whether a presenter/view-model is needed. If the view becomes a multi-section surface (decision card + proof panel + evidence state + table), prefer a presenter to avoid page-local logic drift. +- [x] T006 If introduced, implement a thin derived presenter that outputs: + - `status_label`, `reason`, `impact`, `primary_next_action` + - `operation_proof` state + URL (tenant/workspace-safe, capability-gated) + - `post_run_evidence` state + URL (repo-backed only) + - `result_summary` counts (repo-backed only) + - `diagnostics_state = collapsed` +- [x] T007 Prove presenter output determinism with Unit tests (no static memoization). + +## Phase 3: Detail Page UI (decision-first main/aside) + +**Purpose**: Productize the page layout and hierarchy. + +- [x] T008 Refactor Restore Run view page into a main/aside hierarchy: + - Main: decision card + result summary + item outcomes (table) + secondary run details + - Aside: proof panel (source backup, target env, requested by, operation proof, post-run evidence, audit trail) + diagnostics collapsed +- [x] T009 Ensure diagnostics and raw payloads remain collapsed/secondary by default (no stack traces, no raw JSON as primary UI). +- [x] T010 Ensure the page does not display "recovery verified", "healthy", "compliant", or "customer-safe" claims unless repo truth supports that semantics. + +## Phase 4: Proof/Evidence Links (repo-backed only) + +**Purpose**: Make execution proof and post-run evidence explicit, separate, and truthful. + +- [x] T011 Operation proof: + - restore run with `operation_run_id` shows proof state + link to OperationRun detail + - restore run without operation run shows "unavailable" state +- [x] T012 Post-run evidence: + - when evidence snapshots exist for the linked operation run (tenant-scoped), show state + link to Evidence Snapshot detail + - when absent, show "unavailable" and do not imply recovery proof + +## Phase 5: Item Outcomes (table-first, no payload dump) + +**Purpose**: Make per-item outcomes reviewable without flooding the page. + +- [x] T013 Render item outcomes as a table (not large cards) when `results.items` exists. +- [x] T014 Show compact summary counts from `restore_runs.metadata` (only when repo-backed; no fake zeros). +- [x] T015 Keep raw per-item payload/diff/diagnostics behind disclosure. + +## Phase 6: RBAC / Isolation + +- [x] T016 Add at least one positive and one negative authorization test for Restore Run view access. +- [x] T017 Prove cross-workspace/tenant proof and evidence links cannot leak (deny-as-not-found semantics preserved). + +## Phase 7: Tests + +- [x] T018 Add Feature test: `apps/platform/tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php` covering: + - decision question visible + - "Completed" does not imply recovery verified + - operation proof state visible + - post-run evidence state visible and truthful + - diagnostics collapsed; raw payload hidden by default +- [x] T019 Extend or align with existing coverage: + - `apps/platform/tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php` +- [x] T020 Add Browser smoke/screenshot test: `apps/platform/tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php`. + +## Phase 8: Screenshots + +- [x] T021 Capture required screenshots under: + - `specs/335-restore-run-detail-post-execution-proof-productization/artifacts/screenshots/` +- [x] T022 Capture at least: + - `01-restore-run-draft.png` + - `02-restore-run-completed-proof-incomplete.png` + - `03-restore-run-operation-proof.png` + - `04-restore-run-evidence-unavailable.png` + - `05-restore-run-item-outcomes.png` + - `06-restore-run-failed-if-supported.png` + - `07-restore-run-diagnostics-collapsed.png` + - `08-restore-run-dark-mode.png` + +If a state is not reachable via fixtures, document why in the Spec 335 notes (do not fake coverage). + +## Phase 9: Validation + +- [x] T023 Run: + - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec335RestoreRunDetailProductizationTest.php tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php --compact` + - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec335RestoreRunDetailProductizationSmokeTest.php --compact` + - `cd apps/platform && ./vendor/bin/sail pint --dirty` + - `git diff --check` + +## Explicit Non-Goals + +- [x] NT001 Do not change restore execution backend behavior. +- [x] NT002 Do not add new Graph calls or ProviderGateway behavior. +- [x] NT003 Do not change `OperationRun` lifecycle semantics (link-only). +- [x] NT004 Do not add migrations, packages, env vars, queues, scheduler, or storage changes. +- [x] NT005 Do not redesign Restore Create wizard (Spec 333 owns Create UX). +- [x] NT006 Do not introduce any false recovery-proof claims.