Skip to content

fix(recovery): expose typed lifecycle transitions and actionable blockers #240

Open

Description

@ebarti

Implementation progress - 1 November 2026

Partial implementation; acceptance remains open. Merged #262 provides shared typed lifecycle assessments and custody checks; merged #248 repairs ordinary native merge preparation. Merged #274 (merge commit 2d52d3f10608ea099c7a0a1e924992b1f3b95ee4) adds named blockers and shared observations for selected recovery owners, including historical repair authority, attempts and effects. Exact command replay checks retained identity and fails closed on corrupt or conflicting receipts, while preserving authentic historical replies after later progress.

Verification: Public API, owned Git/SQLite, local Temporal and concurrent replay scenarios exercised the selected routes. The configured hosted checks and CodeQL passed for the reviewed #274 head. Unsupported or unproven custody remains unknown.

Configured hosted qualification on the reviewed pre-merge head/base authenticated Check 41332643263, all five jobs, CodeQL, ZIP digests and four complete disjoint reports/JUnit: 1,426 runtime passes and 188 source passes. Four existing runtime and three existing source opt-in/capability bodies remain skipped and unexecuted.

Remaining: Pre-plan same-run recovery, owner-specific predicates across every recovery route, removal of remaining error-text classification, and the full public transition/restart table are not complete. Native descendant settlement and full issue acceptance remain separate. This progress report does not close the issue; the required behavior and acceptance below remain authoritative.
Earlier text below describes the historical #238 candidate. PR #238 and foundation stack #253 have merged; statements calling them open are historical.

Problem and evidence

Supported recovery commands currently authenticate many special cases independently. A valid retained state can fall between them: failure before an accepted plan, implementation completed before publication, failed validation with later cleanup confirmation, or an uncertain publication. Generic errors such as “requires a closed, finalized failed gate and released claim” do not identify which fact is missing.

The owners include delivery_gate_retry.py, delivery_stopped_resume.py and the preparation/publication/cleanup recovery modules. Existing narrow repairs must remain valid; this issue does not authorize relaxing evidence or ownership guards.

Required behavior

  • Define one versioned lifecycle/transition contract, including pending, running, stopping, stopped, recovering and terminal states, with extension points for pause.
  • Represent eligibility as typed predicates and structured blocker codes with the exact missing fact, responsible owner, supported next action and whether user input is genuinely required.
  • Cover pre-plan preparation failure, completed unpublished implementation, same-candidate failed gates, interrupted cleanup, unknown publication effects, exhausted product budget and restart/reboot.
  • Make public preflight and execution use the same transition rules. A valid preflight cannot select a route that its corresponding execution rejects solely because another validator interprets the same facts differently.
  • Require fresh proof for changed candidates/owners while retaining immutable prior evidence. Do not authorize recovery by matching English error text.
  • Keep an unrepairable/unknown state truthful and actionable; never invent successful cleanup or released custody.

Acceptance

Build an explicit transition table with representative real retained states. Exercise each supported recovery via API/CLI, including states before plan acceptance and after later cleanup reconciliation. Every refused transition must return specific unmet predicates rather than only the aggregate error.

Verify compatibility with historical admissions and that repeated recovery requests cannot create concurrent owners, broaden scope or reset budgets.

Existing implementation to reuse

PR #238 is open at bfc918a545ce820f47c814e99a6fe5e92b1c3fc1, matching the inspected installed runtime. Reuse its bounded diagnostic and prerequisite-only retry routes. This issue consolidates their state contract and reports typed eligibility across combinations, without weakening original custody.

Dependencies

Blocked by:

These are required contracts for this issue's acceptance. Related work without a blocking relationship can proceed in parallel.

Blocks:

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions