Skip to content

F22.6 — Installer transactions with honest recovery

State Closed
Parent E22
Iteration Release 9
Start Date 2026-11-14
Closed Date 2026-11-16
Predecessors F22.3

Stories: 3 Closed

Story State Depends on
S22.6.1 — Exercise recovery failures Closed (2026-11-14) S22.6.3
S22.6.2 — Separate prepare from mutation Closed (2026-11-15) S22.6.1
S22.6.3 — Decide the recovery contract Closed (2026-11-14) —

Keep release preparation, mutation and recovery readable and independently testable.

Context

install/lifecycle.py mixes download preparation and filesystem transaction work; _activate executes undo callbacks in a loop (:268-278) where one undo exception stops remaining recovery and masks the initiating failure. The install contract currently promises that everything is undone. The finally block then removes the work directory, which may still contain the displaced working version after a failed force-reinstall recovery. CLI lifecycle also duplicates verb declarations in VERBS and _COMMANDS.

S22.6.1 — Exercise recovery failures

State: Closed (2026-11-14) · Depends on: S22.6.3

Implement the recovery contract S22.6.3 settled (option B), with temporary homes and controlled injected failures, including a failure in an undo step.

Acceptance:

  • A failed undo does not prevent independent remaining recovery attempts; reports retain the initiating failure and incomplete recovery details.
  • Tests inspect links, current version, state and prior files after failures at each mutation boundary and during interruption.
  • No success/fully-rolled-back message is emitted while recovery remains incomplete; displaced installs and needed recovery material survive failed restoration.
  • The two TestRecoveryFailure reproductions pass without their xfail markers; cleanup and a later install leave a retained directory alone; the lifecycle guide and the install docstring state the settled contract.

Outcome: a retained version lives in a unique .work/<version>-* directory, which the error message names; cleanup logs and keeps it.

S22.6.2 — Separate prepare from mutation

State: Closed (2026-11-15) · Depends on: S22.6.1

Extract focused release-preparation and activation/recovery functions only where it removes shared mutable state or repeated work. Keep CLI orchestration thin.

Acceptance:

  • Checksums and release validation complete before activation, and failed preparation leaves the prior installation usable.
  • Install/upgrade/uninstall and interruption scenarios preserve locking, ownership and transactional behavior; advertised verbs derive from the registry and malformed lifecycle tables receive diagnosed errors.
  • Repeated release reads/hashes are measured before caching; no speculative installer protocol or product package is introduced.

Settled contract: _install orchestrates _prepare (work directory, download, checksum, extract; cleans up on failure), _activate, _recover and _failure; messages are unchanged; VERBS = tuple(_COMMANDS) is the one verb registry; LifecycleSurface.load rejects a non-table [lifecycle] and verbs that is not a list of strings; no release caching.

Outcome: a 64 MiB install downloads, hashes and extracts once (0.12 s, 0.5 MB peak traced); preparation failures through install are now tested.

S22.6.3 — Decide the recovery contract

State: Closed (2026-11-14)

The install contract promises that everything is undone. Reproduce an undo step that fails and a forced reinstall whose restoration fails, then decide what is recoverable, what survives a failed restoration and how the initiating and recovery failures are both reported.

Acceptance:

  • Failing tests reproduce the stopped recovery loop and the removed work directory.
  • The install contract states what recovery guarantees, what is reported when it is incomplete, and what material survives a failed restoration.
  • Settled (owner, 2026-11-14): option B. Recovery attempts every undo step in reverse, even after one fails. An Exception is re-raised as an AppException naming the initiating failure (its __cause__). It says "rolled back" only when every step succeeded; otherwise it says recovery is incomplete and names each failed step. If restoring a displaced version fails, its transaction directory under .work is retained, and the report names that path. cleanup leaves retained directories in place, and a new transaction never reuses or deletes one. uninstall still removes everything. An interruption is re-raised as-is after recovery, with any recovery failures and the retained path logged as errors. No doctor finding or recover verb (option C) is added.
  • Outcome: strict-xfail reproductions in tests/install/test_lifecycle.py::TestRecoveryFailure.

Acceptance

  • S22.6.1: A failed undo does not prevent independent remaining recovery attempts; reports retain the initiating failure and incomplete recovery details.
  • S22.6.2: Checksums and release validation complete before activation, and failed preparation leaves the prior installation usable.
  • S22.6.3: The install contract states what recovery guarantees and reports.