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
TestRecoveryFailurereproductions pass without their xfail markers;cleanupand a later install leave a retained directory alone; the lifecycle guide and theinstalldocstring 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
Exceptionis re-raised as anAppExceptionnaming 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.workis retained, and the report names that path.cleanupleaves retained directories in place, and a new transaction never reuses or deletes one.uninstallstill removes everything. An interruption is re-raised as-is after recovery, with any recovery failures and the retained path logged as errors. Nodoctorfinding 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.