ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/335-restore-run-detail-post-execution-proof-productization/restore-result-state-contract.md
ahmido 4edb047901 feat: productize restore run detail proof surface (#404) 
## Summary
- productize the Restore Run detail surface around post-execution proof, evidence availability, and decision-first outcome framing
- add a dedicated restore run detail presenter and update the resource/detail rendering for clearer result and diagnostics states
- add Spec 335 feature, unit, and browser coverage plus screenshot artifacts

## Testing
- Not run as part of this commit/PR task

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #404
2026-05-29 01:20:55 +00:00

7.3 KiB
Raw Permalink Blame History

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