From fa2558014420a7836eaef83765d614d6145bf559 Mon Sep 17 00:00:00 2001
From: Steffen Beyer <steffen@beyer.io>
Date: Mon, 13 Apr 2026 19:03:59 +0200
Subject: [PATCH] Link and refine lifecycle planning docs

---
 docs/plan.md   |  3 +++
 docs/plan_2.md | 29 ++++++++++++++++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/plan.md b/docs/plan.md
index 76b05c4..b73cdc0 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -359,6 +359,9 @@ Key requirement:
 
 Status: **partial / in progress**.
 
+See also: `docs/plan_2.md` for the follow-on lifecycle plan focused on
+node-local management, deploy hardening, and the later source/pin/upgrade path.
+
 ## Source / pin / update / lock workflow
 
 Source provenance should not only be recorded after the fact; it should become
diff --git a/docs/plan_2.md b/docs/plan_2.md
index 50e1957..7906c89 100644
--- a/docs/plan_2.md
+++ b/docs/plan_2.md
@@ -188,13 +188,40 @@ Completed:
 
 Remaining:
 
-- review and document switch / rollback ordering invariants
 - validate `status` / `reconfigure` / `rollback` on a real booted self-hosted
   node
 - decide whether generation-local `install.scm` should keep its current
   deployment-oriented schema or move closer to the initial install-generation
   shape
 
+### Reviewed switch / rollback ordering invariants
+
+The current implementation should be treated as intentionally following these
+rules:
+
+- prepare the new generation directory and metadata before changing any current
+  or rollback pointers
+- record rollback pointers from the previously current generation before moving
+  current pointers to the new generation
+- update generation links / files and gcroots before changing
+  `/run/current-system`
+- update EFI loader state after the current closure link has moved
+
+That gives Fruix a simple current contract:
+
+- generation data exists before it becomes current
+- rollback points at the previously current generation
+- `/run/current-system` moves only after generation metadata and gcroots are in
+  place
+
+Known caveat for later refinement:
+
+- EFI loader update happens after current-state links move, so a failure during
+  loader copy could leave the running/current generation advanced while boot
+  media state still reflects the previous loader payload
+
+That is acceptable for now, but it should remain an explicit reviewed tradeoff.
+
 ## Phase 1: node-local lifecycle hardening
 
 Goal: an installed self-hosted Fruix node can manage itself from its own pinned