From 797e1b05324a8de7217b7e483496f44c1e7bcdbd Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 00:22:38 -0300 Subject: docs/next-plumber.md: the plumber in pardes's core, the design record of 2026-11-16: Plan 9's plumber and acme's use of it read from the sources (the message, the rules language, the files, the order acme asks it in), what pardes's Look decides today and which of it is plumbing, the design (Plumb.zig owning the rules as their text, a pure matcher over the existing regex convention with isfile and isdir at the taped resolve sites, pardes reading its own ports as acme reads edit, plumb start as pardes's exec), the files, Look after the plumber with the default rule file in full, the phases and their gates; the four questions decided: submatches refused in words, an open pane first, the Plumb word opening /plumbing, start as exec Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- docs/next-plumber.md | 896 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 896 insertions(+) create mode 100644 docs/next-plumber.md (limited to 'docs') 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 `, `plumb start ` and `plumb client `. 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/`, 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=` + (: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, + ` [word…] to `, 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 | `~`, `` 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` 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 ` 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 ` 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 ` (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 ` 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 `** 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/` | 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 `** is refused in words: "Plumb takes no rule now: rules are + plumb(6) rule sets, in /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 `/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 ` 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 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 `/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 `/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 ` 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. -- cgit v1.3