docs: a 9P design note and a design registry to argue it in

1 files changed, 986 insertions, 0 deletions

diff --git a/docs/registry.typ b/docs/registry.typ
new file mode 100644
index 00000000..597e930f
--- /dev/null
+++ b/docs/registry.typ
@@ -0,0 +1,986 @@
+// THE DESIGN REGISTRY — the one place where an idea, a refactor or an open
+// question lives between "someone said it" and "the tree does it".
+//
+// WHY A FILE AND NOT AN ISSUE TRACKER. Every claim in here cites `file:line`
+// against this tree, and a tracker cannot be grepped from an editor pane, does
+// not diff, and is not there when the network is not. `docs/design.typ` says
+// what pardes IS; this file says what is being argued about. When an argument
+// settles, its conclusion moves into `design.typ` (or into the code) and the
+// entry here becomes `landed` or `rejected` — a tombstone with the reasoning
+// still attached, because the expensive part of a decision is the part that
+// says why the other option lost.
+//
+// NO PACKAGES. `design.typ` pins cetz because diagrams are genuinely painful to
+// hand-roll; this file has none, so it depends on nothing and builds offline
+// forever:
+//
+//   typst compile docs/registry.typ docs/registry.pdf
+//
+// HOW TO ADD TO IT. Append an `#entry`. Argue inside it with `#note`. Cite with
+// `#ev`. Never delete a note — flip the entry's status and let the losing
+// argument stand. The dashboard on page one is generated from the entries, so
+// there is no index to keep in sync.
+
+#set page(paper: "a4", margin: (x: 2.2cm, y: 2cm), numbering: "1")
+#set text(font: "New Computer Modern", size: 9.6pt)
+#set par(justify: true, leading: 0.58em)
+#set heading(numbering: none)
+#show heading: set block(above: 1.4em, below: 0.7em)
+#show heading.where(level: 1): set text(size: 12pt)
+#show heading.where(level: 2): set text(size: 10.4pt)
+
+#show raw.where(block: true): it => block(
+  width: 100%,
+  fill: luma(246),
+  inset: (x: 0.5em, y: 0.45em),
+  radius: 1pt,
+  breakable: true,
+  text(size: 7.8pt, it),
+)
+#show raw.where(block: false): set text(size: 8.8pt)
+#set table(stroke: 0.4pt, inset: 0.4em)
+
+// ---------------------------------------------------------------------------
+// machinery
+// ---------------------------------------------------------------------------
+
+/// The lifecycle. `open` is a question nobody has taken; `investigating` has an
+/// agent or a human on it; `decided` has an answer but no code; `landed` and
+/// `rejected` are terminal and keep their argument; `deferred` is "correct, but
+/// not until X exists" and must say what X is; `blocked` waits on someone else.
+#let states = (
+  open: (rgb("#8a6d3b"), "OPEN"),
+  investigating: (rgb("#31708f"), "LOOKING"),
+  decided: (rgb("#2f6f4f"), "DECIDED"),
+  landed: (rgb("#3c763d"), "LANDED"),
+  rejected: (rgb("#a94442"), "REJECTED"),
+  deferred: (rgb("#6f5499"), "DEFERRED"),
+  blocked: (rgb("#777777"), "BLOCKED"),
+)
+
+#let chip(state) = {
+  let (c, label) = states.at(state)
+  box(
+    fill: c,
+    inset: (x: 4.5pt, y: 2.2pt),
+    outset: (y: 1.5pt),
+    radius: 2pt,
+    text(size: 6.4pt, fill: white, weight: "bold", tracking: 0.4pt, label),
+  )
+}
+
+/// One argument. `id` is stable forever — notes and code comments cite it, so a
+/// renumber is a lie in every file that referenced the old number.
+#let entry(id, title, state: "open", tags: (), body) = {
+  [#metadata((id: id, title: title, state: state, tags: tags)) <reg>]
+  block(above: 1.5em, below: 0.5em, breakable: true)[
+    #block(
+      width: 100%,
+      fill: luma(242),
+      inset: (x: 0.6em, y: 0.45em),
+      radius: 2pt,
+      stroke: (left: 2pt + states.at(state).at(0)),
+    )[
+      #text(weight: "bold", size: 9.6pt)[#raw(id) #h(0.5em) #title]
+      #h(1fr)
+      #chip(state)
+      #if tags.len() > 0 [
+        #linebreak()
+        #text(size: 7.4pt, fill: luma(90))[#tags.join(" · ")]
+      ]
+    ]
+    #block(inset: (x: 0.2em, top: 0.5em))[#body]
+  ]
+}
+
+/// A comment. The thread IS the design discussion; keep them in time order and
+/// never edit one in place — reply to it instead.
+#let note(who, date, body) = block(
+  width: 100%,
+  inset: (left: 0.9em, y: 0.35em),
+  stroke: (left: 1.6pt + luma(205)),
+  {
+    text(size: 7.6pt, weight: "bold", fill: luma(70))[#who]
+    text(size: 7.6pt, fill: luma(140))[ · #date]
+    linebreak()
+    set text(size: 9.2pt)
+    body
+  },
+)
+
+/// Evidence. A claim with a path is a fact; a claim without one is an opinion,
+/// and this makes the difference visible at a glance.
+#let ev(where, body) = block(
+  width: 100%,
+  inset: (left: 0.9em, y: 0.25em),
+  {
+    text(size: 8.2pt, fill: rgb("#2f6f4f"))[▸ ]
+    raw(where)
+    text(size: 9.2pt)[ — #body]
+  },
+)
+
+/// A question with no owner yet. Rendered so it can be found by eye when
+/// scanning for something to pick up.
+#let q(body) = block(
+  width: 100%,
+  inset: (x: 0.7em, y: 0.4em),
+  fill: rgb("#fdf6e3"),
+  radius: 2pt,
+  { text(size: 7.6pt, weight: "bold", fill: rgb("#8a6d3b"))[OPEN QUESTION]; linebreak(); body },
+)
+
+/// What the entry concluded. One per entry at most, and only when the state is
+/// `decided`, `landed` or `rejected`.
+#let verdict(body) = block(
+  width: 100%,
+  inset: (x: 0.7em, y: 0.4em),
+  fill: rgb("#eef5ef"),
+  radius: 2pt,
+  stroke: 0.4pt + rgb("#2f6f4f"),
+  { text(size: 7.6pt, weight: "bold", fill: rgb("#2f6f4f"))[VERDICT]; linebreak(); body },
+)
+
+// ---------------------------------------------------------------------------
+
+#align(center)[
+  #text(size: 15pt, weight: "bold")[The Design Registry]
+  #v(0.3em)
+  #text(size: 9pt, style: "italic")[open arguments, their evidence, and how they were settled]
+  #v(0.2em)
+  #text(size: 8.5pt)[#datetime.today().display("[year]-[month]-[day]")]
+]
+
+#v(0.8em)
+
+#context {
+  let es = query(<reg>).map(e => e.value)
+  let order = ("open", "investigating", "blocked", "decided", "deferred", "landed", "rejected")
+  let counts = order
+    .map(s => (s, es.filter(e => e.state == s).len()))
+    .filter(p => p.at(1) > 0)
+    .map(p => [#chip(p.at(0)) #text(size: 8.4pt)[#p.at(1)]])
+  align(center, counts.join(h(0.9em)))
+  v(0.6em)
+  table(
+    columns: (auto, 1fr, auto),
+    align: (left + horizon, left + horizon, right + horizon),
+    table.header(
+      text(size: 8pt, weight: "bold")[ID],
+      text(size: 8pt, weight: "bold")[Argument],
+      text(size: 8pt, weight: "bold")[State],
+    ),
+    ..es
+      .sorted(key: e => order.position(s => s == e.state) * 1000)
+      .map(e => (raw(e.id), text(size: 8.8pt)[#e.title], chip(e.state)))
+      .flatten()
+  )
+}
+
+#pagebreak()
+
+= 9P
+
+Born from the draft note `docs/9p.typ`. The owner's instinct: replace FUSE with
+9P, replace the private unix-socket wire with 9P too, and put a small 9P server
+on the ESP32-P4 that pardes talks to as a client. The instinct is recorded here
+entry by entry so it can be argued with in pieces rather than accepted or
+rejected whole.
+
+#entry("9P-1", "Where does 9P go? Two layers, and 9P is the outward face of one of them", state: "decided", tags: ("architecture", "umbrella"))[
+  The umbrella. The draft conflated two things that share a socket and nothing
+  else.
+
+  #ev("src/acmefs.zig:63-78")[LAYER 1, the acme control tree: request/response, nine operations, and an ABI that already says "FUSE opcodes, 9P messages and a unit test all reduce to these".]
+  #ev("src/detached/wire.zig:187-232")[LAYER 2, the detached wire: 19 tags carrying RLE cell frames and input, server-push, N frontends on one screen. None of them is a file.]
+
+  #verdict[
+    9P is a TRANSPORT FOR LAYER 1 and a CARRIER FOR LAYER 2 — never a
+    re-encoding of either.
+
+    Layer 1 gets 9P as a second transport beside FUSE, because the ABI was
+    built for it and because FUSE cannot leave the machine (`9P-13`).
+
+    Layer 2 keeps `encodeFrame` byte for byte. 9P may carry those bytes
+    (`9P-12`), but the moment a frame is re-expressed as a file's contents the
+    design has lost the thing that makes it fast, and there is a thirty-year
+    demonstration of both answers (`9P-12`, devdraw against `/dev/screen`).
+  ]
+
+  #note("review", "2026-08-27")[
+    The reason this is worth stating as its own entry: nearly every mistake in
+    the draft is one layer's property asserted about the other. "Offsets are
+    meaningless" is true of Layer 2 and false of Layer 1. "The protocol is
+    private and undocumented" is true of Layer 2 and false of Layer 1, which is
+    acme(4). "Adding a feature means adding a message" is true of Layer 2 —
+    measured at 7 lines per fact (`src/detached/wire.zig`, `set_clipboard`
+    occurring 8 times) — and false of Layer 1, where a feature is a file.
+  ]
+]
+
+#entry("9P-2", "Make the transport seam explicit before writing any 9P", state: "decided", tags: ("refactor", "cheap"))[
+  `fs_service` already touches its transport through exactly three methods.
+  Turning `*fuse.Fs` into a ctx+vtable at three call sites is a no-behaviour
+  change that makes a second transport possible without deciding anything else.
+
+  #ev("src/fs_service.zig:158-200")[`drain`/`step` call only `retry()`, `next()` and `reply()`.]
+  #ev("src/tty/tty.zig:1216")[call site 1.]
+  #ev("src/gui/gui.zig:3738")[call site 2 — and `:3841` for the headless grid harness.]
+
+  #verdict[Do it first, independently of every other entry. ≈40 lines changed, 0 added, `fuse.Fs` is the first implementor. If 9P is never built, this costs nothing and documents the seam.]
+]
+
+#entry("9P-3", "Direct I/O is `qid.version = 0`, not `cache=none`", state: "decided", tags: ("protocol", "correction"))[
+  Under FUSE the server asserts `FOPEN_DIRECT_IO` per open and the client
+  cannot argue. The draft assumed 9P gives this up and compensated with advice
+  ("mount with `cache=none`"). It does not have to: Linux's client disables
+  both read and write caching for any file whose qid version is zero.
+
+  #ev("linux/fs/9p/fid.h:52-53")[`(fid->qid.version == 0) && !(s_flags & V9FS_IGNORE_QV)` sets `P9L_DIRECT` — "no read or write cache".]
+  #ev("linux/fs/9p/v9fs.h:82")[`CACHE_NONE = 0` is the default anyway.]
+  #ev("linux/fs/9p/v9fs.c:93")[`ignoreqv` is the only opt-out, and it is explicit.]
+
+  #verdict[A synthetic tree reports `qid.vers = 0` on every file. Server-enforced, near-parity with `FOPEN_DIRECT_IO`, and the mount advice in the draft becomes unnecessary. Plan 9 needs nothing: its cache is opt-in via `mount -c`.]
+]
+
+#entry("9P-4", "The error ABI: 9P2000 Rerror is a string", state: "open", tags: ("protocol", "ABI"))[
+  The core answers with numbers. 9P2000 answers with prose, and the Linux
+  client turns prose back into a number by exact string match. A miss is not
+  `EIO`; it is 526, which userspace prints as "Unknown error 526".
+
+  #ev("src/acmefs.zig:152-165")[`E.PERM..E.NOSYS`, nine numeric values.]
+  #ev("linux/net/9p/error.c:224-243")[`p9_errstr2errno` hash lookup; on a miss `errno = ESERVERFAULT`.]
+  #ev("principia-softwarica/editors/acme/xfid.c:19-24")[acme's own strings — `Ebadctl`, `Ebadaddr`, `Ebadevent` — are all misses in that table.]
+
+  Three ways out, and they are not equally good.
+
+  / A: #[Emit Linux `strerror` text verbatim so all nine round-trip. Cheap (≈20 lines), and makes English kernel strings this project's error ABI.]
+  / B: #[Serve 9P2000.u, whose `Rerror` carries a numeric errno alongside the string. Costs a second dialect in the codec; buys exact errnos and keeps a human-readable string for Plan 9 clients.]
+  / C: #[Emit acme's strings and accept 526 on Linux. Faithful to acme, hostile to `mount -t 9p`.]
+
+  #q[Which? Note that B also answers `9P-5`'s `statfs` gap for free, and that the draft deferred `.u`/`.L` without noticing either.]
+
+  #note("prior-art", "2026-08-27")[
+    `ad` — a Rust acme-like editor that already ships this — chose option C
+    without noticing. It emits nineteen lowercase prose strings: `"unknown
+    fid"`, `"permission denied"`, `"file not open"`, `"exclusive file already
+    open"`, `"invalid offset for read on directory"`
+    (`~/05-genizah/ad/crates/ninep/src/sansio/server.rs:25-43`). *None* of
+    them is in Linux's table, so under `mount -t 9p` every single error `ad`
+    can produce arrives as 526. It also serves `SUPPORTED_VERSION = "9P2000"`
+    and nothing else (`:46`), so there is no `.u` escape hatch in place.
+    Real implementations fall into this; it is not a theoretical trap.
+  ]
+]
+
+#entry("9P-5", "Directory reads need per-fid state the core does not have", state: "decided", tags: ("protocol", "cost"))[
+  This is the real offset discontinuity, and the draft missed it while
+  inventing a false one about `body`.
+
+  9P requires a directory read at offset 0 or at exactly the byte offset where
+  the previous read ended, and the reply must contain whole `Dir` entries.
+  `acmefs` treats the offset as an *entry index* and re-stages the whole
+  listing each call, which is right for FUSE and wrong here.
+
+  #ev("principia-softwarica/lib_networking/lib9p/srv.c:473")[a dir read whose offset is neither 0 nor `fid->diroffset` is answered `Ebadoffset`.]
+  #ev("u9fs/u9fs.c:60-64")[the reference server keeps `diroffset`, a cached `dirent` and `direof` per fid.]
+  #ev("src/acmefs.zig:972")[`var skip = req.off;` — an entry index.]
+
+  #verdict[Transport-side, not core-side: the 9P transport keeps a per-fid byte cursor plus the one entry that did not fit, and calls the existing `readdir` with the entry index it has counted. `acmefs.zig` is untouched. Budget ≈40 lines.]
+
+  #note("prior-art", "2026-08-27")[
+    `ad` has no cookie at all: `read_dir` returns the entire `Vec<Stat>` on
+    every call and the server re-serialises all of it and byte-skips the offset
+    (`ninep/src/sync/server.rs:203`, `sansio/server.rs:377-401`). Its
+    `FidMeta` is `{qid, mode}` — no dir state (`:700-703`). So it is O(N) per
+    read, O(N²) per directory, and `E_INVALID_OFFSET` fires only when the
+    offset lands mid-entry (`:388-390`), which means an arbitrary offset on an
+    entry boundary is silently accepted and a changing directory tears.
+    The 40-line budget above buys correctness `ad` does not have.
+  ]
+]
+
+#entry("9P-6", "Is `addr` per-fid or per-window?", state: "open", tags: ("semantics", "divergence"))[
+  The draft claimed per-fid and attributed it to acme. acme does the opposite,
+  and so does pardes today.
+
+  #ev("principia-softwarica/editors/acme/dat.h:239")[`Range addr;` is a field of `struct Window`; every use in `xfid.c` is `w->addr`.]
+  #ev("src/acmefs.zig:1027-1031")[pardes copied that, deliberately, and records why: there is no fid table because FUSE puts the nodeid on every request.]
+
+  Per-fid genuinely is better — two scripts can address one window without
+  colliding — but it is a divergence from acme, not a restatement of it, and it
+  is the one place in the whole draft that asks the *core* to grow state. Under
+  FUSE there is no fid to hang it on at all.
+
+  #q[Take the divergence and pay for it (per-fid `addr` lives in the 9P transport, and the FUSE transport keeps one per mount), or keep acme's race and document it?]
+
+  #note("prior-art", "2026-08-27")[
+    Third independent source against the draft: `ad`'s address is per-BUFFER,
+    keyed by buffer id (`Req::SetBufferAddr{id, addr}`,
+    `ad/src/fsys/message.rs:77-80`). acme per-window, pardes per-pane, `ad`
+    per-buffer. Nobody has ever shipped it per-fid. That is not proof it is
+    wrong — it is proof it is a proposal, and it should be argued as one.
+  ]
+]
+
+#entry("9P-7", "One controller per window, or many?", state: "open", tags: ("semantics", "divergence"))[
+  The draft says `event` is exclusive-use. acme does not do this, and pardes
+  currently allows any number of readers.
+
+  #ev("principia-softwarica/editors/acme/xfid.c:603-609")[acme's exclusivity is an advisory `lock` ctl verb setting `w->ctlfid`, cleared on clunk.]
+  #ev("principia-softwarica/editors/acme/fsys.c:537-563")[`fsysopen` checks permission bits only; a second `event` reader is not refused.]
+  #ev("src/acmefs.zig")[`pf.readers +|= 1` on open — a count, and the count is what suppresses button actions.]
+
+  `DMEXCL` would make a second open fail with `EAGAIN` under Linux. That is a
+  tightening with a real cost: two cooperating scripts on one window stop
+  working, and nothing in `examples/acmefs/` was written expecting it.
+
+  #q[Leave it a count (status quo, acme-compatible), or make it exclusive and lose multi-reader?]
+
+  #note("prior-art", "2026-08-27")[
+    `ad` DOES do what the draft describes: `event` is `FileType::EXCLUSIVE`,
+    i.e. QTEXCL (`ninep/src/sansio/protocol.rs:503`, added in commit
+    `678fbf5`). Note how it is scoped, though — enforcement is per *ClientId*,
+    not per fid (`sansio/server.rs:762-764`), so one client may hold two fids
+    on `event` and two clients may not share one window. That is a third
+    position between "a count" and "one fid", and it is probably the right one:
+    it stops two unrelated scripts fighting without breaking a script that
+    opens the file twice.
+  ]
+]
+
+#entry("9P-8", "`pty/` files — the best idea in the draft, and unrelated to 9P", state: "open", tags: ("feature", "transport-independent"))[
+  A script today can write a terminal pane's `body` (it becomes a pty write)
+  and read its rendered scrollback. It cannot spawn a terminal, resize one, or
+  signal one. The draft's `pty/{data,ctl,status}` fixes that, and none of it
+  needs 9P — it is `ctl` verbs and two new `PaneFile` variants.
+
+  #ev("src/host.zig:80-82")[`push_spawn` and `push_pty_resize` already exist as effects, so `exec` and `winsize` are two existing effects with a name.]
+  #ev("src/acmefs.zig")[the `Verb` table has no pty verb; `PaneFile` has no pty entry.]
+
+  `sig INT` is the only genuinely new capability — there is no `kill` anywhere
+  in `host_io.zig`.
+
+  #verdict[Not blocked on anything. Build it in the FUSE tree now; a 9P transport inherits it for free. Sequencing it *after* 9P would be putting the transport before the feature.]
+
+  #note("prior-art", "2026-08-27")[
+    Worth knowing before building it: there is *no prior art anywhere*. acme
+    has no pty files; `ad` has none either — its tree is
+    `{ctl, minibuffer, scratch, log, buffers/…}` and contains no terminal
+    surface at all (`ad/src/fsys/mod.rs:17-32`). So `pty/` is a genuinely new
+    interface, which cuts both ways: nobody has made these mistakes for us, and
+    nobody's scripts already expect a particular spelling. Being first is a
+    reason to keep it small — `data`, `ctl`, `status`, and no more.
+  ]
+]
+
+#entry("9P-9", "Naming sessions: `aname` or a top-level directory", state: "open", tags: ("protocol", "naming"))[
+  Verified: `aname` works, and the draft's mount line is valid verbatim.
+
+  #ev("linux/fs/9p/v9fs.c:72-90")[`aname` parses to `Opt_remotename`; `version=9p2000` selects `p9_proto_legacy`.]
+  #ev("linux/fs/9p/vfs_super.c:340")[`port` defaults to 564, so the draft's command line needs no `port=`.]
+  #ev("u9fs/u9fs.c:409-420")[u9fs uses `aname` to pick a tree, so there is precedent for exactly this use.]
+
+  Against it: pardes has no multi-session concept in the core at all today —
+  `--detach=work` names a *socket*, not a tree. A top-level directory needs no
+  protocol feature and works with clients that ignore `aname`.
+
+  #q[Is this question even live before `9P-12` settles? A per-session socket already names a session; `aname` matters only if one listener serves many.]
+
+  #note("prior-art", "2026-08-27")[
+    `ad` does not use `aname` either: `Server::new` installs a single anonymous
+    root `""` (`ninep/src/sansio/server.rs:91-95`), and multi-session is the
+    SOCKET name, `ad-<pid>`, with discovery through a `list_open_sessions`
+    helper (`ad/src/fsys/mod.rs:158-159`). That is exactly pardes's
+    `--detach=work` shape. Two implementations independently reaching for a
+    named socket over `aname` is evidence about which one people actually
+    build.
+  ]
+]
+
+#entry("9P-10", "Aggregation: the prefix router", state: "deferred", tags: ("architecture", "premature"))[
+  The draft's longest technical section, and its own §11 concludes the
+  aggregate is not worth building before a second machine exists. That verdict
+  is correct and also covers the client half.
+
+  What the section understates: a proxied `Twalk` cannot be answered until the
+  remote `Rwalk` arrives, so "the fid table maps our fid to a pair" is not the
+  entire proxy — it needs per-tag continuations, remote↔local tag remapping,
+  `Tflush` forwarding and fid invalidation on connection death.
+
+  #ev("src/detached/wire.zig:64-70")[a round trip inside `update` is the one thing the transport must never do.]
+  #ev("src/detached/server.zig:238-241")[the daemon is one `poll(2)` over 50 slots, and `:565-569` records that it has no worker pool.]
+
+  #verdict[Deferred until a second machine exists AND `9P-12` has settled, because the proxy's shape depends entirely on which layer 9P occupies. Reopen with a named use case, not with an architecture.]
+]
+
+#entry("9P-11", "A 9P server on the ESP32-P4 — real, cheap, and a second firmware image", state: "decided", tags: ("board", "motivating-case"))[
+  The owner's motivating case, and the entry that changed the most under
+  measurement. Both the draft and the first review were wrong about it, in
+  opposite directions.
+
+  The draft was wrong about what the board IS: it describes a machine running
+  "a 9P server and nothing else", and today the P4 runs the whole editor
+  (`src/esp32p4.zig:264-300`, 2 of 21 vtable methods at `:930-934`).
+
+  The review was wrong about what the board CAN AFFORD, because it quoted a
+  stale number.
+
+  #ev("src/esp32p4.zig:470-473")[the "9,128 bytes free at 80×24" comment predates `direct_emit` (`:870`), which sized vaxis's two shadow grids to one cell.]
+  #ev("05-zig-p4/experiments/report.typ:848-849,877-880")[measured after that change: "the heap now reports 336 KB free at every geometry tried, including ones that used to fail outright… the heap has 336 KB spare while `.bss` runs out". The binding resource is the 240 KiB low L2MEM, not the 384 KiB heap.]
+
+  A 9P server's RAM, costed from real components: two msize buffers at 4,096
+  (u9fs uses three — `rxbuf`, `txbuf`, `databuf`, `u9fs.c:1814-1816` — a
+  minimal server needs two) = 8,192 B; a FIXED-ARRAY fid table of 32 entries ×
+  16 B (`fid`, `qid.path`, `mode`, `diroffset`) = 512 B; codec scratch with
+  `P9_ERRMAX` = 128 B. *Total 8,832 B, or 2.5% of free heap.*
+
+  #ev("src/esp32p4/input_rescue.zig:52")[and a 4,096-byte reassembly buffer already exists on this exact UART, measured: "4,096 bytes in a single write arrive intact, and past that the loss is counted rather than silent".]
+  #ev("linux/net/9p/client.c:840-843,908-910")[the 4,096 floor is imposed by the LINUX KERNEL and by nothing else. Plan 9's devmnt, plan9port's `9p` and pardes's own client accept a 512-byte msize, which halves the buffers to 1 KiB.]
+
+  Flash: the editor image is 809,536 B of a 1,536,000 B partition
+  (`report.typ:375-376`), leaving 726,464 B. A 9P-only image is ≈23,870 B of
+  platform plus ≈15 KiB of server ≈ *39 KiB, 2.5% of the partition*.
+
+  #ev("build.zig:1182-1235")[a second board image is ALREADY expressible: `esp32p4-test` builds its own executable, `ImageStep`, `FlashStep` and run step in 54 lines, and deliberately links no pardes object. That is the shape.]
+  #ev("src/acmefs.zig")[and the semantics layer already compiles for riscv32: `llvm-nm` finds 21,548 B across 17 `acmefs.*` symbols in `zig-out/pardes-esp32p4.o`.]
+
+  #verdict[
+    Buildable, and much cheaper than anyone assumed. But it is a SECOND
+    FIRMWARE IMAGE, not a second role for this one: the editor owns UART0
+    bidirectionally (`esp32p4.zig:611`, `uart.zig:43-44,122-130`) and JP1
+    exposes no second P4 UART (`board_memory.zig:382-383`). The board is either
+    an editor or a filesystem at any one time. Say that plainly rather than
+    implying both.
+  ]
+
+  #note("review", "2026-08-27")[
+    The reframing the draft misses: the board already exposes `Peek`, `Poke`,
+    `Hexdump` and `Gpio` as acme words (`src/board_memory.zig:306-349,410-472`,
+    registered `src/builtins.zig:1009,1025,1038`). All four cap at 4,096 bytes
+    per command and the cap's stated reason is the 115200 console. So the whole
+    2³² address space is already reachable — by *typing a word into a tag*,
+    with the answer landing in an output pane. Nothing is machine-readable and
+    nothing is remote. A 9P tree is that same capability with names instead of
+    verbs, and `mem/`, `gpio/pinout` and `prof` are backed by functions that
+    exist today (`board_memory.readWord:136`, `:368-390`,
+    `pardes_esp32p4_frame_prof` at `esp32p4.zig:985`, already exported).
+    Four more files need one new C-ABI extern each; four have no
+    implementation at all. That inventory belongs in the note, not a wishlist.
+  ]
+
+  #q[Should the parked second RISC-V core own the 9P server? `report.typ:552-563` says it needs four register writes plus a trampoline, shares one L1 D-cache so a lock-free ring needs only fences, and that giving core 1 the UART "eliminates the silent input loss". That is the one arrangement where the board serves 9P *and* keeps the editor. Uncosted.]
+]
+
+#entry("BOARD-1", "Raise UART0 to 921600 before quoting any board latency", state: "decided", tags: ("board", "cheap", "prerequisite"))[
+  Every board 9P latency figure is eight times worse than it needs to be, for
+  no reason but that the bootloader left the divider alone.
+
+  #ev("src/esp32p4/uart.zig:35-38")[the firmware never programs the divider; 115200 is inherited.]
+  #ev("05-zig-p4/src/hal/uart.zig:321-333")[`setBaudrate` and `divider` already exist and `reset()`'s refusal of instance 0 does not apply to them.]
+  #ev("05-zig-p4/experiments/report.typ:540-544")[921600 is one `UART_CLKDIV_SYNC` write on the existing 40 MHz XTAL — int 43, frag 6, +0.064% error. 2 Mbaud is representable but this CH340 is unreliable there, corroborated by the flasher at `build.zig:1136-1138`.]
+
+  #verdict[
+    One register write, 86.8 µs → 10.85 µs per byte. A warm
+    `cat /mnt/board/gpio/2/value` goes from 10.8 ms to 1.35 ms; a 4 KiB `Tread`
+    from 358 ms to 45 ms. Do it first, and re-measure everything after.
+    The hazard the same files record: writing the console UART's divider is
+    adjacent to what bricks the board, and the host must be reopened in step.
+  ]
+]
+#entry("9P-12", "Should 9P replace the private wire protocol? Half of it, and not the half you would guess", state: "decided", tags: ("architecture", "the-real-question"))[
+  Six layerings were costed. The finding that settles it is that layering is
+  not a cost decision at all.
+
+  #ev("src/detached/wire.zig")[1705 lines = 1092 code + 613 tests, of which only 303 are FRAME and 789 are TRANSPORT: bounds, tags, message structs, framing, codecs.]
+  #ev("src/detached/wire.zig:1401,1412")[a 56×14 full frame is 6,298 B; a one-keystroke diff is 56 B. Ratio over 100.]
+  #ev("src/detached/server.zig:1102-1110")[skip-slow is three lines: `if (c.out.items.len != 0) continue;` — skip the frame and leave the mirror alone, so the next frame diffs against what the client really has.]
+
+  A base-9P2000 codec (≈450), a dispatcher onto `acmefs.Op` (≈400) and a fid
+  table (≈120) come to ≈970 lines that are IDENTICAL in all six layerings.
+  Layering moves ±150. So the question is reach and semantics, not lines.
+
+  *Does 9P subsume the wire's job?* The transport half, yes, with shipped
+  precedent: clipboard becomes `snarf` (`rio/fsys.c:61`), input becomes
+  `mouse`/`cons` — and rio's `mouse` is exclusive-open with a blocking read and
+  a flush (`rio/xfid.c:167-173,638-660`), which is the `event` idiom exactly.
+  The frame half, no: 9P has no server-initiated message.
+
+  *Is "the frame is a file" a category error?* Only if you mean push. Two
+  shipped counter-forms exist and they disagree with each other, which is the
+  most useful thing in this entry:
+
+  #ev("plan9/rio/fsys.c:53, lens.c:281-282")[`/dev/screen` is an offset-addressed raster you POLL — `lens` seeks to a scanline and repaints on mouse events because it never learns the screen changed. Real, and precisely why nobody runs a remote rio through it.]
+  #ev("drawterm-9front/kern/devdraw.c:1574, include/draw.h:55")[`/dev/draw/N/data` is a PRIVATE BINARY COMMAND STREAM batched into 8,000-byte buffers and flushed as one `Twrite`. Real, and how remote display has actually shipped for thirty years.]
+  #ev("drawterm-9front/cpu.c:149,191,251,359")[and it inverts direction: the DISPLAY exports its devices and the APPLICATION mounts them. The frame travels as a client's `Twrite`, never as a server's push.]
+
+  pardes's codec is already devdraw's shape. `wire.zig`'s 5-byte length prefix
+  (`:145`, `framed()` `:564`) makes an `encodeFrame` message a legal 9P payload
+  with zero new framing.
+
+  #verdict[
+    *Superseded in part by `9P-19`.* The reasoning below stands; the conclusion
+    moved. O3's tunnel was chosen because it was the only option that reached
+    the board without sockets. `9P-19` shows the tunnel is unnecessary: the
+    link simply carries 9P, with the FRONTEND as the server and the core as the
+    client, and the frame travels as the client's `Twrite` to `screen`. That is
+    O1 done the way it has actually shipped for thirty years, and it dissolves
+    the objection recorded here.
+
+    What survives unchanged: *O4* (wire inside 9P) costs +34 B per frame, +61%
+    on a 56-byte diff. *O5* (a standalone listener) remains correct and is
+    independently worth building — it is the scripting face and it composes
+    with anything.
+
+    What was wrongly rejected: *O6*. "The frontend serves, the core is a
+    client" was rejected here for making the core write and match tags inside
+    `update` and for foreclosing the freestanding targets. Both are wrong. The
+    core need not wait for `Rwrite` — 9P permits many outstanding tags
+    (`linux/net/9p/client.c:194-199`, `plan9/devmnt.c:783-800`) with no
+    in-order reply requirement — and the freestanding targets have a byte
+    stream even though they have no sockets, which is all 9P asks for.
+    O6 is the destination. See `9P-19`.
+  ]
+
+  #note("review", "2026-08-27")[
+    One honest caveat against O3: `exportfs` carries 9P and nothing else — its
+    framing is 9P's own 4-byte size prefix (`exportfs.c:434,476`) — so
+    multiplexing a second protocol beside 9P on one link has *no* Plan 9
+    precedent. It is not hard, but we would be first, and "the transport
+    becomes someone else's problem" stops being true for that link.
+  ]
+]
+
+#entry("9P-13", "9P cannot replace FUSE on Linux; it can only join it", state: "decided", tags: ("portability", "privilege", "decisive"))[
+  The strongest argument for 9P was that it needs no kernel and no privileged
+  mount helper: 281 non-test lines of `fuse.zig` exist only to obtain a mount
+  an unprivileged user is not allowed to make.
+
+  #ev("src/fuse.zig:497-703")[207 lines: `_FUSE_COMMFD`, socketpair, `CMSG_*`/`SCM_RIGHTS`, fork/execve/waitpid of the setuid `fusermount3`, environ rebuild.]
+  #ev("src/fuse.zig:752-773")[22 more for the helper's unmount, `:933-978` 46 for the mount call, `:1718-1723` 6 for `clearCloexec`. 281 total, measured.]
+  #ev("src/fuse.zig:64")[and all of it is Linux-only, so macOS (14/21 vtable) and web (6/21) have no control filesystem at all.]
+
+  That argument is dead. The kernel grades mount privilege by a per-filesystem
+  flag, and the two filesystems are on opposite sides of it.
+
+  #ev("linux/fs/super.c:694-700")[`mount_capable`: without `FS_USERNS_MOUNT` the check is `capable(CAP_SYS_ADMIN)` — and `capable()` is `ns_capable(&init_user_ns, …)`, i.e. root in the INITIAL namespace, not the caller's.]
+  #ev("linux/fs/9p/vfs_super.c:362")[`.fs_flags = FS_RENAME_DOES_D_MOVE` — v9fs does not set `FS_USERNS_MOUNT`.]
+  #ev("linux/fs/fuse/inode.c:2004")[`.fs_flags = FS_HAS_SUBTYPE | FS_USERNS_MOUNT | FS_ALLOW_IDMAP` — FUSE does.]
+
+  So `mount -t 9p` costs real root, unconditionally: a fresh
+  `unshare(CLONE_NEWUSER|CLONE_NEWNS)` does not help, because `mount_capable`
+  falls back to the init namespace for exactly the filesystems that lack the
+  flag. `trans=fd` does not help either — it lets an unprivileged process own
+  the connected socket, but `mount(2)` is checked before the transport is ever
+  consulted (`linux/fs/namespace.c:3838`). And `9pfuse`, the usual escape,
+  is FUSE: it needs `fusermount` in `PATH` and reimports the whole setuid dance
+  in someone else's process.
+
+  #verdict[
+    The 281 lines are not overhead. They buy an *unprivileged pathname*, which
+    is a capability 9P has no way to provide on Linux. `fuse.zig` stays.
+
+    This does not weaken 9P; it relocates it. The two are complementary faces
+    of one `acmefs.handle`: FUSE is the PATHNAME face — local, unprivileged,
+    Linux, for `grep` and `make`. 9P is the NETWORK AND IPC face — remote,
+    unprivileged, every platform, for pardes's own client, for the board, for
+    the daemon, and for anyone with root who wants `mount -t 9p`.
+
+    Everything downstream follows from this split, and `9P-2` is what makes it
+    cost nothing.
+  ]
+
+  #note("review", "2026-08-27")[
+    Worth being precise about what survived. The draft's §6 has two halves and
+    only one of them died. "The client half needs no mount… no kernel
+    involvement, no privilege" is TRUE and remains the best paragraph in the
+    document. "The mount is for other people's programs… and it is sufficient"
+    is where the root requirement lands, and it is not sufficient — on Linux
+    that mount is strictly more privileged than the one we already have.
+  ]
+]
+
+#pagebreak()
+
+= Corrections
+
+Small, certain, and independent of every argument above.
+
+#entry("FIX-1", "`acmefs.zig` is wrong about 9P truncation", state: "decided", tags: ("comment", "one-line"))[
+  The comment justifying `setattr` says 9P has no truncate-on-open and that
+  nothing in acme answers a `Twstat` carrying a length. Both halves are wrong.
+
+  #ev("src/acmefs.zig:1097-1100")[the claim.]
+  #ev("u9fs/plan9.h:150")[`#define OTRUNC 16` — base 9P2000, used at `u9fs.c:1578` and `:1682`.]
+  #ev("u9fs/u9fs.c:1047")[`Twstat` with a length calls `truncate(2)`; that is how 9P truncates.]
+
+  #verdict[Rewrite the comment. The real reason `setattr` exists is that Linux strips `O_TRUNC` from the OPEN when `FUSE_ATOMIC_O_TRUNC` is not negotiated, which is a FUSE fact and stands on its own without the false claim about 9P. Under a 9P transport, `> body` arrives as `Topen` with `OTRUNC` or as `Twstat`, and maps onto the same `Req.truncate`.]
+]
+
+#entry("DOC-1", "`design.typ` says \"No 9P\"", state: "open", tags: ("docs", "consistency"))[
+  The project has already recorded a decision against this, under *What is
+  deliberately absent*, and the draft neither cites nor rebuts it.
+
+  #ev("docs/design.typ:1969-1971")[«No 9P. The library boundary is exactly where acme put the file server, and the FUSE mount is already that server with a Linux transport instead of a 9P one; a sixth shell could serve `Surface` and `Event` over 9P without touching the core.»]
+
+  Read closely, that paragraph is not hostile — it says *not built*, and its
+  second clause proposes something stronger than the draft does: serving
+  `Surface` and `Event`, i.e. `9P-12`'s option 1, which the project apparently
+  considered plausible enough to write down.
+
+  #q[When `9P-1` settles, this paragraph is rewritten rather than deleted — it should say which layer 9P occupies and why the other one was left alone.]
+]
+
+#entry("9P-14", "Do the daemon's filesystem first, with 16 lines and no 9P", state: "decided", tags: ("sequencing", "cheap", "do-first"))[
+  The strongest *stated* motive for putting 9P in the daemon is that a
+  detached session has no control filesystem. That is true, and it is not a
+  protocol problem.
+
+  #ev("src/detached/server.zig:563-570")[«no `push_fs_reply`, because this process mounted no /dev/fuse». The daemon simply never calls `fs_service.start`.]
+
+  The fix, counted: a `Source.fuse` variant (1 line), an `fs` field (1),
+  `fs_service.start` (1), `fsReply` copied verbatim from `tty.zig:1455-1458`
+  (4), a vtable entry (1), a pollfd and dispatch arm (6), `drain` (2).
+  *≈16 lines.* And it is *better* there than on the desktop hosts: the
+  daemon's own `poll(2)` covers `/dev/fuse` directly, so it needs no wake
+  thread at all (`src/fs_service.zig:127-131`).
+
+  #verdict[
+    Build this before deciding anything else. It costs sixteen lines, it
+    delivers the feature people actually want, and it removes a motive from the
+    9P argument so that argument is decided on its merits. If it turns out to
+    be all anyone needed, that is a good outcome, not a wasted one.
+  ]
+]
+
+#entry("9P-15", "The honest cost of a 9P stack is ≈1,600-1,900 lines, not ≈770", state: "decided", tags: ("cost", "estimate"))[
+  Two independent implementations were measured rather than guessed, and they
+  agree closely.
+
+  #ev("~/05-genizah/ad/crates/ninep")[12,296 lines total; the irreducible 9P2000 SERVER core is 2,321 non-blank non-comment: codec 704, `Stat`/`Perm`/`Mode`/`WStat` 437, session+fid+flush 615, loop+handlers 474. Fid table alone is 57 lines; the server loop 141; the flush path ≈58; directory reads 50; tests 3,669, i.e. 31%.]
+  #ev("~/05-genizah/u9fs/u9fs.c")[1,838 lines — NOT the 6,149 the first review quoted, which counted a whole plan9-libc substitute. Its codec, `convM2S` + `convS2M`, is 805.]
+
+  Codec ≈700-800 and server logic ≈1,500-1,900, from both. The earlier
+  ≈770-line figure was the size of one component.
+
+  #verdict[
+    Budget ≈1,600-1,900 core lines plus ≈500 of tests, and say so out loud,
+    because it *breaks the house rule* (`docs/design.typ:1957-1960`: a change
+    leaves the file it touches no longer than it found it) unless something is
+    retired in exchange. `9P-13` says `fuse.zig` cannot be the thing retired.
+    So this is net growth, and it has to be justified by reach — the board, the
+    network, macOS, web — not by simplification.
+  ]
+
+  #note("review", "2026-08-27")[
+    Two mitigations that are real. First, ≈970 of those lines are identical in
+    every layering (`9P-12`), so none of it is at risk from the layering
+    decision. Second, 296 of ninep's 704 codec lines are macro-generated
+    (`protocol.rs:809-1154`); Zig `comptime` over an exhaustive message enum
+    should compress that at least as well, and the message set is the one part
+    of 9P that never changes. Against that: `ad` needed `UnsafeCell` plus
+    `unsafe impl Send/Sync` to get zero-allocation parsing
+    (`protocol.rs:67-76`), which Zig gives for free — so the *hard* part of
+    their codec is not a cost we inherit.
+  ]
+]
+
+#entry("9P-16", "Tflush is a park-table lookup, and this is where we beat the prior art", state: "decided", tags: ("protocol", "advantage"))[
+  The draft says `Tflush` is the most common omission in hand-written 9P
+  servers. It understates the problem: the common failure is having it and
+  still hanging.
+
+  #ev("~/05-genizah/ad/crates/ninep/src/sansio/server.rs:767-819")[`ad` gets the ORDERING right in 39 lines — an Rflush for an in-flight tag is chained and sent only after the original replies, matching `lib9p/srv.c:241-266`.]
+  #ev("~/05-genizah/ad/crates/ninep/src/sync/server.rs:163-164")[and then `Serve9p::flush` defaults to a no-op, which `ad` never overrides. A client flushing a blocked `event` read gets no Rflush until an unrelated editor event happens to arrive. Interrupts and unmounts hang exactly as the draft warns, *despite* Tflush being "implemented".]
+
+  #verdict[
+    pardes is structurally better placed than either reference. The 32-slot
+    park table (`src/fuse.zig:789`) is already keyed per outstanding request, so
+    `Tflush` is a lookup, a reply to the original, and a reply to the flush —
+    the same path `FUSE_INTERRUPT` already takes, which is tested
+    (`src/fuse.zig`: "interrupt answers the original with EINTR and drops it").
+    Implement it against the table, not against a filesystem callback, and the
+    class of bug `ad` shipped is unrepresentable.
+  ]
+]
+
+#entry("9P-17", "Clamp Rread to the client's count, or Linux hard-fails the read", state: "decided", tags: ("protocol", "correctness", "trap"))[
+  A trap with no analogue in FUSE, which is why nobody looks for it.
+
+  #ev("linux/net/9p/client.c:1475-1479")[`if (rsize < received) { pr_err("bogus RREAD count"); *err = -EIO; }` — an Rread longer than the `count` asked for is a HARD ERROR, not a truncation.]
+  #ev("~/05-genizah/ad/crates/ninep/src/fsys/event.rs:116-122")[`ad` clamps replies to `msize` (`protocol.rs:1011-1018`) but never to `count`, and its `event` file concatenates every drained event and returns the lot. Under a kernel mount that is `-EIO`.]
+
+  #verdict[
+    Every reply path clamps to `min(count, msize - 11)`. This interacts with a
+    decision already made the other way: `acmefs` refuses a read smaller than
+    one event record with `EINVAL`, on the grounds that half a record silently
+    desynchronises a client (`docs/acme-fs.md`). That rule stays and is now
+    load-bearing for a second reason — it is what makes "clamp to count"
+    safe on `event`, because a record is either whole or refused.
+  ]
+]
+
+#entry("9P-18", "The spec-bug checklist, taken from someone else's git history", state: "open", tags: ("testing", "gift"))[
+  `ad` shipped and then fixed each of these. They are the test list for
+  `src/ninep.zig`, in roughly the order they will bite.
+
+  #ev("~/05-genizah/ad/crates/ninep/src/sansio/server.rs:335-338")[the scar they left in the source: «Spec: first element failure must be Rerror, not Rwalk with zero qids».]
+
+  Partial walks (`09334ce`); `Tcreate` of `".."` (`bcb05d9`); write-then-remove
+  (`1c8ae96`); create permission masking (`3ccc461`); open with truncate
+  (`f0c71be`); remove-on-close (`6471cd3`); the root qid's name being `"/"`
+  (`64f2f4b`); the default `aname` (`b3a2c8b`, `ce7ebc6`); exclusive files
+  (`135190c`); clearing the fid cache on clunk (`113b053`); fid open state
+  (`22041ab`); flush tracking (`7170e6a`, `5a6b5bf`).
+
+  #q[Most of these are `Tcreate`/`Tremove` bugs, and a synthetic tree could simply answer `Rerror` to both — the draft's §9 already argues our trees are invented and have no cases we did not choose. Does `new/` need real `Tcreate`, or is walk-to-create enough as it is under FUSE?]
+]
+
+#entry("FIX-2", "The board's free-heap comment is two refactors out of date", state: "decided", tags: ("comment", "board", "one-line"))[
+  #ev("src/esp32p4.zig:470-473")[says 9,128 bytes free at 80×24. That was measured before `direct_emit` (`:870`) sized vaxis's two shadow grids to one cell.]
+  #ev("05-zig-p4/experiments/report.typ:848-849,877-880")[the heap now reports ≈336 KB free, and `.bss` in the 240 KiB low L2MEM is the binding constraint instead.]
+
+  #verdict[
+    Fix the comment and name the new constraint, because the stale number was
+    load-bearing in an architecture review — it is the reason a 9P server on
+    the board looked impossible when it costs 2.5% of free heap. A stale
+    measurement in a comment is worse than none: it gets quoted.
+  ]
+
+  #q[The `report.typ` figure of "336 KB at every geometry tried" cannot be literally true across the 62,480-byte swing between 56×14 and 80×24 at 55 B/cell. One boot and one `MARK PARDES_HEAP` line closes it.]
+]
+
+#pagebreak()
+
+= Direction
+
+The four entries below were written after the owner rejected the first
+synthesis as directionless and stated the goal himself: *"make it overall
+simpler, and more transparent to scripting and integrating over the network,
+and that could unlock some interesting things like chaining a pardes to
+another — right now these kinds of things are complex and ad hoc."*
+
+Three of those four are achievable. One is not, and `9P-20` says which.
+
+#entry("9P-19", "Bidirectional 9P is one role per CONNECTION, not one role per message", state: "decided", tags: ("protocol", "mechanism", "correction"))[
+  The owner's objection to the first review: *"you said the server can't
+  initiate a message, but since the daemon and the app both could have a client
+  and a server, they could communicate bidirectionally."* He is right, and the
+  mechanism is better than either of us described.
+
+  The tempting reading is a double-role link: both ends run a server and a
+  client on one descriptor, demuxing on the message-type parity, which 9P makes
+  possible for free.
+
+  #ev("u9fs/fcall.h")[`Tversion = 100, Rversion, Tauth = 102, Rauth, …` — T is even, R is odd, so a receiver can always tell a request it must serve from a reply it is owed.]
+
+  That reading is available and *nobody has ever built it*.
+
+  #ev("drawterm-9front/exportfs/io.c:132-163")[`io()` is a pure server loop: read a T-message, dispatch through `fcalls[type]`, reply. It never emits a message that is not a reply. Plan 9's `exportfs` is the same (`exportfs.c:510-515`), u9fs is the same, and v9fs and `devmnt` are pure clients. No implementation anywhere demuxes two roles on one descriptor.]
+
+  What ships instead is better, because it needs no invention at all:
+
+  #ev("drawterm-9front/cpu.c:119-192")[drawterm DIALS OUT to the cpu server, writes a shell script, and then calls `exportfs(fd, fd)` — *the dialer becomes the server on the socket it dialed*.]
+  #ev("principia-softwarica/networking/misc/cpu.c:448,459-463")[the script the remote runs is `mount -nc /fd/0 /mnt/term`, then it opens `/mnt/term/dev/cons` as its stdin and stdout. The remote is the CLIENT.]
+  #ev("drawterm-9front/kern/devdraw.c:1323-1326")[so when the remote application draws, the bytes cross as *the application's `Twrite`* to `/dev/draw/N/data`, and the terminal — the machine with the screen — executes them as a server.]
+
+  One descriptor, roles fixed per side, data flowing both ways. There is no
+  server push because none is needed: *the frame producer is the client.*
+
+  #verdict[
+    The rule for pardes, and it is the whole architecture in three lines:
+
+    / display: #[the FRONTEND is the server (it owns the screen), the CORE is the client. The core `Twrite`s frames to `screen` and blocking-`Tread`s `input`. This is `cpu` verbatim.]
+    / session: #[the CORE is the server (it owns the windows), scripts and other instances are clients.]
+    / devices: #[the BOARD is the server (it owns the memory and the pads), the core is the client.]
+
+    Three connections, one role each, and the program contains both halves. Do
+    NOT build a double-role single-descriptor link: no precedent, a `Tversion`
+    ordering hazard where each side must answer the peer's version while
+    awaiting its own, and `trans=fd` wants separate read and write descriptors
+    anyway.
+  ]
+
+  #note("mechanism", "2026-08-27")[
+    Two numbers that make the display path credible, both of which the first
+    review got wrong by assuming a push. Chunking is a non-issue: payload per
+    message is `msize − P9_IOHDRSZ` = 131,072 B at Linux's default
+    (`client.h:23`, `9p.h:364`), so every real frame — 20 B, a 56 B keystroke
+    diff, a 6,298 B full board frame, a 27 KB desktop frame — is ONE `Twrite`,
+    and even the 1,703,936 B worst case is 13. And the core need not block:
+    tags are allocated per outstanding request with no in-order reply
+    requirement (`client.c:194-199`, `devmnt.c:783-800`, and `exportfs`
+    deliberately answers out of order via slave procs, `exportsrv.c:408-520`).
+    pardes needs no slave procs — `Status.again` plus the park table is the
+    same thing done single-threaded.
+  ]
+
+  #note("mechanism", "2026-08-27")[
+    Copy the file discipline rather than inventing one. `/dev/draw/N/data` is a
+    write-only batched binary command stream (`devdraw.c:1323-1326`) with an
+    exclusive `ctl` (`:1047-1051`); `/dev/mouse` is an exclusive single-reader
+    file whose read blocks until something happens (`devmouse.c:96-98,150-158`).
+    That is exactly `screen` and `input`, already designed, already debugged,
+    and already the shape `event` has in `acmefs`.
+  ]
+]
+
+#entry("9P-20", "\"Simpler\" is false in lines and true in concepts — argue reach instead", state: "decided", tags: ("cost", "honesty", "framing"))[
+  The owner's first criterion was that 9P make the codebase *overall simpler*.
+  Measured, it does not. This entry exists so that nobody argues otherwise
+  later, including us.
+
+  The baseline: *nine* IPC mechanisms, *four* framings, *three* discovery
+  schemes, *two* version-negotiation schemes and one mechanism with none.
+
+  #ev("src/nested.zig")[743 lines to deliver ONE line. By region: 255 transport, 158 ancestor discovery, 43 `sendLook`, 232 tests, 30 header — and the FEATURE is ≈12 lines (`:301-306` format, `:507` filter). Ratio feature-to-transport ≈ 1:24.]
+  #ev("src/detached/wire.zig")[contains ZERO syscalls — no `socket`, `bind`, `accept`, `poll`, `read` or `write` anywhere. It is a pure codec into caller buffers, so calling 789 of its lines "transport" was wrong: they are the definition of what may be said. 9P replaces its 5-byte length prefix with a 4-byte one.]
+
+  Six concepts are genuinely duplicated across the mechanisms, and the
+  duplication is real: endpoint-path derivation 82 lines across 6 copies;
+  directory create-and-vet 105 across 6; stale sweeping 112 across 3;
+  bind/listen/accept 213 across 3; "which instance?" 231 across 3; version
+  negotiation 56 across 2. *799 lines, of which ≈330 is recoverable.*
+
+  #ev("src/fs_service.zig:37-55")[the comment there is right on the facts and wrong on the conclusion: `parentFrom` and `nested.socketDir` differ ONLY by appending `/pardes` under `$XDG_RUNTIME_DIR` and coincide verbatim under the HOME fallback. And there are two liveness oracles for one question — `kill(0)`/ESRCH at `nested.zig:401` and `fuse.zig:742`, `connect`/ECONNREFUSED at `server.zig:1940-1942`.]
+
+  #verdict[
+    Could delete ≈850 lines (`nested.zig`'s transport and its socket tests,
+    518; the net collapse of duplicated plumbing, ≈330). Could not delete
+    ≈7,700 — `fuse.zig` 2,709 (`9P-13`), `wire.zig` 1,705, the daemon's host
+    half, the 158-line ancestor walk that answers a question 9P has no message
+    for, and every kernel interface that was never a protocol choice (inotify,
+    pty, pipes, `mkstemp`).
+
+    Against a 1,600-1,900-line 9P stack (`9P-15`): *net growth of +750 to
+    +1,050 lines.*
+
+    So: strike "simpler" from every argument. What IS true, and is worth
+    saying, is that the CONCEPT count falls — four framings to two, three
+    discovery schemes to two, two version schemes to one, six duplicated
+    concepts to one copy each. Fewer ideas, more lines. Say exactly that.
+  ]
+
+  #note("contra", "2026-08-27")[
+    The strongest form of the objection, and it should stay on the record: the
+    three mechanisms do not share a problem. `nested`'s format is twelve lines
+    *because* it reuses a language pardes already speaks — the file says so at
+    `:14-16`, "no serialization, nothing to version". `wire`'s codec is 1,167
+    lines because it carries a 1.6 MiB worst-case RLE grid at one message per
+    frame. `acmefs` is 2,324 because it is acme's semantics. The general thing
+    costs ≈970 lines before saying anything specific to pardes, and each of the
+    three still needs its specific part afterwards.
+  ]
+]
+
+#entry("9P-21", "The lost compile-time invariant, which nothing else prices", state: "open", tags: ("cost", "correctness", "unpriced"))[
+  The best objection found against the whole direction, and no other entry
+  costs it.
+
+  #ev("src/detached/wire.zig:23-27")[«every union and every enum gets a tag chosen HERE … so reordering `Event` or `CellStyle.ul` cannot silently redefine the protocol. The mapping switches are exhaustive: adding a variant to the core is a compile error in this file, which is the point of them.»]
+  #ev("src/detached/wire.zig:1199-1265")[and a test enumerates the eleven legal client tags by name under the rule "A HUMAN DID IT", asserts the enum holds exactly those, and asserts the other 250 tag bytes answer `BadTag` — so a frontend built before a change cannot forge a pane's output into a session built after it.]
+
+  Under a `ctl`-file grammar, input arrives as `Twrite` payload bytes. 9P's
+  codec validates 9P; it cannot validate that a byte string is a legal `key`.
+  An exhaustive switch checked by the compiler and a 250-byte refusal test
+  become a runtime string parse with nothing to bind to.
+
+  #ev("src/host.zig:44-52")[a related loss: fourteen of twenty-one vtable methods are `push_` and return nothing, because "a push with an answer would have N answers and no way to pick one". 9P answers every T with an R, so each acquires a tag, a reply, and a matching obligation.]
+
+  #q[Three candidate answers, none costed yet. (a) Keep the typed wire for input and use 9P only for control and text — accepts two protocols forever. (b) Make the `ctl` grammar generated from the same enum, so the exhaustive switch survives as a parser generator and adding a variant is still a compile error. (c) Accept the loss and buy it back with a fuzz test over the grammar. (b) looks best and nobody has tried it.]
+]
+
+#entry("9P-22", "The real gap: pardes cannot ask another pardes anything", state: "decided", tags: ("direction", "motivating-case"))[
+  This is the entry the whole file was missing, and it is the owner's own
+  criterion stated precisely.
+
+  Two instances of pardes can do exactly two things to each other today.
+
+  / Shout: #[`nested.sendLook` formats `Look <path>`, connects, writes, returns `true`, and NEVER READS (`src/nested.zig:294-330`). The receiver filters for the one legal verb and closes (`:466-510`). The test at `:652-702` exercises the whole protocol and asserts that nothing comes back.]
+  / Become: #[`Attach` is not a connection, it is a replacement. Only on a successful handshake does the frontend reap its pane shells, close its watches, unmount `--fs`, *deinit the core*, and enter the thin loop (`src/detached/client.zig`, `docs/detached.md:207-213`). The local core is destroyed, not linked.]
+
+  Everything else is out of reach. Nothing in `src/` reads `PARDES_FS`; `Event`
+  has no variant for a peer; `Host.VTable`'s 21 methods have no peer method.
+  Reading another session's text is possible only by shelling out —
+  `Exec cat /run/user/1000/pardes/<other-pid>/1/body` — which is Linux-only,
+  opt-in behind `--fs`, requires already knowing the pid, and is mediated
+  entirely by `/bin/sh`. And it fails outright against a detached session,
+  which serves no filesystem at all (`src/detached/server.zig:566-570`).
+
+  #verdict[
+    *The direction is a reply.*
+
+    pardes has no request/response channel to anything that is not the kernel.
+    `nested` is one-way by construction. The detached wire forbids a round trip
+    inside `update` by design (`wire.zig:64-70`). `acmefs` has request/response
+    and cannot leave the machine (`fuse.zig:64`, `9P-13`).
+
+    9P is a request/response protocol that crosses machines, and that single
+    property is what the other three cannot be extended to have. Every good
+    thing on the list — scripting from macOS, driving a session over a network,
+    reading the board's memory, chaining one instance to another without
+    destroying either — is the same feature: *being able to ask, and get an
+    answer back.*
+
+    That is the justification. Not simplification (`9P-20` forbids it), not
+    elegance, and not symmetry.
+  ]
+
+  #note("direction", "2026-08-27")[
+    The measure of success, so this can be checked rather than admired: after
+    the work, `Attach` should have a sibling that CONNECTS instead of
+    replacing — two live cores, each able to walk the other's tree — and the
+    twelve-line `Look` sentence should be a `Twrite` to the other instance's
+    `new/` on a connection that can also answer. If those two things are not
+    true at the end, the protocol was adopted for its own sake.
+  ]
+]
+
+#entry("9P-23", "The host vtable stays; 9P is one implementation of it, for remote hosts only", state: "decided", tags: ("architecture", "scope-limit"))[
+  The grand version of the direction was that `Host.VTable` becomes a tree the
+  core mounts, so that the downward seam and the outward seam are the same kind
+  of thing. Measured, that is wrong for every LOCAL host and right only for
+  remote ones.
+
+  #ev("src/host.zig:52-140")[the seam is 21 methods: 15 `push_` and 6 `pull_`, with the prefix compiler-enforced (`isPull`, `:265-274`) — a `push_` returning non-void does not build.]
+
+  The blocking objection turns out to be nearly empty. Of the six `pull_`
+  methods, three are ALREADY asynchronous — `pull_read_clipboard`, `pull_lsp`
+  and `pull_pipe` return `void` and their answers arrive as `Event.paste`,
+  `.lsp_resp`, `.pipe_resp` (`src/pardes.zig:6896-6907`). `pull_wait_input`
+  cannot become an event because it is how events arrive. That leaves two:
+  `pull_gpio_toggle`, whose answer is only used to set a message row
+  (`board_memory.zig:422-428`), so deferring it a frame is invisible; and
+  `pull_tty_taken`, which is reached from `takesCommandLine`
+  (`pardes.zig:6465-6469`) at four call sites, two of which loop over all 16
+  panes — 16 probes per call, collapsing to ONE read if `proc` is a single file
+  of sixteen lines rather than `proc/N/status`.
+
+  So the core could be a 9P client without blocking. It should not be, locally:
+
+  #ev("per-host measurement")[bodies replaced by an estimated 9P server, per host: tty 345 → ≈225 but *+204* with the tree and `ctl` grammars; gui *+204*; detached server *+182*; macos *+164*; web *+142 Zig plus ≈500 lines of JavaScript*; board *+59* and 8,832 B of RAM. *No host gets simpler.*]
+  #ev("src/web.zig:356-391")[and web gets actively worse than the count shows: `present` today writes a flat `WebCell` array that JavaScript reads *directly out of wasm memory* across four `extern` declarations (`:330-340`). Under 9P that zero-copy array becomes an RLE stream JS must decode, and wasm32 has no sockets, so JS must carry a 9P codec too.]
+  #ev("src/esp32p4.zig:127")[the board is worse still in kind: its "host" is the same process behind a C-ABI function pointer, so a `Twrite`/`Rwrite` pair per frame is pure protocol overhead against a direct call.]
+
+  #verdict[
+    `Host.VTable` is already the abstraction — `docs/design.typ:1964-1965` says
+    the surface IS the abstraction and refuses a render layer over the shells.
+    A tree would be that layer.
+
+    So: a 9P host is *one more implementation of the existing vtable*, chosen
+    when the display is on the other end of a wire, exactly as `9P-2` makes a
+    9P transport one more implementation of the filesystem seam. Local hosts
+    keep the direct call and pay nothing. The two seams stay two seams; what
+    they gain is a second backend each.
+
+    That also settles `9P-19`'s scope: the core is a 9P client of its display
+    only when the display is REMOTE — a detached frontend, or a board acting as
+    a terminal for a full core elsewhere. Never for the window in front of you.
+  ]
+
+  #note("correction", "2026-08-27")[
+    Fact correction for anything quoting the earlier tally: `tty` and `gui`
+    fill *19* of 21, not 20 — `src/detached/server.zig:558-559` already says
+    "NINETEEN each". The 20 figure was wrong by one and is superseded here.
+  ]
+]