diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 02:31:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | f749eb712d990a9b03f1db372d5311e77bd32edd (patch) | |
| tree | ee4d9966f1eb293054b7ed865c9d4d6eb49e432b /docs/next-plumber.md | |
| parent | 8f6621f9f70db86d56266a59b56dfb92b324b0d9 (diff) | |
| parent | b3d32656413734952bc918c2d4cfd12fede6c214 (diff) | |
| download | pardes-f749eb712d990a9b03f1db372d5311e77bd32edd.tar.gz pardes-f749eb712d990a9b03f1db372d5311e77bd32edd.zip | |
integration: the terminal behind src/Term.zig, with the diff viewer and the plumber's first phase
A merge of term-phase0 and pardes-next. File.zig's recolorSyntax keeps the theme's grounds and names Term.Filter and Term.Span; the changelog keeps both sides' entries, the palette sentence in the place of the entry the terminal work cut down. core-test 985/985 on tui; the diff, pager and tree process cases pass, goldens unchanged.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'docs/next-plumber.md')
| -rw-r--r-- | docs/next-plumber.md | 896 |
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. |
