nexu-io__open-design/docs/testing/updater-lifecycle.md

Install + updater lifecycle coverage map

The single reference for where every install/updater lifecycle node is tested. When an updater change touches a node, run its owning tests (plus the matrix in tools/pack/AGENTS.md → "Validation matrix for updater changes") and update this map if ownership moves. Nodes marked manual-only are deliberate; do not silently automate or drop them without revisiting the rationale here.

Legend — U: unit/component (package tests/), P: packaged platform spec (e2e/specs/mac.spec.ts / win.spec.ts via release-smoke.ts), F: real-feed validated, M: manual-only.

A. Acquisition and first install

Node	Coverage	Owning tests
Installer download + sha256 from the release feed	P, F	mac/win spec download flow; desktop updater.test.ts checksum trio
mac DMG install (ditto path)	P	mac spec install/start/inspect/stop/uninstall
mac DMG drag-install UI	M	human acceptance; harness uses ditto
win NSIS silent install + transactional log contract	P	win spec assertTransactionalInPlaceInstallLog
win NSIS interactive UI install	M	human acceptance per tools/pack/AGENTS.md
Channel identity (bundle name, registry key, install dir)	U, P	tools-pack win-identity.test.ts; specs
First-boot bootstrap (current-package, runtime.json gen0, install.json)	U, P	packaged launcher-runtime.test.ts; specs
Onboarding first run	P	mac/win onboarding smoke (@electron-smoke)

B. Steady-state check loop

Node	Coverage	Owning tests
Scheduler cadence / backoff / stop-after-install	U	desktop updater.test.ts scheduler group
Metadata fetch/parse/channel match, per-channel version fields	U, P, F	desktop unit; specs; real beta feed loop
not-available / available / downloaded-stays-visible	U, P	desktop unit; specs
Silent startup payload update (allowSilentUpdates)	U, P	desktop unit silent group; mac/win spec applies a downloaded payload silently on the next cold start
Artifact selection (payload vs installer, context validity)	U, P	desktop unit routing group; specs
Installer-reinstall floor (control.launcher.version.min): three reasons, same-version offer, clamp	U, P	desktop unit reseed group; spec recovery segment
Installed-outer version read (bundle config, env override)	U, P	desktop unit resolveInstalledOuterVersion; spec recovery segment reads the real outer

C. Download and integrity

Node	Coverage	Owning tests
Triple checksum verify (downloader, post-download, pre-install)	U	desktop unit
In-session resume; cross-session interrupted-download clearing	U	desktop unit (fixture byte ranges)
On-disk release adoption; store ownership/shape validation	U, P	desktop unit; specs

D. Payload apply chain

Node	Coverage	Owning tests
activate (generation++) → after-quit takeover → confirm	U, P, F	packaged + desktop unit; specs; real-feed loop
Delegated pre-arm (--od-launcher-delegated-*)	U	launcher-proto selection; packaged delegation/launch tests; desktop activation test
Crash rollback to lastSuccessful + self-heal on next release	P	mac/win spec rolls back a crashing payload and self-heals on the next good update
Stale relaunch freeze scrub after rollback (installResult.activeVersion > running)	U, P	desktop unit stale-freeze spec; exercised by the spec's self-heal phase
Exact desktop identity, cold-start reconvergence	P, F	specs; real-feed loop
Historical-outer handoff bridge (prepared→armed→confirmed)	U, partial P	daemon handoff unit; win spec legacy-executable path
Full historical-outer migration with a real legacy binary	M	needs a genuinely old installed generation
Obsolete outer retirement (mac/win)	U	packaged obsolete-installed-outer.test.ts
Reinstalled newer outer resets runtime (bound > active)	U	packaged launcher-runtime.test.ts supersede case
Reinstalled older outer delegates (bound < active)	P	spec recovery segment precondition
Physical running payload survives pointer changes, cleanup, and same-version repair	U	desktop tests/main/updater/payload-running.test.ts

E. Installer (reinstall) path

Node	Coverage	Owning tests
win NSIS reinstall over the same registry key + transaction contract	P	win spec installer fallback acceptance
mac dry-run installer open	P	mac spec recovery segment
mac real DMG open via the deferred helper script	U, M	desktop unit fake-spawn; human acceptance

F. Manual clear-cache (disaster recovery)

Node	Coverage	Owning tests
Action chain (sidecar action → IPC → host → web)	U, P	boundary tests; web tests; spec recovery segment
Reset depth + retained-version protection	U, P	desktop unit clear-cache group; specs
Owned-but-corrupt store rebuild (sentinel = ownership proof)	U	desktop unit store-rebuild group
Post-clear recovery (re-check re-derives + re-downloads)	P	spec recovery segment

G. Publication pipeline

Node	Coverage	Owning tests
metadata.json composition + CAS latest publish	U	tools-serve release-metadata-publish.test.ts
Launcher version floor channel policy (vars pairs, stable fallback, validation)	U	tools-release launcher-version-floor.test.ts; publish integration
Workflow env passthrough (no YAML fallback)	U	tools-pack release-workflows.test.ts floor passthrough test
verify-metadata / summary-metadata wiring	U	publish integration test
Fixture bridge (control knobs, port pinning)	U	e2e tests/updater-fixture.test.ts; tools-serve fixture tests

Known deliberate gaps

• Interactive installer UIs (mac drag, NSIS wizard) stay human-verified.
• Full historical-outer migration needs a genuinely old installed build; the daemon bridge is unit-tested and the win spec covers the legacy-executable identity variant.
• Linux ships no packaged auto-update (AppImage manual) by design.