1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
|
# 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`.
## What phases 2-4 did otherwise (2026-11-17)
- **Q4 is (b) now**, the coordinator's lean while the user was away: a
program a rule starts runs detached, as Plan 9's plumber starts one
(Effect.start, every host's host_io.startDetached: setsid, stdin, stdout
and stderr `/dev/null`, every other fd closed, argv exec'd in wdir with no
shell). Its output is not the session's log, as the lean said: that needs
an inbox message and an Event through the tui, window, macOS and daemon
hosts, which other agents are changing. A failure to start (the program
not found, its directory gone) is said and logged, the child's errno
carried back by a close-on-exec pipe. Its directory and words fit 256
bytes, an effect's inline payload.
- **Only a diff paged is sent** (§5.4 had every page sent). Text paged is
`type text`, which the look rules do see, contrary to §5.4: their
`matches` would run over the whole output (up to a MiB, and the regular
expressions' 300 ms budget) at each page. A diff is `text/x-diff`, which
every look rule refuses at its first pattern.
- **A port pardes reads itself (edit, web, a kind) asks nobody** whether a
program reads it: its readers' copies are the authority's own to hand
out, and pardes reads it anyway, so a URL's look still speculates whole.
Only another port's dispose asks `tape.authority`.
- **The rules in force are read once** and kept until their text changes
(by its hash, derived state): per send the parse was 29k instructions
in a fast build, about half of a URL's send and 40% of a word's look.
- **`showdata` from another sender** makes a clean pane of its `filename`
(acme's plumbshow); the pager's own message is shown already.
- **plumb/rules' rest read at the close**, refused there, is an `err` in
the log (Plan 9 loses it); the T1 monkey models it as a line file's.
## 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.
|