From 9da63e81e21df9d8516e7d2206dfb7e805265b13 Mon Sep 17 00:00:00 2001
From: Daniel Samson <12231216+daniel-samson@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:01:03 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20the=20boot=20volume=20=E2=80=94=20ident?=
 =?UTF-8?q?ity=20is=20what=20makes=20yanking=20it=20survivable?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sharpest instance of the return story, folded into the architecture: the
boot volume is a recorded content identity (the volume carrying
/system/configuration and /system/logs), the system runs on without it (the
ramdisk is the OS; only log persistence pauses), the kernel ring is the
buffer during absence — bounded, so a wrapped ring is a data loss window
that gets MARKED in the file on resume, never spliced silently — and on
return at any port the same identity remounts the same prefixes and the
logger appends into the same boot-stamp tree. The logger requirement is
named: failed flushes retry on the patient cadence, never abandoned after
the first not_found. The dirty-honesty rule stands; the boot volume gets no
exemption.
---
 .../storage-architecture.md                   | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/file-system-development/storage-architecture.md b/docs/file-system-development/storage-architecture.md
index 189390a..4f8a30e 100644
--- a/docs/file-system-development/storage-architecture.md
+++ b/docs/file-system-development/storage-architecture.md
@@ -179,6 +179,38 @@ subtree reappear. A different stick in the same port is a *different volume*
 (identity is content, not port) and mounts wherever its identity says —
 possibly nowhere but `/volumes/…`.
 
+### The boot volume: identity is what makes yanking it survivable
+
+The boot volume is the sharpest instance of the return story, because the
+system's own log persistence rides it (`/system/logs`), and because nothing
+else about the running system depends on it at all — every binary and the
+boot-time configuration live in the initial ramdisk. Its lifecycle,
+end to end:
+
+- **At first mount** the volume manager records the identity of the volume
+  carrying `/system/configuration` and `/system/logs` — THE boot volume,
+  from then on a fact about content, not about a port.
+- **While it is absent**, the system runs on. The kernel log ring keeps
+  accumulating — it is the buffer that makes the absence survivable — and
+  the logger keeps draining it; only *persistence* pauses. File operations
+  under the retired mounts fail honestly (`not_found`). The ring is bounded,
+  so a long absence overwrites its oldest entries: that window is the data
+  loss, and it must be *said* — the logger marks the gap in the file when
+  persistence resumes, never splicing the stream silently.
+- **On return — any port, any hub, even a different transport** — the
+  prober reads the same identity, the mount map answers with the same
+  prefixes, the filesystem service is respawned, and `/system/logs` is the
+  same tree it was: the logger resumes appending into the SAME
+  `<boot-stamp>` directory, per-binary files continuing where they left
+  off (plus the gap marker if the ring wrapped).
+- **What never comes back** is the write-back window lost at the yank —
+  the dirty-honesty rule, unchanged; the boot volume gets no exemption.
+
+This is also the requirement that shapes the logger: it treats the log tree
+as a volume that comes and goes — failed flushes are retried on the same
+patient cadence the fat service already uses for storage that arrives late,
+never abandoned after the first `not_found`.
+
 What is lost on a surprise yank is exactly the write-back window of the
 filesystem service, no more: the engine owns its cache, so the blast radius of
 a yank is one volume's unflushed writes, marked by the on-disk dirty flag. A