From fa54ef691599ed2db7b482afb014a1cb2197f351 Mon Sep 17 00:00:00 2001
From: Daniel Samson <12231216+daniel-samson@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:13:34 +0100
Subject: [PATCH] docs: the volume lifecycle is enforced, not described
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 .../storage-architecture.md                   | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/file-system-development/storage-architecture.md b/docs/file-system-development/storage-architecture.md
index 22421da..323c612 100644
--- a/docs/file-system-development/storage-architecture.md
+++ b/docs/file-system-development/storage-architecture.md
@@ -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
 lesson of QNX's Power-Safe) narrows that window further and slots in as
 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.