path: root/docs/9p.typ

// Second draft. The first is superseded; what changed and why is recorded
// entry by entry in `docs/registry.typ`, and every §-to-entry link below is
// live. Build:  typst compile docs/9p.typ docs/9p.pdf
#let app = "PaRDeS"

#set page(
  paper: "us-letter",
  margin: (x: 1.5in, y: 1.2in),
  numbering: "1",
  number-align: center,
)
#set text(font: "Libertinus Serif", size: 11pt, lang: "en")
#set par(justify: true, leading: 0.62em, first-line-indent: 1.5em)
#show raw: set text(font: "DejaVu Sans Mono", size: 8.5pt)
#show raw.where(block: true): block.with(inset: (left: 1.5em, y: 0.4em), width: 100%)
#set table(stroke: none, inset: 0.35em)

#set heading(numbering: "1.")
#show heading: it => {
  set text(size: 11pt, weight: "bold")
  v(1.1em, weak: true)
  block(counter(heading).display() + h(0.6em) + it.body)
  v(0.4em, weak: true)
}
#show heading.where(level: 1): it => {
  set text(size: 11pt, weight: "bold")
  v(1.4em, weak: true)
  block(counter(heading).display() + h(0.6em) + it.body)
  v(0.5em, weak: true)
}

/// A registry cross-reference. Every contestable claim in this note is an
/// entry over there, with its evidence and its losing arguments attached.
#let r(id) = text(size: 9pt)[#raw(id)]

#align(center)[
  #v(0.5em)
  #text(size: 15pt)[A File Interface for an Editor and Terminal Multiplexer]
  #v(0.9em)
  #text(size: 10.5pt, style: "italic")[architecture draft, second revision]
  #v(0.4em)
  #text(size: 10pt)[#datetime.today().display("[year]-[month]-[day]")]
]

#v(1.2em)

*Historical proposal, superseded by `docs/fs.md`.* Pardes now serves 9P by
default over Unix sockets, with optional TCP and QUIC. FUSE support and the
old examples have been removed. The arguments and source references below
describe the earlier implementation, not the current interface.

#block(inset: (x: 2.5em))[
  #set text(size: 10pt)
  #set par(first-line-indent: 0em)
  #text(weight: "bold")[ABSTRACT] #h(0.8em)
  #app is an editor with attached terminals. It runs as a daemon; clients attach
  to it. It already serves acme's control filesystem, over FUSE, on Linux only.
  This note adds 9P as that filesystem's second transport, and as a carrier for
  the display protocol it already has. The program becomes a file server that
  needs no kernel, so the tree reaches macOS, a browser tab, a microcontroller
  and another machine, none of which FUSE can reach. The same program is also a
  9P client, which is how it edits a file on a board it cannot mount. We
  describe the interface, what it costs — measured against two shipping
  implementations rather than estimated — and, at greater length, the parts we
  do not build. The first draft of this note proposed replacing FUSE and
  replacing the wire protocol. Both are wrong, for reasons that turn out to be
  cheap to state and expensive to discover.
]

= What this is for

One sentence, because every other section is downstream of it.

*PaRDeS has no way to ask anything a question.* It can ask the kernel, and that
is all. Two running instances can do exactly two things to each other: shout —
`nested.sendLook` formats one line, connects, writes, returns, and never reads,
and its own test asserts that nothing comes back — or *become*, which is what
`Attach` does, and `Attach` is not a connection but a replacement: on a
successful handshake the frontend reaps its pane shells, closes its watches,
unmounts its filesystem, deinitialises the core, and turns into a thin client of
somebody else's. Nothing in the tree reads `PARDES_FS`. `Event` has no variant
for a peer. The 21-method host vtable has no peer method. Reading another
session's text is possible only by shelling out to `cat` a path derived from a
pid you must already know, on Linux, if that session was started with `--fs` —
and impossible against a detached session, which serves no filesystem at all.

9P is a request/response protocol that crosses machines. That property is the
one thing none of the three private mechanisms can be extended to have, and
every item on the wanted list is the same feature wearing different clothes:
scripting from macOS, driving a session over a network, reading the board's
memory, chaining one instance to another without destroying either. All of it
is *being able to ask, and get an answer back*.

That is the justification, and it is the only one. In particular it is not
simplification: §12 puts the honest figure at between 750 and 1,050 lines of
net growth, and the measurement is in the registry, not in a hope. What does
fall is the number of ideas — four framings become two, three schemes for
"which instance?" become two, two version negotiations become one, and six
concepts currently duplicated across 799 lines become one copy each. Fewer
ideas, more lines. Anyone selling this as "simpler" has not counted.

= What changed, and why this draft exists

The first draft argued that 9P should replace two things: the FUSE mount, and
the private protocol on the daemon's socket. Neither survives contact with the
sources.

It cannot replace the mount. Linux grades mount privilege by a per-filesystem
flag, and 9P and FUSE are on opposite sides of it. `mount_capable` falls back to
`capable(CAP_SYS_ADMIN)` — root in the *initial* namespace — for any filesystem
that does not set `FS_USERNS_MOUNT`; FUSE sets it, v9fs does not. So
`mount -t 9p` costs real root, a user namespace does not help, and `trans=fd`
does not help because the syscall is checked before the transport is consulted.
The 281 lines in `src/fuse.zig` that fork a setuid helper and receive a
descriptor over `SCM_RIGHTS` are not overhead; they buy an unprivileged
pathname, which 9P cannot buy at any price on Linux. The usual escape, `9pfuse`,
is FUSE again in someone else's process — which is exactly what `ad`, the one
editor that already took this route, ships #cite(<ad>). #r("9P-13")

It cannot replace the wire either, because the wire's payload is a compressed
cell grid and 9P has no server-initiated message. But the interesting half of
that finding is that 9P *can carry* the wire unchanged, and that this is how
remote display has actually shipped for thirty years #cite(<devdraw>). #r("9P-12")

What is left is better than what was proposed, and smaller.

= Two layers

The first draft's mistakes are almost all one layer's property asserted about
the other, so the layers are worth naming before anything else.

*Layer 1 is the control tree.* Request and response, nine operations, a pure
transaction over the core: `handle(p, req) Reply` in `src/acmefs.zig`, whose ABI
already records that "FUSE opcodes, 9P messages and a unit test all reduce to
these". It is transport-neutral today and unit-tested with no transport at all.

*Layer 2 is the display protocol.* Nineteen message tags in
`src/detached/wire.zig` carrying run-length-encoded cell grids and input, one
message per frame, pushed by the server to N frontends that share one screen.

They share a machine and nothing else. The tree is not private and not
undocumented — it is acme(4) #cite(<acme>). The wire is both, and deliberately:
it is a codec, and its cost is measured at seven lines per new fact, which is
cheap for what it does.

9P is Layer 1's second transport and Layer 2's carrier. It is never a
re-encoding of either. #r("9P-1")

= The interface

A session is a tree. Windows are numbered directories under it.

```
/
  ctl                 session control; read lists windows
  index               one line per window: id, tag, flags
  new/                walking here creates a window
  7/
    ctl               commands in; id and state out
    tag               the tag line
    body              the text
    addr              an address
    data              read and write at addr
    event             the interesting one; see below
    errors            writes appear in the error window
    pty/
      data            the stream
      ctl             winsize, raw, cooked, sig, exec
      status          dimensions, mode, exit status
```

This is acme's tree plus `pty/`, minus the plan9 compatibility stubs. Four
conventions matter, and the first draft got three of them wrong.

*Offsets are honoured everywhere they mean something.* `body`, `tag`, `addr`,
`ctl`, `index` and `rdsel` are seekable files and are read at the offset the
message carries. acme does the same, and its entire byte-to-rune cache exists to
serve a non-zero offset on `body`. Only `data` and `event` ignore offsets, and
only because they are positioned by `addr` and by the queue respectively. All
writes ignore offsets: a write to `body` appends, which acme(4) specifies. A
server that ignored offsets on `body` would make `cat`, `wc`, `diff` and `tail`
return the first chunk forever, which is the opposite of the whole point.

*Directory reads carry a cookie, not an index.* 9P requires a directory read at
offset zero or at exactly the byte offset where the previous read ended, and the
reply must contain whole `stat` entries; anything else is `Ebadoffset`. The core
counts entries, so the transport keeps a per-fid byte cursor and the one entry
that did not fit. This is the only genuine offset discontinuity between FUSE and
9P, and it is about forty lines. #r("9P-5")

*The address belongs to the window.* The first draft claimed per-fid and
attributed it to acme; acme keeps `Range addr` in `struct Window`, #app keeps it
per pane, and `ad` keeps it per buffer. Per-fid is a real improvement — two
scripts could then address one window without colliding — but it is a proposal,
not a restatement, and it is the only thing in this note that asks the core to
grow state. It is argued on its own merits or not at all. #r("9P-6")

*`event` is opened by a client, not by a fid.* One controller per window is
right; enforcing it per fid is not, because a client that opens the file twice
is not two controllers. `ad` reaches the same conclusion and scopes `QTEXCL` to
a connection. #r("9P-7")

= Events

A window handles its own mouse and keyboard until a program opens `event`. From
then on it ships them out: origin, action, the character range, the text. The
program reads a record, decides, and writes it back to accept it; or handles it
itself and stays silent.

This is the whole extension mechanism and it already works — `examples/acmefs/`
has four programs that use it, one of which puts words #app has never heard of
into a tag and makes them execute. There are no callbacks and no plugin API. A
program that wants to redefine what the right button does opens a file and reads
it.

A read blocks. The core does not: it answers `again` — nothing consumed, ask me
later — and the transport holds the request. That inversion is what lets a
single-threaded core serve a filesystem at all, and it is worth stating plainly
because the prior art does not have it. `ad` spends three to four threads per
connection and then serialises all of them behind one mutex and a blocking
round trip into the editor thread. #app answers a blocked `event` read in
twenty-one nanoseconds and allocates nothing.

= Terminals

A pty is a file interface wearing the wrong clothes. Everything one wants to do
to it is an `ioctl`, and 9P has none in any dialect. They become writes to
`pty/ctl`:

#v(0.3em)
#align(center)[
  #set text(size: 9.5pt)
  #table(
    columns: 2,
    align: left,
    column-gutter: 2em,
    row-gutter: 0.3em,
    [`TIOCSWINSZ`], [`winsize 80 24`],
    [`TCSETS`], [`raw`, `cooked`, `echo off`],
    [`kill`], [`sig INT`],
    [`TIOCGWINSZ`], [read `status`],
    [spawn], [`exec /bin/sh`],
  )
]
#v(0.3em)

`pty/data` is the stream. A write is input to the process; a read blocks until
there is output. On exit a read returns zero bytes rather than an error, because
clients already know what end of file means.

Two things about this section that the first draft did not say. It has *nothing
to do with 9P*: `push_spawn` and `push_pty_resize` are effects the core already
has, so `exec` and `winsize` are existing capabilities acquiring a name, and
`sig INT` is the only new one. Build it in the FUSE tree first and the 9P
transport inherits it. And it has *no prior art anywhere*: acme has no pty
files, `ad` has no terminal surface at all. Being first is a reason to keep it
to three files and stop. #r("9P-8")

Every keystroke in raw mode is a round trip. On a local socket this does not
matter. Over a slow link it matters a great deal, which is why Plan 9's terminal
programs do line editing locally and send whole lines. Raw mode should be
entered deliberately and left promptly.

= Layering: how 9P and the wire meet

Six arrangements were costed. The finding that decides it is that the cost is
almost the same in all of them: a base-9P2000 codec, a dispatcher onto the
existing nine operations, and a fid table come to roughly 970 lines that appear
in every option. Layering moves about 150 lines either way. So this is not a
cost question. It is a question of reach.

#v(0.3em)
#align(center)[
  #set text(size: 9pt)
  #table(
    columns: (auto, auto, auto, 1fr),
    align: (left, right, right, left),
    stroke: (y: 0.4pt),
    table.header([], [msgs/frame], [msgs/key], [what decides it]),
    [O1 9P replaces all], [2], [4], [64 park slots needed against 32; a round trip per frame],
    [O2 two listeners], [1], [2], [no routing origin for the 9P descriptor],
    [O3 9P inside the wire], [1], [2], [*works over the board's UART unchanged*],
    [O4 wire inside 9P], [2], [4], [+34 B on a 56 B diff, or +61%],
    [O5 side by side], [1], [2], [cheapest, but cannot reach the board],
    [O6 frontend serves], [2], [4], [core would write and match tags inside `update`],
  )
]
#v(0.3em)

That table is superseded, and the correction is the most important thing in
this note. It was written believing 9P has no way to push a frame, so every
arrangement that carried frames over 9P paid a round trip. The premise is
wrong — not because 9P can push, but because *the pushing end should be the
client.*

Plan 9 has shipped this for thirty years and it needs no invention. `drawterm`
dials out to a cpu server, writes a shell script, and then calls
`exportfs(fd, fd)`: the dialer becomes the *server* on the socket it dialed.
The script the remote runs is `mount -nc /fd/0 /mnt/term`, and the remote is
the *client*. 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. One descriptor, roles fixed per side, data
flowing both ways, no server-initiated message anywhere.

So the rule is one role per connection, not one role per message:

#v(0.3em)
#align(center)[
  #set text(size: 9.5pt)
  #table(
    columns: (auto, auto, 1fr),
    align: (left, left, left),
    column-gutter: 1.2em,
    row-gutter: 0.3em,
    [*display*], [frontend serves], [core `Twrite`s frames to `screen`, blocking-`Tread`s `input`],
    [*session*], [core serves], [scripts and other instances walk `7/body`, `event`, `ctl`],
    [*devices*], [board serves], [core reads `mem/`, `gpio/`, `prof`],
  )
]
#v(0.3em)

Three connections, one role each; the program contains both halves and uses
whichever the link calls for. Do *not* build a link that carries both roles at
once. 9P permits it — T-messages are even and R-messages odd, so a stream is
self-demuxing — but nothing has ever done it, and it buys a `Tversion` ordering
hazard in which each side must answer the peer's version while awaiting its
own.

Two numbers make the display path credible. Chunking is a non-issue: payload
per message is 131,072 bytes at Linux's default, 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 the 1.7 MB worst case is thirteen. And the core need not block:
tags are allocated per outstanding request with no in-order reply requirement,
which is why `exportfs` can answer out of order at all. Where `exportfs` needs
a slave process per blocked request, PaRDeS needs none — `Status.again` and the
park table are the same thing done single-threaded.

Copy the file discipline rather than inventing one: `/dev/draw/N/data` is a
write-only batched binary command stream with an exclusive `ctl`, and
`/dev/mouse` is an exclusive single-reader file whose read blocks until
something happens. That is `screen` and `input` already designed, and it is the
shape `event` already has.

Frames are never re-represented. Whatever carries them carries `encodeFrame`
bytes; the existing five-byte length prefix already makes such a message a legal
9P payload. The counter-example is worth keeping in view: Plan 9's `/dev/screen`
is an offset-addressed raster a client polls, with no change notification, which
is precisely why nobody ever ran a remote rio through it.

One scope limit, measured and not negotiable. This applies to *remote* displays
only. Turning the local host vtable into a tree costs every shell more than it
saves — tty and gui about +204 lines each, macOS +164, and the web shell +142
lines of Zig plus roughly 500 of JavaScript, because its `present` today writes
a flat cell array that JavaScript reads straight out of wasm memory and 9P would
make that an RLE stream needing a decoder and a codec. The board is worse in
kind: its host is the same process behind a function pointer, so a message pair
per frame is overhead against a direct call. `host.VTable` is already the
abstraction — the design document says the surface *is* the abstraction and
refuses a layer over the shells — so a 9P host is one more implementation of
that vtable, chosen when the display is on the other end of a wire, and never
for the window in front of you. #r("9P-19") #r("9P-23")

= The client half

The same program is a 9P client. This is not symmetry for its own sake: it is
how one instance shows another instance's windows, and how it edits a file on a
machine it cannot mount.

The client half needs no mount, and after §1 that is no longer one advantage
among several — it is the whole of what 9P buys that we cannot otherwise have.
To edit a file on the board, #app walks to `board/fs/etc/config`, opens, reads,
edits in a buffer, writes, and clunks. There is no path on the local machine, no
kernel involvement, and no privilege. That works on macOS, which has no 9P in
the kernel and no control filesystem at all today; it works in a browser tab,
which has no filesystem at all; it works on the board, which has no sockets; and
it works when the operator is not root, which on Linux is now the interesting
case.

A mount is still worth offering, because `grep`, `make` and the compiler take
filenames and a filename is the one thing a client library cannot produce. But
on Linux that mount is `src/fuse.zig`, which we keep, or it is `9pfuse`, which
is `src/fuse.zig` written by someone else. It is not `mount -t 9p` unless the
operator is root and chooses to be.

= The board

The microcontroller is the case that motivated this note, and both the first
draft and its review were wrong about it in opposite directions.

The first draft said the board runs "a 9P server and nothing else". It runs the
whole editor, as firmware, with two of twenty-one host methods filled. The
review said a 9P server would not fit, quoting nine kilobytes of free heap. That
number is two refactors stale: since the shadow grids were reduced to one cell,
the heap reports around 336 KB free and the binding constraint moved to the
240 KiB of low memory that holds `.bss`. #r("FIX-2")

Costed from real components, a 9P server on this board is:

#v(0.3em)
#align(center)[
  #set text(size: 9.5pt)
  #table(
    columns: (auto, auto, 1fr),
    align: (left, right, left),
    column-gutter: 1.2em,
    row-gutter: 0.3em,
    [two `msize` buffers], [8,192 B], [u9fs uses three; a minimal server needs two],
    [fid table, fixed array], [512 B], [32 entries × 16 B, linear scan ≈0.4 µs],
    [codec scratch], [128 B], [one `stat`, `ERRMAX`],
    [#text(weight: "bold")[RAM total]], [#text(weight: "bold")[8,832 B]], [2.5% of free heap],
    [flash, 9P-only image], [≈39 KiB], [2.5% of a 1.5 MB partition],
  )
]
#v(0.3em)

The 4,096-byte floor that sizes those buffers is imposed by the Linux kernel and
by nothing else; Plan 9, plan9port and #app's own client all accept a
512-byte `msize`, which would halve them. And a 4,096-byte reassembly buffer
already exists on this exact serial line, with the property measured: that much
in a single write arrives intact.

So it fits, easily. What does not work is having it both ways: the editor owns
the one UART bidirectionally and the board's header exposes no second one, so a
9P server on the P4 is a *second firmware image*, not a second role for this
one. The build already expresses that shape — the on-die test suite is a
separate executable with its own image and flash steps in fifty-four lines, and
it links no editor object. The board is an editor or a filesystem, and saying so
is better than implying both. #r("9P-11")

Before quoting any latency for it, raise the console to 921600 baud. It is one
divider write on the existing crystal, the routine already exists, and it takes
a warm read of a small file from 10.8 ms to 1.35 ms. #r("BOARD-1")

The tree such an image would serve is not invented. The board already exposes
its whole address space, its pin header and one pad toggle — as *acme words a
human types into a tag*, capped at four kilobytes per command because of the
console, with the answer landing in an output pane. Nothing about it is
machine-readable and nothing is remote. `mem/`, `gpio/pinout` and `prof` are
backed by functions that exist today; four more files need one new exported
symbol each; four have no implementation at all. A 9P tree is that capability
with names instead of verbs, and the inventory above is the honest scope.

= What we do not build

The temptation in this design is to keep going. Each of the following was
considered and declined.

*A window system.* #app draws in one window. Panes are ours; surfaces are not.
Becoming a Wayland compositor would buy the ability to put someone else's
program in a pane, and cost input handling, buffer management, output hotplug,
scaling, clipboard, and a permanent maintenance obligation against a moving
protocol. We do not want someone else's program in a pane.

*A namespace.* Per-process namespaces, union directories, `bind`, and walks that
cross mount points are what make Plan 9's implementation large #cite(<plan9>).
The distinction is worth defending, because the first union directory brings the
rest.

*An aggregate.* The first draft's longest technical section described a prefix
router that re-exports attached instances, and its own final section concluded
the aggregate is not worth building before a second machine exists. That verdict
is right and also covers the client half of it. It also understates the work: a
proxied `Twalk` cannot be answered until the remote `Rwalk` arrives, and the
core may not block, so it is not a fid map — it is per-tag continuations, tag
remapping, flush forwarding and fid invalidation on connection death, in a
daemon that is one `poll(2)` with no worker pool. Deferred with a named
precondition rather than described as easy. #r("9P-10")

*A file server.* Where a host's files must be exported, we run `u9fs` or `diod`
and attach as a client #cite(<u9fs>). Real filesystems are where the difficulty
in 9P actually lives: stable qids, `..` clamped at the export root, symlinks
that escape, identity mapping, and the full `wstat` surface. Our own trees are
synthetic, so we invent every file and there are no cases we did not choose.
Note that `u9fs` serves its requests from a strictly serial loop and its flush
handler is a `break`, so it is a reference for the tree and not for §10.

*Authentication.* Not now, and not by us. The Unix socket is protected by the
permissions on the socket. Where a network is involved, the connection is
tunnelled. Linux's client never sends `Tauth` at all, and Plan 9's `mount` only
does so without `-N`, so a server that refuses it is not an obstacle to either.
Real authentication is `Tauth` or TLS, and it can be added without changing the
tree.

= Protocol notes

We serve base 9P2000 #cite(<intro5>). Plan 9 mounts it natively, plan9port's
`9p` speaks it, and Linux mounts it with `version=9p2000` #cite(<v9fs>). The
following are the traps, in the order they will bite. Each is cheap once known
and each has been shipped wrongly by someone.

*Set `qid.version` to zero on every file.* This is the 9P equivalent of FUSE's
`FOPEN_DIRECT_IO` and it is server-side, not advice to the operator: Linux's
client disables both read and write caching for any file whose qid version is
zero, whatever the cache mode, unless `ignoreqv` is passed explicitly. A
synthetic tree of live editor state has no business being cached, and this is
how we say so. The first draft's "mount with `cache=none`" was unnecessary; its
claim that the default message size is small was simply wrong, since the default
is 128 KiB and the cap is 1 MB. #r("9P-3")

*Clamp every reply to the client's `count`.* An `Rread` longer than the count
asked for is a hard `EIO` in the Linux client, not a truncation. This has no
FUSE analogue, which is why nobody looks for it, and `ad` gets it wrong on
exactly the file we care about. The existing rule that a read too small for one
event record is refused rather than split is what makes the clamp safe on
`event`. #r("9P-17")

*Decide the error ABI deliberately.* `Rerror` in base 9P2000 is a string, and
Linux recovers an errno by exact match against a fixed table; a miss is not
`EIO` but `ESERVERFAULT`, which userspace prints as "Unknown error 526". `ad`
emits nineteen prose strings and not one of them is in that table. Either emit
the exact strings Linux knows, or serve 9P2000.u and send the number. The second
also restores `statfs`, which base 9P2000 does not have and which the core's
operation set includes. #r("9P-4")

*`Tflush` is a park-table lookup.* The common failure is not omitting it — it is
implementing the message and still hanging, which is what `ad` does: correct
`Rflush` ordering in thirty-nine lines, and a filesystem hook that defaults to
doing nothing. #app is structurally better placed than either reference, because
the thirty-two-slot park table is already keyed per outstanding request and
already answers `FUSE_INTERRUPT` the same way. Implement flush against the
table, not against a callback, and the bug is unrepresentable. #r("9P-16")

*Serve requests concurrently.* Several tags may be outstanding on one connection
and `event` reads block by design. This does not require threads: it requires
that a blocked request be parked rather than waited on, which is what the core's
`again` already means.

= Cost, and the order to build in

The honest figure is 1,600 to 1,900 lines of server plus around 500 of tests.
This is measured, not estimated: `ad`'s 9P2000 server core is 2,321 lines
(codec 704, stat and mode 437, session and fid and flush 615, loop and handlers
474) and `u9fs` is 1,838 with an 805-line codec. Two independent
implementations agree on codec ≈750 and server logic ≈1,700. Roughly 970 of
those lines are identical under every layering, so none of the estimate is at
risk from §6. #r("9P-15")

What comes off against it has now been counted too, and it is less than hoped.
Six concepts are genuinely duplicated across the existing mechanisms —
endpoint-path derivation in six copies, directory create-and-vet in six, stale
sweeping in three, bind/listen/accept in three, "which instance?" in three, and
version negotiation in two — 799 lines in total, of which about 330 collapses
to one copy. Add `nested.zig`'s socket half and its socket tests, 518 more, and
the deletion is *≈850 lines*. What cannot be deleted is ≈7,700: `src/fuse.zig`
by §1, `wire.zig` because frames stay frames, 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, the pty, the
subprocess pipes, `mkstemp`.

*Net: between 750 and 1,050 lines of growth.* It breaks the house rule that a
change leaves the file it touches no longer than it found it, §1 forbids
retiring `src/fuse.zig` in exchange, and there is no arithmetic that rescues
it. The growth is justified by reach and by §0's reply, or it is not justified.

One cost is still unpriced and should be before any code is written. `wire.zig`
chooses every protocol tag in one file so that reordering a core enum is a
compile error, and a test asserts that exactly eleven client tags exist and that
the other 250 bytes are refused, so a frontend built before a change cannot
forge a pane's output into a session built after it. 9P's codec validates 9P; it
cannot validate that a byte string is a legal keystroke. An exhaustive switch
checked by the compiler becomes a runtime string parse with nothing to bind to.
The likely answer is to generate the `ctl` grammar from the same enum so the
compile error survives as a parser generator, but nobody has tried it.
#r("9P-20") #r("9P-21")

The order matters more than the total. Each step is stated with what it is,
where it lands, what becomes possible that was not, and how you know it worked.
Steps 1 to 3 are independent of each other and of 9P; step 4 needs step 2;
step 6 needs step 5. Any prefix of this list is a reasonable place to stop.

== Step 1 — let a detached session be scripted

A daemon started with `--detach=work` holds the core, and today it serves no
control filesystem at all: `src/detached/server.zig:566-570` records that it has
no `push_fs_reply` "because this process mounted no /dev/fuse". It simply never
calls `fs_service.start`. Nothing prevents it.

The change is a `Source.fuse` variant in the poll union, an `fs` field, the
`fs_service.start` call, `fsReply` copied verbatim from `src/tty/tty.zig`, one
vtable entry, a pollfd and its dispatch arm, and the `drain` call. About sixteen
lines. It is *better* in the daemon than in the desktop hosts: those need a
background thread to notice a request, and the daemon's own `poll(2)` already
watches everything, so it can watch `/dev/fuse` too and the thread disappears.

After: `pardes --detach=work` and then `ls $XDG_RUNTIME_DIR/pardes/<pid>/` works,
and every script in `examples/acmefs/` drives a daemon it previously could not
see. Proof is those four programs and the existing filesystem snapshots, run
against a detached session instead of a local one. #r("9P-14")

== Step 2 — name the transport seam

`fs_service.drain` and `step` take a `*fuse.Fs`, but they only ever call three
methods on it: `retry()`, `next()` and `reply()`. Replace the concrete pointer
with a context pointer and a three-function vtable, at the three call sites in
`tty.zig` and `gui.zig`. Forty lines changed, none added, `fuse.Fs` is the first
implementor, and nothing observable changes.

This is the whole preparation for a second transport, and it is worth doing on
its own merits: if 9P is never written, the seam is documented in code rather
than in a comment. #r("9P-2")

== Step 3 — make terminals scriptable

Add `pty/data`, `pty/ctl` and `pty/status` to each pane's directory in
`src/acmefs.zig`, with `ctl` taking `winsize 80 24`, `raw`, `cooked`,
`echo off`, `sig INT` and `exec /bin/sh`.

Today a script can write into a terminal that already exists and read its
rendered scrollback, and that is all — it cannot start one, resize one, or
signal one. Two of those are free: `push_spawn` and `push_pty_resize` are
already effects the core emits (`src/host.zig:80-82`), so `exec` and `winsize`
are existing capabilities acquiring a name. Only `sig INT` is new work; there is
no `kill` anywhere in `host_io.zig`.

This has nothing to do with 9P. It lands in the FUSE tree, works immediately,
and any later transport inherits it. Keep it to three files: acme has no pty
files and neither does `ad`, so there is no prior art to be wrong about, which
is a reason for restraint rather than ambition. #r("9P-8")

== Step 4 — serve the existing tree over 9P

A new `src/ninep.zig`: base 9P2000 over a unix socket, serving exactly the tree
`src/acmefs.zig` already defines. No client, no aggregation, no `aname`, and no
new files — step 3 already added the only ones wanted.

Implement `Tversion`, `Tattach`, `Twalk`, `Topen`, `Tread`, `Twrite`, `Tclunk`,
`Tstat`, `Twstat` and `Tflush`, and answer `Rerror` to `Tauth`, `Tcreate` and
`Tremove`. Lift the park table and its `retry`/`take`/`freeSlot`/`findSlot`
helpers out of `src/fuse.zig` unchanged — `Status.again` means the same thing to
both transports. What is genuinely new is the codec, the fid table, a per-fid
directory cursor, and `stat` marshalling. Every trap in §11 applies here and
nowhere else.

After: macOS and the browser have a control filesystem for the first time, and a
script on another machine can drive a session over TCP. On Linux the FUSE mount
stays, because `mount -t 9p` needs root and `fusermount3` does not — the two are
complementary, not competing. Proof is the existing snapshots run through the
9P transport unchanged, and `examples/acmefs/` run through `9pfuse`. #r("9P-15")

== Step 5 — become a 9P client

The other half, and the one that moved up the list, because it is the mechanism
for everything the note is for. A server lets pardes be *talked to*; a client is
how pardes *asks*.

It is a state machine over a byte stream — walk, open, read, write, clunk — with
no kernel, no mount and no privilege, and the protocol layer is freestanding-safe:
no allocator, no threads, no sockets, so it runs on the board's UART and in the
browser as readily as on a socket.

After: `Look board/fs/etc/config` opens a file that lives on the microcontroller,
in a pane, with no mount anywhere. And `Attach` gains the sibling it has always
needed — one that *connects* instead of replacing. Today `Attach` deinitialises
the local core and turns the process into a thin frontend; the new word leaves
both cores alive and lets each walk the other's tree. That is the "chaining"
that is currently impossible. #r("9P-22")

== Step 6 — let a remote display serve the core

A frontend exports `screen`, `input`, `snarf` and `ctl`; the core dials it and
becomes its client, writing frames to `screen` and taking a blocking read on
`input`. This is `drawterm` exactly, and the file discipline should be copied
rather than invented: a write-only batched command stream with an exclusive
`ctl`, and an exclusive single-reader input file whose read blocks.

The frame bytes are `encodeFrame` output verbatim — the codec does not change,
only what carries it. *Remote displays only.* The window in front of you keeps
the direct vtable call, because a tree costs every local shell more than it
saves.

What this actually unlocks: the ESP32-P4 stops being a shrunken pardes — an
809 KB image running a subset of the editor in 384 KB of RAM — and becomes a
terminal for a full core running on the workstation. Roughly 39 KB of firmware,
and it gains language servers, tree-sitter and PDF because those now run
somewhere that can afford them. Raise the console to 921600 baud first, or every
measurement will be eight times worse than it needs to be. #r("9P-19") #r("BOARD-1")

= Status

The tree, the event protocol, the pty control language and the layering are
settled enough to implement, and the registry holds the arguments that settled
them. Three questions remain genuinely open: whether the address becomes a
per-fid property and the core grows state to hold it #r("9P-6"); which error ABI
we adopt #r("9P-4"); and whether the parked second core on the board could own a
9P server so the board need not choose between being an editor and being a
filesystem #r("9P-11").

Steps one through three are worth doing whatever the answer to the rest is,
which is the best property this plan has.

#v(1.5em)
#line(length: 30%, stroke: 0.5pt)
#v(0.5em)

#set text(size: 9.5pt)
#set par(first-line-indent: 0em)

#bibliography(
  title: none,
  full: false,
  ("refs.yml"),
)