docs: correct the storage docs' V0-V4 status — the V5 flip missed several
A V5 close-out audit (docs against the actual code) found the storage docs overclaiming in both directions: the status header was flipped to "built" but several body markers were not, and two passages describe mechanisms the code never implemented. Nine confirmed, adversarially verified against the source: Underclaims (marked Planned, actually built): - storage-architecture: driver named sub-ranges / range confinement (V2, tested by the block-range case); the pushed medium_changed event (published today from a TEST UNIT READY poll); ownership-gated fs_unmount (V0, process.zig gates it with EPERM); the filesystem-harness extraction (V1). Scoped the remaining *planned* to the genuinely-pending parts (native-signal translation, the volume manager consuming medium_changed). Overclaims (described, never built): - storage-architecture: the "FAT dirty flag on disk" guarantee — no on-disk dirty/clean-shutdown bit exists; only an in-memory device-dirty bool gating a device write-cache flush on close. Fixed in all three places. - storage-architecture: fat "acquires its own volume (first mass-storage child by enumeration order)" — the V3b flip removed self-acquisition; fat is handed its volume id and channel by the volume manager. - rationale + plan: the FAT engine's base_lba "deleted rather than moved" — it and the engine's MBR walk still exist as now-inert legacy; the authoritative walk lives in partition.zig. - rationale: NVMe namespaces "decision 4 settles as endpoint-per-volume" — decision 4 settles the opposite (per-sender confinement, one endpoint); endpoint-per-volume is named only as an unbuilt future refactor. - rationale: the five-rung identity ladder and volumes.csv map stated in flat present tense — only rung 4 (MBR signature + index) is built; added the build-status hedge and marked each rung. Docs only; no code or behavior change. Suite unaffected (127/127).
This commit is contained in:
@@ -105,8 +105,9 @@ and /system/logs), closing the two-sticks question honestly.
|
||||
Plan 9's `dossrv` to Minix to Fuchsia: block-client + engine + file-protocol
|
||||
provider in one binary, one process per volume (9front practice; per-volume
|
||||
fault isolation is what our supervision makes cheap). fat's shell becomes a
|
||||
shared *filesystem harness* library before a second engine is written; the MBR
|
||||
walk moves out of the engine into the volume manager; write caching stays
|
||||
shared *filesystem harness* library before a second engine is written; a
|
||||
partition walk is added in the volume manager (`partition.zig`) — the engine's
|
||||
own MBR walk currently remains alongside it; write caching stays
|
||||
inside the process (the anti-fsyncgate rule). Each mounts its prefixes into the
|
||||
kernel mount table itself, exactly as today.
|
||||
|
||||
@@ -132,8 +133,10 @@ what the architecture promises: one driver binary plus one `devices.csv` row.
|
||||
**NVMe** shortens the stack — no bus/class split; the driver IS the
|
||||
controller driver, one hop fewer than USB. Its structural novelty,
|
||||
**namespaces** (hardware-native multiple volumes behind one controller), is
|
||||
exactly the case the block protocol reserved on day one and decision 4 below
|
||||
settles as endpoint-per-volume. **AHCI** is a shape choice, not a problem: an
|
||||
exactly the case the block protocol reserved on day one — still reserved, not
|
||||
implemented (pressure point 1 below): decision 4 settles per-volume addressing
|
||||
as per-sender confinement on a single endpoint, and names endpoint-per-volume
|
||||
only as an unbuilt future refactor. **AHCI** is a shape choice, not a problem: an
|
||||
HBA fronts up to 32 ports plus port multipliers — structurally a bus — so
|
||||
either mirror USB (ahci-bus + a per-port disk driver: maximum restart
|
||||
granularity, the proven shape) or mirror NVMe (one driver per controller, one
|
||||
@@ -180,7 +183,10 @@ matrix-proven shape; genuinely open.
|
||||
same pattern applied to blocks. The volume manager sets each filesystem
|
||||
process's range on the driver; the driver clamps AND translates every
|
||||
transfer by the sender's range, so filesystems address volume-relative
|
||||
LBAs from 0 and the FAT engine's `base_lba` is deleted rather than moved.
|
||||
LBAs from 0. On the confined path the FAT engine's `base_lba` therefore
|
||||
resolves to 0 on every access; the field and the engine's own MBR walk
|
||||
remain in `engine.zig` as now-inert legacy code (the authoritative partition
|
||||
walk lives in the volume manager's `partition.zig`), not yet deleted.
|
||||
The enforcement point (the clamp at the provider, never in the consumer)
|
||||
is what carries the security property; endpoint-per-volume would deliver
|
||||
the same property only by inventing a multi-endpoint harness the pattern
|
||||
@@ -209,20 +215,26 @@ matrix-proven shape; genuinely open.
|
||||
broke whenever a drive changed ports or enumeration order; `UUID=` entries
|
||||
exist because device-path identity failed. danos skips that era: the mount
|
||||
map (`volumes.csv` — configuration, read by the volume manager) keys on
|
||||
**content identity, never port or discovery order**. The prober reads
|
||||
identity off the medium, strongest first:
|
||||
1. GPT partition GUID — 128-bit, unique, stable for the volume's life;
|
||||
2. filesystem UUID (ext-family and most modern formats, in the superblock);
|
||||
**content identity, never port or discovery order**. Build status: only
|
||||
rung 4 (MBR signature + partition index) is implemented today; the fuller
|
||||
rungs and the `volumes.csv` map itself land with the identity ladder, so
|
||||
today a single volume mounts at the fixed `/volumes/usb` and its recorded
|
||||
identity is not yet consulted to pick a path. The target ladder the prober
|
||||
reads off the medium, strongest first:
|
||||
1. GPT partition GUID — 128-bit, unique, stable for the volume's life *(planned)*;
|
||||
2. filesystem UUID (ext-family and most modern formats, in the superblock) *(planned)*;
|
||||
3. FAT volume serial + label — 32 bits, weak (dd-cloned sticks share it)
|
||||
but what real sticks carry;
|
||||
4. MBR disk signature + partition index;
|
||||
5. nothing — an anonymous volume: generated mount name, no persistence.
|
||||
but what real sticks carry *(planned)*;
|
||||
4. MBR disk signature + partition index — **built**; a bare FAT with no
|
||||
table takes index 0 over the whole device;
|
||||
5. nothing — an anonymous volume: generated mount name, no persistence *(planned)*.
|
||||
|
||||
Consequences, each mechanical once identity keys the map: **moving a drive
|
||||
to a different port changes nothing** — same identity, same mount point,
|
||||
whether USB port, hub depth, SATA port, or a stick that left as USB and
|
||||
returned in a SATA dock; **replug remounts at the same path** (the
|
||||
remount-after-return story is a map lookup); **the boot volume** is the
|
||||
returned in a SATA dock; **replug remounts at the same path** (a map lookup
|
||||
once the map exists; today's single volume re-probes and remounts at the
|
||||
fixed prefix, and remount-on-replug is bench-verified, not QEMU-tested); **the boot volume** is the
|
||||
recorded identity of the volume carrying `/system/configuration`, findable
|
||||
on any port; and **duplicate identity is a policy case, not a surprise** —
|
||||
two cloned sticks at once: first keeps the mapped name, second mounts
|
||||
|
||||
Reference in New Issue
Block a user