docs: the boot volume — identity is what makes yanking it survivable

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.
This commit is contained in:
Daniel Samson
2026-08-09 16:01:03 +01:00
parent ada251150a
commit 9da63e81e2
@@ -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 — (identity is content, not port) and mounts wherever its identity says —
possibly nowhere but `/volumes/…`. 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 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 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 a yank is one volume's unflushed writes, marked by the on-disk dirty flag. A