summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/next-plumber.md896
1 files changed, 896 insertions, 0 deletions
diff --git a/docs/next-plumber.md b/docs/next-plumber.md
new file mode 100644
index 00000000..76a86bea
--- /dev/null
+++ b/docs/next-plumber.md
@@ -0,0 +1,896 @@
+# The plumber in pardes's core: the design record
+
+> it's really about time to write the acme plumber, it's a real part of the
+> core that we're missing. You may use its code at principia softwarica as a
+> reference.
+
+Said 2026-11-16, while ruling on the diff viewer ("Keep the diff compiled in
+and do the changes that it asks for pardes as a library"). The diff survey
+had found three diff decisions hard-coded in Look and the pager that are
+plumbing with no general form, because pardes's `Plumb` word has no
+`matches` test and cannot start anything (.scratch/sketch/reports/diff-module.md
+§3 row 12, §5 M3). The coordinator's ruling: the three hooks become default
+plumbing rules when the plumber lands (PLAN.md §7 Dv).
+
+This is round 1 of a design discussion. It is written to be committed as
+`docs/next-plumber.md`, and an implementation agent follows it. Nothing was
+built or run: every number below is a count from reading or an estimate. Plan
+9 paths are under `~/05-genizah/principia-softwarica` unless they say
+`plan9port/` (`~/05-genizah/plan9port`). pardes paths are the working copy,
+including the user's uncommitted edits.
+
+## 0. Summary
+
+- **What Plan 9's plumber is.** A small language-driven file server. A message
+ is six header lines (src, dst, wdir, type, attr, ndata) and then the data. The
+ rules are blank-line-separated rule sets of `object verb args` lines, and the
+ first rule set whose patterns all hold takes the message. Its actions are
+ `plumb to <port>`, `plumb start <cmd>` and `plumb client <cmd>`. The files are
+ `send`, `rules` and one file per port.
+- **What acme does with it.** acme asks the plumber first. A write that fails
+ means no rule matched, and acme then does its own look, which opens a file or
+ searches for the word (plan9port acme/look.c:147-223). acme reads the `edit`
+ port itself: it opens a file at an `addr`, or shows the data when
+ `action=showdata` (acme.c:556-564).
+- **What pardes has.** A one-line `Plumb` word with four tests and three ports
+ (look.zig:155-261). Its rules sit in the middle of `resolve`, which also
+ hard-codes four other decisions:
+ - http(s) URLs (look.zig:263-265, :1601);
+ - a bare `.diff`/`.patch` stacked in a +Diff (:1622-1633);
+ - a commit hash run through `git show` (:1092, :1118-1143);
+ - a diff paged into a +Pager restacked (ninep/ctl.zig:721-731).
+
+ No user rule exists today: the user's init has no `Plumb` line. Two tests pin
+ the word: look.zig:2688 and test/behaviour/addons.zig:188.
+- **The design.**
+ - `src/Plumb.zig` owns the rules as text, which is replicated and dumped core
+ state, plus the ports this session has named.
+ - Its matcher is a pure function of the rules and a message. The exceptions
+ are `isfile`/`isdir`, which resolve a name exactly as Look does, through
+ taped `.resolve` sites.
+ - `matches` uses mvzr through regexp.zig, with no engine work. The price is
+ `$0` but no `$1`–`$9`, because mvzr has no capture groups.
+ - pardes reads three kinds of port itself, as acme reads `edit`: `edit` (Look's
+ open), `web` (the host's link opener) and every loaded kind by its name.
+ Other ports are 9P files that external programs read, with the tree's held
+ reads.
+ - `plumb start` runs the expanded line as pardes's exec runs a line from the
+ message's pane, so a builtin such as `Diff $file` runs in place.
+ - The files are `plumb/send`, `plumb/rules` and `plumb/<port>`, in Plan 9's
+ text form and with Plan 9's error words.
+- **Look after it.** The pane-context readings stay first: History, Recent, a
+ diff line, a command word, `file:/re/`, and a name already open in a pane.
+ Then the plumber runs. If it takes nothing, pardes's own look runs on the
+ target it already resolved. The default rule file (§5.2) reproduces today's
+ behaviour, and the three diff hooks and the URL become rules. `Diff` gains an
+ argument (a file or a revision) and a way to decline silently, which is what
+ keeps the fallback byte-identical.
+- **Size.** About 600 lines of new code and 400 lines of tests. look.zig loses
+ about 150 lines.
+- **Phases.**
+ 1. The language and the files.
+ 2. Look sends to the plumber.
+ 3. External ports.
+ 4. The pager as a sender.
+
+ Deferred: the click attribute, the hover asking the matcher, and
+ `pardes plumb`.
+- **Four taste questions** (§8):
+ 1. submatches;
+ 2. whether an open pane comes before the rules;
+ 3. the `Plumb` word's form;
+ 4. whether `start` of a program is a command pane or detached.
+
+## 1. What Plan 9's plumber is
+
+### 1.1 The message
+
+- **Six lines of header, then the data.** The lines are src, dst, wdir, type,
+ attr and ndata, followed by ndata bytes of data with no terminating newline
+ (include/ipc/plumb.h:5-28; plumb.ms:223-263).
+ - Any header line may be empty except ndata.
+ - Only `type=text` is supported (plumb(6), ROOT/docs/man/6/plumb:49-59).
+- **attr** is `name=value` pairs separated by blanks.
+ - A value holding a blank, a quote, `=` or a tab is quoted rc-style: `'…'`,
+ with `''` for a quote (libplumb/mesg.c:76-103 quote, :260-338
+ plumbunpackattr).
+ - A value cannot hold a newline.
+- **Packing and unpacking** are plumbpack (mesg.c:157-193) and
+ plumbunpackpartial (:382-432).
+ - Unpacking tells "not yet complete" (`*morep` bytes still to come) apart from
+ "malformed".
+ - That is how the plumber assembles a message written in pieces
+ (fsys.c:858-887).
+
+### 1.2 The rules language
+
+Taken from rules.c and match.c, which are authoritative where the man page
+differs.
+
+- **Lines.**
+ - `#` starts a comment, which counts as a blank line.
+ - A blank line ends a rule set.
+ - `include file` substitutes a file: an absolute path, `./` or `../`, else the
+ plumber's directory, then `/lib/plumb` (principia patched this from
+ `/sys/lib/plumb`). It is limited to depth 10 (rules.c:89-112, :398-432).
+ - `name=value` defines a variable, one per line (:376-396).
+- **A rule line** is `object verb arg…`.
+ - The objects are `arg attr data dst plumb src type wdir`. `kind` is an old
+ spelling of `type` (rules.c:46-57, :474-480).
+ - The verbs are `add client delete is isdir isfile matches set start to`
+ (:59-72).
+- **Parse checks** (rules.c:348-374, :531-613):
+ - `plumb` takes only `to`, `start` and `client`, and only `plumb` takes them.
+ - `add` and `delete` take only `attr`.
+ - A rule set needs patterns and actions, with at most one `start` or `client`
+ and at most one `to`.
+ - A rule set of nothing but `plumb to X` lines declares ports.
+ - The port names `.`, `..` and `send` are illegal.
+- **Arguments are expanded twice.**
+ - At parse time, with the variables only (`qarg`). A `matches` regex is
+ compiled then, so `'$addr'` in a pattern is the macro (rules.c:351, :364-366).
+ - At match time, with the message's variables too.
+ - Expansion is rc quoting: `'…'` is literal, `''` is a quote, and `$` outside
+ quotes is a variable (rules.c:294-336).
+- **The variables** (rules.c:249-292):
+ - `$0`–`$9`: the last `data matches` and its parenthesised submatches;
+ - `$src`, `$dst`, `$type`, `$wdir`, `$data`;
+ - `$attr`: the packed attributes;
+ - `$file` and `$dir`: what `isfile`/`isdir` found. Without one they are data
+ joined to wdir (filename, :228-247).
+ - An unknown `$x` stays as written (:322-325).
+- **Patterns run in order, and a rewrite is permanent even if a later pattern
+ fails** (plumb(6) :140-145; match.c:366-386 mutates the message in place).
+- **Each verb:**
+ - `is`: string equality on data, dst, type, wdir or src (match.c:17-36).
+ - `isfile`/`isdir`: the expanded arg (or data, or wdir) is made absolute in
+ wdir and cleaned (not realpath'd), then stat'd. Success sets `$file`/`$dir`
+ (match.c:131-189, absolute :149-159).
+ - `set`: replaces data, dst, type, wdir or src. A `data set` clears the click
+ span (:191-231).
+ - `add`: appends attributes (:233-245).
+ - `delete`: removes an attribute. **The code fails the pattern when the
+ attribute is absent** (:247-264). The man page says it matches anyway
+ (plumb(6) :155-161). pardes follows the code.
+- **`matches`** (match.c:75-129):
+ - Without a `click` attribute, the regex must match the **whole** object
+ (:119-126).
+ - With `click=N` on data, the plumber tries the regex from each offset 0..N.
+ The first match that contains offset N wins, where N counts runes
+ (clickmatch, :55-73).
+ - Every `data matches` in the rule set must then match that same span
+ (:99-100). The data is cut to that span and the click attribute removed when
+ the set matches (rewrite, :318-344).
+ - This is Pike's two-patterns trick: one pattern finds the run of file
+ characters, the next checks its suffix, so `horse.gift` is no `.gif`
+ (plumb.ms:444-514).
+ - Plan 9's regexp is leftmost-longest (plumb.ms:481).
+- **First match wins**, then dispose (fsys.c:892-902):
+ - A message that names a dst only tries rule sets whose `to` names that port
+ (match.c:372-373). A set without `to` still tries.
+ - A matching set with `to` sets dst when dst was empty (:380-383).
+ - No set matches: a message that names a dst goes there unchanged. Anything
+ else is the write error `no matching plumb rule`.
+- **Dispose** (fsys.c:524-556, startup match.c:438-463):
+ - dst empty: run the `start`/`client` command, or fail `couldn't find
+ destination for message`.
+ - dst is a port with readers: queue the message to each of them (fan-out).
+ - dst is a port with no reader: run `start`, which discards the message, or
+ `client`, which holds it until the port is opened. Otherwise fail `no start
+ action for plumb message`.
+- **`start` and `client`** split the expanded arguments into argv and **exec
+ them directly, with no shell**, stdin `/dev/null`, falling back to `/bin/x`
+ (match.c:346-364, :419-436). Rules that need a pipe say `rc -c '…'`
+ (ROOT/lib/plumb/basic:13, :95). The man page's "a shell program" (plumb(6)
+ :254-260) is loose.
+
+### 1.3 The files
+
+- **The directory** is `rules` (0600), `send` (0200) and one file per port
+ (0400), each port created the first time a rule names it. Ports are never
+ deleted (fsys.c:94-99, :161-182; plumber(4) :85-101). At most 50 entries
+ (NDIR).
+- **`send`**: a write is a message, assembled across writes (fsys.c:858-887). It
+ is answered once the message is matched and queued, so the sender never
+ waits on the reader (plumb.ms:724-760). An error comes back as the write's
+ error string.
+- **A port**: opening it makes the opener a reader. A message goes to every fid
+ open when it was sent (queuesend, fsys.c:337-362).
+ - A read blocks until a message arrives, and a message may take several reads
+ (drainqueue, :377-436).
+ - A flush cancels a held read (:439-459).
+ - A clunk drops what that fid had not read (:462-491).
+ - Messages held for a `client` go to the first opener (queueheld on open,
+ :510-522, :754).
+- **`rules`**:
+ - A read gives the parsed rules printed back: variables, port declarations,
+ then each set as `obj\tverb\targ` (printrules, rules.c:695-710).
+ - A write appends. Complete rule sets, as judged by a blank line, are parsed
+ at each write and the rest at close, and a parse error is that write's
+ error (morerules :722-760, writerules :762-784, fsysclunk :943-952).
+ - An `OTRUNC` open clears the rules (fsys.c:707-711, :742-745). There is one
+ writer at a time (`file already open`, :732-741).
+- **Startup.** The plumber reads `$home/lib/plumbing` (plumber.c:60-72), which is
+ usually just `include basic` (ROOT/usr/pad/lib/plumbing; plan9port
+ plumb/initial.plumbing: `editor = acme`, `include basic`).
+
+### 1.4 What acme does around it
+
+Read in plan9port's acme (principia's acme predates the plumber's use).
+
+- **A pane with an event reader comes first.** The look goes to that reader as
+ an `l`/`L` event and is never plumbed (look.c:98-146).
+- **Otherwise acme sends a message** (look.c:147-195):
+ - src is `acme`;
+ - wdir is the window's directory, or acme's own (:152-162);
+ - type is `text`;
+ - the data is the selection when there is one. With no selection it is the
+ whitespace-delimited word around the click, plus `click=<offset>`
+ (:166-182).
+ - A write that succeeds ends the look. A failed write (no rule matched) falls
+ through (:189-194).
+- **acme's own look** opens a file or address (openfile, which also handles
+ directories and acme's `includename` search) or searches the window for the
+ word (:197-223).
+- **acme reads the `edit` port** (plumbthread, look.c:25-72, which reconnects to
+ a restarted plumber). It acts on a message by its `action` attribute
+ (acme.c:556-564):
+ - none or `showfile`: open the file at the message's `addr` attribute
+ (plumblook, look.c:241-271);
+ - `showdata`: a new window holding the data, named by the `filename`
+ attribute or `Untitled-N`, and clean (plumbshow, :273-311).
+
+ `plumb -i` adds `action=showdata` (plumb(1) :69-77). That is how the stock
+ rules show `man` output and `doc2txt` output in the editor (plumb.ms:993-1033;
+ plan9port plumb/basic:139-142).
+- **Plan 9's own limit**: the language cannot look inside files, only at names
+ (plumb.ms:1298-1314).
+
+## 2. What pardes has today, measured
+
+### 2.1 The `Plumb` word
+
+- **Builtin**: builtins.zig:941-978, with session scope. It takes one line,
+ `<test> [word…] to <port>`, checked by look.plumbRuleError (look.zig:160-186).
+- **Tests**: `prefix` (the text starts so), `suffix` (an existing file's
+ resolved path ends so, in any case), `isdir`, `isfile`.
+- **Ports**: `url`, `dir`, `file` or a loaded kind's name (look.zig:158). A port
+ naming a kind that is not loaded is refused.
+- **Forms**: bare lists the rules on the message row; `Plumb -` empties them.
+- **State**: the field `Core.plumb: ArrayList([]u8)` (Core.zig:211-213), which
+ is digested and dumped (it is not in `replica`'s lists, Core.zig:401-418).
+- **Matching**: inside `resolve` (look.zig:227-261). The user's rules come after
+ an `@p` pane address (:214-225) and after resolveLookTarget's open-pane check
+ (:881, :894-897), and before the URL test and the disk.
+- **Who uses it.**
+ - The user's init: none (grep of ~/.config/pardes/init).
+ - Tests: look.zig:2688-2735, and test/behaviour/addons.zig:188-209 (a rule to
+ the image kind).
+ - Docs: reference.typ:1355, guide.typ:177.
+
+### 2.2 Everything Look decides, and which of it is plumbing
+
+lookAt (look.zig:1493-1688) runs these steps in order. The last column says what
+each step is in acme's terms.
+
+| # | decision | code | in acme |
+|---|---|---|---|
+| 1 | a +History row restores a dump | look.zig:1507-1512 | the window's own (an event reader's): **not plumbing** |
+| 2 | a +Recent/+Jumplist row reopens, clamped | :1515-1520 | the window's own: not plumbing |
+| 3 | a whole diff line written over 9P is its address | :1524-1527 (diffLineAddress :1423) | the window's own rows (M4's row address): not plumbing |
+| 4 | a `` @`…` `` command word executes | :1528-1531 | exec: not plumbing |
+| 5 | `~`, `<x>` and a trailing `:` | :1500-1502, :1536-1540 | the sender's expansion (acme's `expand`) |
+| 6 | `file:3:0` refused | :1546 | address syntax: not plumbing |
+| 7 | `file:/re/`, `:addr` | :1547 (addressed :1028; lookAddress :1148) | plumbing in Plan 9 (fileaddr's `$addr`), but evaluated by the editor; stays here (see §5.1) |
+| 8 | `:N` in a kind's pane | :1550-1551 | the window's own |
+| 9 | an `@p<serial>` address | resolve :214-225 | pardes's names: not plumbing |
+| 10 | a name open in a pane, first by path, then joined to each candidate directory | resolveLookTarget :881, :894-897 | acme's `lookfile` inside openfile, after the plumber |
+| 11 | the user's Plumb rules | resolve :227-261 | **plumbing** |
+| 12 | http(s):// opens the browser | resolve :263-265; lookAt :1601 (emits `open_link`, Effect.zig:48, :131-134; the hosts' `look.openLink`, look.zig:39-54, double-fork xdg-open or `open`) | **plumbing** (`plumb to web`, plan9port plumb/basic:18-22) |
+| 13 | a name found in the pane's directory, then the jump list's directories, then Incl's | resolveLookTarget :877-911; fs.resolve fs.zig:341-381 (taped `.resolve`, fs.zig:436-446) | acme's openfile plus includename (its own look) |
+| 14 | a directory opens a listing pane | resolve :268; lookAt :1602-1611 | acme's openfile, not the plumber |
+| 15 | a kind's extension opens that kind | resolve :269; lookAt :1654-1686 | **plumbing** in Plan 9 (`plumb to image`); in pardes, the editor choosing the kind of pane |
+| 16 | a file opens at its line and column | lookAt :1612-1653 | the `edit` port (plumblook) |
+| 17 | **a bare `.diff`/`.patch` opens as a +Diff** | :1622-1633 | **plumbing** |
+| 18 | a `./` name that is not there is a miss | lookUnresolved :1078-1087 | acme's own |
+| 19 | no search in a raw terminal or a kind's pane | :1090 | the window's own |
+| 20 | **a commit hash in a git work tree runs `git show` paged** | :1092, lookCommit :1118-1131, isCommitHash :1133-1143; command_pages panes.zig:173-175, :704-707 | **plumbing** |
+| 21 | a word is searched in its pane, or in a +Search | lookWord :1011-1023; :1093-1110 | acme's search: **not plumbing** |
+| 22 | **a diff paged into a +Pager is restacked** | ninep/ctl.zig:721-731; the sniff File.zig:752 | `plumb -i … action=showdata` arriving at the editor: **plumbing** |
+
+The hover, the n/N walk and lineSpan ask `resolve` what is lookable (look.zig:133-153,
+:622-632). acme underlines nothing, so that is not plumbing. They keep asking
+`resolve` (§7, deferred).
+
+## 3. The plumber as part of the core
+
+### 3.1 Where the rules live
+
+`src/Plumb.zig` is one type file owning its fields, with its tests at its end.
+
+```zig
+//! The plumber (Plan 9's plumber(4), windows/plumb/): the rules, and a
+//! message matched against them and sent where they say.
+text: std.ArrayList(u8) = .empty, // the rules in force, as plumb/rules reads them
+ports: std.ArrayList([]u8) = .empty, // every port a rule named this session, never dropped
+```
+
+- **The rules are stored as their printed text.** The text is what Plan 9's
+ printrules prints, with includes already flattened. It is parsed on every
+ send. Parsing is a few kilobytes of lines and has not been measured.
+- **Why text and not a parsed table.**
+ - Digest, dump and replication are then one byte string; walk.zig needs
+ nothing new.
+ - `plumb/rules` returns the text as is.
+ - No compiled regex is kept: regexp.zig's `Regex` holds a 512-operation mvzr
+ program and 64 sets (regexp.zig:32-33).
+ - An `include` needs a disk read, and that read happens only when rules are
+ written, never when a message is sent.
+- **The field.** `Core.plumber: Plumb` replaces `Core.plumb`. The rename keeps an
+ old dump's `plumb` (a list of strings) from meeting a new type of the same
+ name. How walk.Load treats a field that has gone is not verified;
+ dump.zig:1145 shows a precedent for skipping removed fields.
+- **Bounds.** At most 64 KiB of rule text (Plan 9's whole basic is about 4 KiB),
+ 32 ports (Plan 9's 50, less the fixed files), 32 variables and include depth
+ 10. A write past a bound is refused in words.
+- **How rules change.** Each of these is an input, so a replica replays it or
+ receives it in a dump:
+ - at boot: the user's `plumbing` file if it exists, else `include basic` (§4.3);
+ - a write to `plumb/rules`: a 9P `serve_fs` input on the authority, taped,
+ tape.zig:39;
+ - saving the `plumbing` file in a pane: the same hook as the init file,
+ host_io.zig:3006 → exec.reapplyInitFile. Whether that call is itself taped
+ was not traced.
+
+### 3.2 The matcher, a pure function
+
+```zig
+pub const Msg = struct { src: []const u8, dst: []const u8, wdir: []const u8,
+ type: []const u8, attr: []const u8, data: []const u8 }; // attr in its packed text form
+pub const Verdict = struct { msg: Msg, set: u16, port: ?[]const u8,
+ start: ?[]const u8, client: bool }; // in the step's scratch
+pub fn match(p: *Pardes, id: usize, rules: []const u8, m: Msg) ?Verdict
+```
+
+It follows Plan 9's match.c line for line (§1.2), except:
+
+- **`isfile`/`isdir` resolve a name the way Look does.**
+ - A place written after the name (`:12`, `:12:5`, `:12-14`) is not part of the
+ name; parsePathLine reads it (look.zig:70).
+ - A relative name is tried in wdir, then in the jump list's pane directories,
+ then in Incl's, through the same function resolveLookTarget uses
+ (look.zig:886-909, fs.resolve).
+ - `$file`/`$dir` are the resolved real path, where Plan 9 gives the cleaned
+ join (match.c:149-159).
+ - Both differences keep today's behaviour byte-identical (§5). Each is acme's
+ own look's behaviour moved one step earlier: openfile and includename do
+ this search in acme.
+ - Each stat is a taped `.resolve` site (fs.zig:440). A per-send memo of name
+ to result keeps two rules asking about one name to one syscall.
+- **Determinism.** A replica replaying a unit gets the authority's recorded
+ answers to those sites. A speculating replica is poisoned at the first one and
+ waits a round trip (tape.zig:934-939), as every Look of a file does today. A
+ rule set with no `isfile`/`isdir` (the URL, the hash) never touches a site,
+ so its look speculates fully, as today's URL look does.
+- **Every other verb** is pure string work over the message.
+- **Expansion** has a fixed 4 KiB buffer, Plan 9's `ebuf` (rules.c:36). An
+ expansion past it gives Plan 9's `string-too-long`, and the rule fails. That
+ also keeps a megabyte of paged data out of `$data` (§5.4).
+
+### 3.3 `matches` on mvzr, through regexp.zig's convention
+
+- **No engine work.**
+ - A `matches` with no click compiles `^(` pattern `)$` with regexp.zig's
+ `Regex.compile` (regexp.zig:102) and asks `find` for a match over the
+ object (:371).
+ - Anchoring makes mvzr backtrack into a later alternative when a first one
+ would match short. So whole-match is exact even though mvzr takes the first
+ alternative and not the longest (regexp.zig:22-25).
+ - With `click=N`, the matcher tries `find` from each offset 0..N, as
+ clickmatch does, and N counts runes.
+ - regexp.zig's step budget bounds every call; `TooSlow` counts as no match.
+- **Plan 9 regexp features in the stock rule files, and what mvzr does with
+ them** (ROOT/lib/plumb/basic, plan9port plumb/basic; mvzr's list in
+ zig-pkg/mvzr-0.3.9…/README.md:36-77):
+
+| feature | used in | mvzr through regexp.zig |
+|---|---|---|
+| classes with ranges, `\-` `\.` `\^` escaped in them; `[.$]` | everywhere | yes |
+| `?` `*` `+`, groups, `\|` | everywhere | yes (greedy; first alternative, not longest: harmless under the `^(…)$` anchoring) |
+| `\.`, `\(`, `\)` outside classes | images, man | yes |
+| `.*` | `Local (.*)` (basic:116) | yes (`.` is a byte, or not a newline in a pattern naming `\n`: regexp.zig:9-13) |
+| the rune range `¡-￿` (U+00A1–U+FFFF) | file, image, man classes | **no**: regexp.zig spells non-ASCII ranges out rune by rune and refuses ones wider than 256 (`WideRange`, regexp.zig:78-79). Written instead as an alternation with a high-byte class, `([a-zA-Z0-9_\-./]\|[\x80-\xff])` (UTF-8 is self-synchronising, so a run of these is whole runes). regexp.zig's own rewrite emits high-byte `\x` classes (regexp.zig:300-330); this exact class is not verified |
+| leftmost-longest | clickmatch's choice of span | approximated: the first match from each offset, greedy. A click inside a run of file characters finds that run in every stock rule |
+| `$1`–`$9` submatches | `arg isfile $1`, `attr add addr=$3`, `man $2 $1` | **no**: mvzr has no capture groups (README.md:77). Phase 1 refuses a `$1`–`$9` outside quotes at parse, in words (Q1). The defaults need none (§5.2). |
+| `{m,n}` | nowhere in Plan 9 | mvzr has it (README.md:52): pardes's rules may use it, and the default hash rule does |
+
+### 3.4 Ports
+
+- **One comptime table in Plumb.zig names the ports pardes reads itself.**
+ pardes is always one of their readers, as acme always reads `edit`.
+ - `edit`: opens the data as Look opens a name. It takes a file, a directory or
+ a kind's file by extension, at the place written after it or given as
+ `addr=`. With `action=showdata` it shows the data. With `action=showdiff`
+ it shows the data stacked as a +Diff (§5.4).
+ - From the look that sent the message, in the same step, the handler runs
+ lookAt's final switch on the target Look already resolved. That is no
+ second resolution, and the same code as today.
+ - From anyone else (`plumb/send`), the handler resolves the data itself,
+ joined to the message's wdir when the data is relative.
+ - `web`: the host's link opener (`open_link`, at most 256 bytes as today,
+ look.zig:1601).
+ - every loaded kind by its name (`image`, `pdf`): the file opened in that
+ kind. While the kind is not loaded nobody reads its port, so Plan 9's rules
+ apply: `start`/`client` run, or the send fails and Look falls back to its
+ own look. That is today's "a kind gone since is passed over".
+- **Every other port is a file that external programs read** (§4.1). If a rule
+ names `edit` or `web`, an external reader of it gets a copy too (Plan 9's
+ fan-out). Diverting a message is done with a rule, not by holding the port.
+- **Whether a port has an external reader** is the authority's 9P state.
+ - The matcher asks it through `tape.authority` as a bool, the way mouse.zig
+ asks whether a pane's events are read (mouse.zig:1024-1044).
+ - A speculation guesses the last answer, and the unit confirms it or rolls it
+ back (tape.zig:884-901).
+ - Queues live in `p.fs`, which is authority-only (Core.zig:416). A push to a
+ port with no opens does nothing, as events.noteAction returns when nobody
+ reads (ninep/events.zig:602-611).
+
+### 3.5 `plumb start`, and a compiled-in word as what is started
+
+- **What it runs.** `plumb start <args>` expands its arguments (§1.2) and runs
+ them as pardes's exec runs a line from the message's pane, `exec.execute`
+ (exec.zig:651-722):
+ - A builtin or a kind's word runs in place, through executeBuiltinLine
+ (exec.zig:870-906). So `plumb start Diff $file` runs the compiled-in
+ stacker.
+ - Any other line is a command pane in the message's wdir. That is the pane's
+ directory for a look. For a `plumb/send` with another wdir, runCommand takes
+ an override field, as it takes `exec_column` (exec.zig:752).
+ - Each expanded word goes to `$SHELL -c` single-quoted, so a word stays one
+ argument whatever it holds. This is Plan 9's argv exec (match.c:346-364)
+ spoken to pardes's exec, which runs lines through a shell. A rule that wants
+ a pipe writes `plumb start sh -c '…'`, as Plan 9's write `rc -c '…'`.
+ - Plan 9's start is detached and windowless, and Q4 asks whether to keep that.
+ pardes's exec is already acme's, and nothing in the defaults starts a
+ program.
+- **A started word may decline.**
+ - `Ctx` gains `plumbed: bool`. A word started by the plumber that cannot do
+ what the message asks (Diff on a file with no hunk, Diff on a revision
+ outside a git work tree) sets `p.plumb_declined` and says nothing.
+ - The plumber then fails the send. Look falls back to its own look, as acme
+ does when the plumber's write fails (§1.4).
+ - Any other failure of a started word is the word's, said as usual. Plan 9's
+ sender never hears of a start that fails later.
+- **`Diff` gains an argument** (builtins.zig:1092-1103):
+ - `Diff <file>` stacks that file's hunks. It reads the file at a taped
+ `.read_file` site and calls Output.openDiff (Output.zig:491), which is
+ today's look.zig:1627-1631 moved.
+ - `Diff <rev>` (7 to 40 lowercase hex digits with a letter and a digit, the
+ old isCommitHash) finds `.git` above the pane's directory and runs
+ `git show <rev>` paged: lookCommit, look.zig:1118-1131, moved whole with its
+ `command_pages`.
+ - Bare `Diff` is as today.
+ - A diff pane is needed only when Diff is bare: the `needs` check at
+ exec.zig:985 applies to the bare form.
+- **`plumb client <cmd>`** is `start` plus a hold. The message waits, bounded,
+ in the port's hold list and goes to the port's first opener (Plan 9's
+ queueheld). Rules in the defaults never use it. Two uses it gives:
+ - a helper started on demand;
+ - `plumb client Addon load image`, holding the message until the kind
+ registers and pardes starts reading its port.
+
+## 4. The surface
+
+### 4.1 The 9P files
+
+`plumb/` is a new top directory. It needs `TopFile.plumb` (tree.zig:230-289; the
+u5 enum has 6 values free) and a third node family beside panes and columns for
+the ports, with a bit as `col_bit` has (tree.zig:367).
+
+| file | mode | read | write |
+|---|---|---|---|
+| `plumb/rules` | 0666 | the rules in force: variables, port declarations, rule sets, as printrules prints them | appends rule text. Complete sets (ended by a blank line) are parsed at each write, the rest at release. A parse error fails that write with the line number and Plan 9's words. An open with OTRUNC (`> plumb/rules`) clears the rules first. One writer at a time: `file in use` (tree.zig:62) |
+| `plumb/send` | 0222 | — | a message in the text form of §1.1, assembled across writes. Answered when it is matched and disposed. The error words are Plan 9's: `bad plumb message format`, `no matching plumb rule`, `couldn't find destination for message`, `no start action for plumb message`, `no port for "client" rule`, `empty argument list` (fsys.c:147-156, match.c:450-460) |
+| `plumb/<port>` | 0444 | one message a read, packed. A short read takes the front of a message and the next read the rest, as the event file does (events.zig:104-115). A read with nothing waiting is held (`.again`, Open.held, tree.zig:165-172). Messages sent before the open are not this open's; a release drops what the open did not read | — |
+
+- **Opens.** A port open is an `Open.what` of its own holding a bounded queue: an
+ `events.Queue`, 64 KiB, oldest dropped (events.zig:21-60). A message bigger
+ than the queue is not delivered to that reader, and the log gets an `err`
+ saying so.
+- **readdir order** is Plan 9's: `rules`, `send`, then the ports in the order
+ rules named them.
+- **Reserved port names**: `.`, `..` and `send` (Plan 9's badports,
+ rules.c:38-44), plus `rules`, which Plan 9 forgets.
+- **Wake-ups.** `plumb/send` and `plumb/rules` writes go through `needsQuiet`, as
+ every write does (tree.zig:82-90). A held port read is answered by the
+ listener when `p.fs.news` is set, as event reads are.
+
+### 4.2 The `Plumb` word
+
+The one-line form is replaced.
+
+- **Bare `Plumb`** opens the user's `plumbing` file in the configuration
+ directory, beside `init`, as `Config` opens init (builtins.zig:1338-1360).
+ - If the file is not there yet, the pane holds `include basic`, which Save
+ makes. That is plan9port's initial.plumbing, less the editor variable.
+ - Saving the file replaces the rules, through the same hook that applies a
+ saved init (host_io.zig:3006). It is `cp lib/plumbing /mnt/plumb/rules`
+ done for you (plumb.ms:784-787). A parse error is said with its line, and
+ the rules stay as they were.
+- **`Plumb <anything>`** is refused in words: "Plumb takes no rule now: rules are
+ plumb(6) rule sets, in <config>/plumbing (Plumb opens it) or written to
+ plumb/rules". An old init line `Plumb suffix .svg to image` is said the same
+ way, as an init line that fails is (exec.zig:941-954). The user's init has
+ none. Q3 asks whether a one-line form stays.
+- **Converting an old rule by hand.** `suffix .svg to image` becomes:
+
+```
+type is text
+data matches '.*\.([sS][vV][gG])'
+arg isfile $data
+plumb to image
+```
+
+### 4.3 Where the default rules live
+
+- **Location.** `src/plumbing`, the default rules file, compiled in with
+ `@embedFile`. `include basic` names it, as Plan 9's `include basic` names
+ `/lib/plumb/basic`.
+- **Other includes.** Any other relative include is read from the configuration
+ directory, and an absolute one from where it says. Both are taped `.read_file`
+ sites, read only when rules are written.
+- **Boot.** pardes reads `<config>/plumbing` the way it reads init: main.zig
+ puts it in Options beside `startup_config` (main.zig:725-728). Without the
+ file, the rules are `include basic`, so `Pardes.init` in every test has the
+ defaults.
+- **Where it is shown.**
+ - `plumb/rules`;
+ - the `Plumb` pane (after `include basic`, the flattened rules are in
+ `plumb/rules`);
+ - the reference, which quotes `src/plumbing` whole (§6).
+
+## 5. Look after the plumber
+
+### 5.1 The order
+
+1. **The pane's own readings**, unchanged:
+ - an event reader takes the look first (mouse.zig:1034, acme's look.c:98);
+ - History, Recent, a diff line, a command word (§2.2 rows 1-4);
+ - the sender's expansion (row 5);
+ - the zero column (row 6);
+ - `file:/re/` and `:addr` (rows 7-8). lookAddress calls lookAt on the path,
+ which plumbs it, so `x.diff:/re/` behaves as today.
+2. **resolveLookTarget** as today, minus the user's rules (row 11), which are
+ gone from `resolve`. A `.pane` result (a name open in a pane, or `@p`) is
+ focused as today and never plumbed. This is not acme's order (Q2).
+3. **The plumber**, with this message:
+ - `src`: `pardes`; `term` when the look came from a terminal in raw mode and
+ not over 9P (the condition at look.zig:1090); the kind's name in a kind's
+ pane;
+ - `dst`: empty;
+ - `wdir`: Pardes.paneDir;
+ - `type`: `text`;
+ - `attr`: empty, so no click in phase 2 (§7);
+ - `data`: the trimmed name reading (look.zig:1540).
+
+ Skipped when `p.look_text` is set. That flag now means "a look that opens as
+ text, unplumbed": showDiffText and Edit's `B` (Output.zig:532,
+ edit_cmd.zig:100).
+4. **If the send failed**, lookAt's switch runs on the target from step 2, as
+ today, minus the hooks that became rules:
+ - the `.url` arm becomes lookUnresolved, since acme's own look opens no URL;
+ - the `.diff` hook goes from the `.file` arm;
+ - lookCommit goes from lookUnresolved.
+
+### 5.2 The default rule file (`src/plumbing`), in full
+
+```
+# pardes's plumbing rules, in plumb(6)'s language. The first rule set
+# whose patterns all hold takes the message; one that none takes is
+# Look's own (a file or directory opened, else the word searched for).
+# A look sends what it looks at: type text, src pardes (term from a
+# terminal's raw mode, a kind's name from its pane), wdir its pane's
+# directory, data the name as Look reads it.
+
+# urls go to the web browser (the host's: xdg-open, open on macOS)
+type is text
+data matches 'https?://.*'
+plumb to web
+
+# a diff or patch looked at bare is stacked in a +Diff; one with no
+# hunk in it opens as text
+type is text
+data matches '.*\.(diff|patch)'
+arg isfile $data
+plumb start Diff $file
+
+# existing directories, and existing files at the place written after
+# them, go to the editor; a file a kind shows (a picture, a PDF) to
+# that kind
+type is text
+arg isdir $data
+plumb to edit
+
+type is text
+arg isfile $data
+plumb to edit
+
+# a commit hash looked at in the editor, in a git work tree: git show,
+# stacked in a +Diff (outside one, Diff declines and the word is
+# searched for)
+type is text
+src is pardes
+data matches '[0-9a-f]{7,40}'
+data matches '[0-9a-f]*[0-9][0-9a-f]*'
+data matches '[0-9a-f]*[a-f][0-9a-f]*'
+plumb start Diff $0
+
+# a diff paged (git show, git log -p) is shown stacked in a +Diff in
+# its +Pager's place
+type is text/x-diff
+attr delete action
+attr add action=showdiff
+plumb to edit
+```
+
+**Why each rule matches today's code byte for byte:**
+
+- **web.** Today it is `startsWith(trimmed, "http://" | "https://")`
+ (look.zig:263-265). The rule is a whole match of `https?://.*` over the same
+ `trimmed`. It runs after the open-pane check, as today's URL test does, and
+ needs no disk site, so a replica speculates it fully as today. The handler
+ keeps the 256-byte cap.
+- **diff/patch.** Today the hook is: target `.file`, no line given, not
+ `look_text`, and the path ends in `.diff` or `.patch` (look.zig:1625-1626).
+ - In the rule: a data that ends so and has no `:N` (the whole match fails on
+ `x.diff:12`); isfile, which is a file and not a directory, found where Look
+ finds it; `look_text` skips the plumber; and an open pane was focused
+ already in step 2.
+ - No hunk: Diff declines (§3.5), so Look opens the file as text, which is
+ today's fall-through (:1632).
+ - **One difference**: a symlink not named `.diff` that resolves to a `.diff`
+ file is stacked today (the test is on the resolved path) and opens as text
+ after. Plan 9 cannot test `$file` by pattern without a permanent
+ `data set`. Accepted.
+- **edit, two sets.** They make the hash rule come after file and directory
+ resolution, as lookCommit came after it (look.zig:1092 is inside
+ lookUnresolved). The handler is today's switch on today's target.
+- **hash.** Today: the whole `trimmed` is 7-40 lowercase hex with a digit and a
+ letter (isCommitHash), the pane is no kind's and not in raw mode
+ (look.zig:1090), `.git` is above the pane's directory, and git show runs from
+ that pane.
+ - The rule tests the same, with `src is pardes` covering the pane test.
+ - `Diff <rev>` does the `.git` walk, the exec and the paging exactly as
+ lookCommit did.
+ - Outside a work tree, Diff declines, so Look's search runs as today.
+- **paged diff.** The pager's send (§5.4) carries `type text/x-diff` exactly when
+ File.looksLikeDiff said so (File.zig:752: today's `pager_diff`). The edit
+ port's `showdiff` is today's restack code (ctl.zig:724-730) moved.
+ - The code's `attr delete` fails when the attribute is absent (match.c:258),
+ and the pager always sets `action`.
+ - Without this rule, the explicit dst `edit` delivers the message unchanged
+ and the +Pager stays as text.
+
+**What is deliberately not a rule:** directories in Plan 9's sense (acme's
+openfile handles them, and so does pardes's `edit`), kinds by extension (the
+`edit` port's choice of pane, so that today's `Addon load` of a new kind needs
+no rule), Incl, `@p`, addresses, and the search.
+
+### 5.3 What changes for a user
+
+- **Rules now see a look before any of pardes's own decisions** except steps 1
+ and 2. Today the user's rules came after the `@p` and open-pane checks too,
+ so that part is unchanged.
+- **A rule to a port no one reads is no longer refused at write.** Plan 9 never
+ refuses it (test/behaviour/addons.zig:199-200 changes).
+- **The hover, the n/N walk and the lookable span** no longer see the user's
+ rules. Today they did, through `resolve` (look.zig:133-153, :227). That is
+ deferred (§7). No user rule exists.
+
+### 5.4 The pager as a sender (acme's `plumb -i … action=showdata`)
+
+- **Today.** `pardes -` writes a directory to `/pager`, which makes the +Pager,
+ and then the text. fillPager fills the pane and, for a diff, stacks it and
+ closes the +Pager (ctl.zig:705-731).
+- **After.** fillPager fills the pane as today, then sends:
+ - `src pager`;
+ - `dst edit`;
+ - `wdir` the +Pager's directory;
+ - `type text/x-diff` when the text is a diff, else `text`;
+ - `attr action=showdata filename=<the +Pager's path>`;
+ - the text as data.
+- **The `edit` port's actions.**
+ - `showdata`: nothing more, since the +Pager is shown.
+ - `showdiff`: today's restack. It opens a +Diff from the pane `filename`
+ names, closes the +Pager and keeps the keyboard where it was.
+- **The look rules do not see this message.** They all say `type is text`, and
+ an expansion of `$data` past 4 KiB fails (§3.2).
+- **External readers of `plumb/edit`** get the paged text when it fits their
+ queue.
+
+## 6. One definition, several sinks
+
+| the one definition | its sinks |
+|---|---|
+| `src/plumbing` (embedded) | `include basic`; the boot rules; the reference's plumber section, which quotes the file. Typst reading `src/` from docs/typ is not verified; otherwise build.zig copies it next to the generated builtins JSON |
+| `Plumb.text` (the rules in force) | `plumb/rules`; the `Plumb` pane's file after a save; a dump |
+| Plumb.zig's table of pardes's own ports, each with a line saying what it does | `plumb/` readdir (with the ports rules named); the reference's port table; fs-help.txt's `plumb/` line (one line, as every directory has there, src/fs-help.txt:20-23) |
+| Plumb.zig's error words (Plan 9's) | `plumb/send` and `plumb/rules` write errors; the `Plumb` pane's save error; the reference |
+| the message's text form (one pack, one unpack in Plumb.zig) | `plumb/send`, the ports, a later `pardes plumb [-s src] [-d dst] [-w wdir] [-t type] [-a attr] -i \| data…` (plumb(1); PLAN.md §7 C+L's `fs write` over the tree) |
+
+## 7. Phases
+
+Each phase lands alone. Sizes are estimates from reading, as lines of code plus
+lines of tests.
+
+**Phase 1: the language and the files.** About 450 + 300.
+- What it builds:
+ - Plumb.zig: pack and unpack; parse, print, variables and include; expand;
+ match, including click; dispose to `start` and to pardes's own ports;
+ - `src/plumbing`;
+ - `plumb/rules` and `plumb/send` in the tree;
+ - the field `Core.plumber`.
+- Nothing calls the plumber from Look yet. External ports answer `no such plumb
+ port` on open.
+- **Gates.** Tests at the end of Plumb.zig:
+ - every parse error in Plan 9's words;
+ - a print/parse round trip;
+ - plan9port's basic, with its `¡-￿` classes rewritten and its `$1`/`$3` rule
+ sets dropped, parses;
+ - whole match and click match, each with Plan 9's `horse.gift` case;
+ - rc quoting;
+ - `attr delete` of an absent attribute fails;
+ - dst/port filtering;
+ - a dump keeps the rules.
+- One T1 behaviour test writes `plumb/rules` and reads it back, then sends a
+ message to `web` and sees `open_link` recorded (`p.fallback.setLink`,
+ host_io.zig:314).
+- Known base failures as RULES.md lists them.
+
+**Phase 2: Look sends.** About 120 + 100. look.zig loses about 150 lines:
+- Port, plumbRuleError, plumbTarget, the rules block, lookCommit,
+ isCommitHash and the `.diff` hook go;
+- the sender comes in.
+- What else changes:
+ - Diff takes an argument and declines;
+ - `Plumb` is rewritten as in §4.2;
+ - the hover keeps `resolve`.
+- **Gates**, all unchanged byte for byte:
+ - look.zig's 28 tests, with the Plumb test at :2688 rewritten onto
+ `plumb/rules`;
+ - hunks.zig:718 (`.patch` look, Diff to text and back) and :808 (pagers by
+ commit);
+ - test/behaviour/look_and_exec.zig (36 tests), addresses.zig (7), mouse.zig,
+ event.zig;
+ - addons.zig:188, rewritten to a rule in plumb/rules: same panes;
+ - process goldens look-center, look-file, look-file-1col, lookloaded,
+ lookpanes, lookrange, diffview, dirpane (test/process/tty_editing.zig),
+ ttylook and look-fd-deep (tty_terminals.zig), pagercolor (tty_themes.zig).
+- New tests:
+ - a hash looked at inside and outside a git work tree, so lookCommit's path
+ gets the end-to-end test it never had;
+ - a URL with the web rule removed is searched for.
+- **Replica gate** (this step changes which sites a look reads):
+ - test/replicas.zig gains a look at a `.patch`, at a URL and at a hash on the
+ authority, with digests equal. These are diff-module.md R2.1's missing
+ cases (a)-(c).
+ - A speculated URL look is confirmed with no rollback.
+ - The real-use soak, tty and window, local and on the box, as
+ replica-soak-gate asks.
+
+**Phase 3: external ports.** About 120 + 80.
+- What it builds:
+ - per-open queues, held reads, fan-out, `client` holds;
+ - the `tape.authority` question "is this port read".
+- **Gates:**
+ - a T1 test with two opens of `plumb/edit` sees one look's message each, an
+ open made after the send sees none, and a `client` message reaches the
+ first opener;
+ - monkey9p.zig gains the `plumb/` files;
+ - a replica speculating a look whose rule names an external port is
+ confirmed.
+
+**Phase 4: the pager sends.** About 40 + 30.
+- What it builds: fillPager's send, and the `edit` port's `showdata`/`showdiff`.
+- **Gates:**
+ - pagercolor;
+ - hunks.zig:808;
+ - a test that removes the paged-diff rule and keeps the +Pager;
+ - a soak task paging `git show`, which is diff-module.md R2.1 (c).
+
+**Deferred, and why:**
+- **The click attribute from Look** (acme's whitespace-delimited word plus
+ `click`). Look's own expansion (config.isFileChar, look.zig:318-325) would
+ give way to the rules' `matches`, and every click golden would move. Plan 9
+ fidelity says yes one day. Byte-identity says not with the plumber's first
+ landing. `plumb/send` honours `click` from phase 1, for external senders.
+- **The hover asking the matcher**, as a dry run without dispose. It would put a
+ rule set's regexes in the per-frame hover path; measure first.
+- **`$1`–`$9`**, unless Q1 decides otherwise.
+- **`pardes plumb`** and `pardes -` as `plumb -i -d edit`. These wait for the
+ CLI work (PLAN.md §7 C+L).
+- **Types other than text.** Plan 9 never did them (plumb(6) :49-51).
+
+## 8. Questions only the user can answer, and what was decided
+
+Decided 2026-11-17 by the coordinator, the user asked where marked:
+
+1. **Submatches: (a).** `$1`–`$9` are refused in words at parse: the regex
+ library has no capture groups, and the user's standing rule is never to
+ write or vendor a regex engine. Rules use `$0` and several `matches`. The
+ user has been asked whether they want more.
+2. **An open pane first: (a).** A name already open in a pane is focused
+ before the rules run, as today, so every existing look test and golden
+ stays byte-identical.
+3. **The `Plumb` word: (a).** Bare, it opens `<config>/plumbing` as `Config`
+ opens the init; Save applies it; an argument is refused in words. Without
+ that file the rules are `include basic`, the embedded `src/plumbing`.
+4. **`plumb start` of a program: (a).** It runs as pardes's exec does: a
+ builtin in place, a command as a command does today. The user has been
+ asked whether a started program should run detached with no pane, as Plan
+ 9's does; the place where that is decided is one spot (Plumb.zig's
+ `start`).
+
+The options as round 1 put them:
+
+
+1. **Submatches (`$1`–`$9`).** mvzr has no capture groups, and writing a regex
+ engine is ruled out.
+ - (a) **Refuse them in words, and write rules with `$0`, several `matches`
+ and isfile reading a name past its address.** Shell splitting is the
+ escape hatch: `plumb start sh -c '…' $0`. The defaults need nothing more.
+ *Leaning (a).*
+ - (b) Recover top-level groups by testing candidate splits with anchored
+ whole matches of each group's sub-pattern. That is about 100 lines and no
+ engine, but the spans are approximate where Plan 9's leftmost-longest
+ would choose otherwise. More of plan9port's basic would paste in as is.
+2. **Does a name open in a pane come before the rules?**
+ - (a) **Yes, as today and as today's `Plumb` rules see it.** A `.diff`
+ already open as text is focused, not restacked. *Leaning (a): byte-identity,
+ and acme has only one window per file to find anyway.*
+ - (b) acme's order: the rules first, and the `edit` port finds the open
+ pane. A user rule then wins over an open pane, and looking again at an open
+ `.diff` stacks it again.
+3. **The `Plumb` word.**
+ - (a) **Bare `Plumb` opens `<config>/plumbing`, Save applies it, and an
+ argument is refused.** *Leaning (a): Plan 9 keeps rules in a file, and a
+ rule set is several lines.*
+ - (b) Also keep a one-line `Plumb <rule set>` for tags and init, its lines
+ separated by `;`. But `;` is in Plan 9's `$addr` regexes, so this needs an
+ escape.
+ - (c) Remove the word, so rules live only in the file and in `plumb/rules`.
+4. **`plumb start` of a program.**
+ - (a) **A command pane in wdir, as pardes's exec.** Its output and exit
+ status show, and the defaults start only words. *Leaning (a).*
+ - (b) Plan 9's: a detached child, with no pane, stdin `/dev/null`, and output
+ discarded or logged as an `err`. That is closer to plan9port's rules (`web
+ $0`, `9 page $file`), at the cost of a host effect generalising
+ `open_link`.
+
+## Not verified
+
+- **Nothing was built or run.** All sizes are estimates, and the test counts are
+ greps.
+- **mvzr.**
+ - Whether one mvzr class may mix ASCII and high bytes, and that
+ `[\x80-\xff]` compiles. regexp.zig emits similar `\x` classes; this one was
+ not tried.
+ - The cost of compiling the rules' regexes on every send, and the size of a
+ compiled `Regex`.
+- **Dumps and boot.**
+ - How walk.Load treats the removed `plumb` field of an old dump.
+ - Whether the init-file reapply call at host_io.zig:3006 is a taped input.
+ - Whether Typst can read `src/plumbing` from docs/typ.
+- **Replicas.** That a replica's pushes to its own `p.fs` port queues are
+ harmless. That is assumed from events.noteAction's pattern; replica.zig was
+ not read for it.
+- **Behaviour** read in the code but never run:
+ - git paging into a +Pager under `command_pages` (host_io.zig:2103-2107);
+ - the exec `needs` check for Diff with an argument (exec.zig:985).
+- **Sources.**
+ - plan9port's acme was read for acme's side (look.c, acme.c). principia's
+ acme (editors/acme) was not, nor libplumb's event.c or plumb.c.
+ - The `¡-￿` range in the principia rule files was read through `cat`, as
+ UTF-8.
+- **The symlinked-`.diff` difference** (§5.2) is the only behaviour difference
+ found. Others may exist in paths no test covers.