docs: the volume lifecycle is enforced, not described

The enforcement section of the storage architecture: the three levers the
device lifecycle already proved, mapped onto volumes — a filesystem can only
be GIVEN its volume (no establishment grants, channel at spawn), the volume
manager supervises with teeth (deadline, kill-on-removal, crash-loop cap),
and the shared harness makes every engine inherit the state machine by
construction (engines never see channels). Kernel backstops: ownership-gated
fs_unmount + the lazy dead-endpoint sweep. Checkable via a lifecycle
conformance drill parameterized over filesystems — supporting a filesystem
MEANS passing it.
This commit is contained in:
Daniel Samson
2026-08-09 15:13:34 +01:00
parent fae616fa5a
commit fa54ef6915
@@ -161,3 +161,39 @@ a yank is one volume's unflushed writes, marked by the on-disk dirty flag. A
filesystem format with better crash honesty (journaling, copy-on-write — the filesystem format with better crash honesty (journaling, copy-on-write — the
lesson of QNX's Power-Safe) narrows that window further and slots in as lesson of QNX's Power-Safe) narrows that window further and slots in as
implementation N+1 through the table above, changing nothing else. implementation N+1 through the table above, changing nothing else.
## How the lifecycle is enforced
Responsibility tables are convention; convention is worthless (the bounds
audit's lesson). The volume lifecycle is enforced with the same three levers
the device lifecycle already uses, mapped one-to-one:
1. **A filesystem cannot acquire — it can only be given.** Filesystem
binaries hold NO establishment grants: no `open device-manager`, no
registry name to look up. The only block channel a filesystem process ever
has is the one handed to it at spawn by the volume manager. Serving the
wrong volume, a second volume, or a self-discovered volume is not
forbidden but *impossible* — the same way a driver cannot claim hardware
it was not delegated (device-authority.md).
2. **The volume manager supervises with teeth.** Mount-within-deadline or be
stopped (a filesystem wedged on a corrupt volume is killed and crash-loop
capped; the volume is marked bad, not retried forever). On removal the
manager KILLS the filesystem process and retires its mounts — the polite
observe-`EPEER`-and-exit path is an optimization; the kill is the
guarantee, because a process cannot be trusted to observe its own
obsolescence (the reap argument, proven on the device tree).
3. **The shared harness is how every filesystem inherits the lifecycle by
construction.** The harness — not the engine — owns the state machine:
establishment at spawn, mount registration, the dirty-flag set/clear
bracket, error-out-and-exit on channel death. The engine sits behind the
four-function vtable and never sees a channel; it cannot opt out of the
lifecycle for the same reason it cannot find a device. This is why the
harness is extracted BEFORE the second engine is written.
Beneath all three, two kernel mechanisms: ownership-gated `fs_unmount` (only
the mounting endpoint's holder may unmount), and the lazy dead-endpoint mount
sweep as the backstop nothing can disable. And above them, the check: a
**lifecycle conformance drill** — mount, serve, yank mid-write, verify honest
loss, replug, remount — parameterized over filesystem implementations, so
"danos supports filesystem X" MEANS "X passes the drill through the harness",
exactly as provider conformance means passing the reserved-verb suite.