461655ce

build: the folder rule — tui imports client, never the reverse

a73x 2026-08-28 20:18

Commit message

build: the folder rule — tui imports client, never the reverse

A directory is a suggestion until something refuses to build. Layers say
which way an import may point; folders say which domain may know the
other exists, and the two are different questions — client importing tui
points strictly downward and is exactly what must not compile into an
app that paints its own way.

Rule 4 reads the sources, because an import graph cannot catch a module
that writes the escape bytes itself. Both debts the rules find are
signed rather than hidden: folder_exemptions carries client -> interact,
and four files under engine/ and client/ carry a one-line marker saying
why they spell VT bytes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CLAUDE.md

Old		New
@@ -51,6 +51,13 @@ engine and a client can link those folders and paint its own way:
51	\| `src/cli/` \| `main`(muxd) `mux_main` `muxa` `webhub_main` `flags` \|	51	\| `src/cli/` \| `main`(muxd) `mux_main` `muxa` `webhub_main` `flags` \|
52	\| `src/` \| `xdg` `sockpath` `proxy` `quic` `testtmp` — what both sides link \|	52	\| `src/` \| `xdg` `sockpath` `proxy` `quic` `testtmp` — what both sides link \|
53		53
		54	`build.zig`'s `checkFolderRules` enforces it: engine and client name no tui,
		55	server or cli module; server names no client and no terminal; tui imports
		56	client and never the reverse; and nothing under `src/engine/` or `src/client/`
		57	spells `termios` or an escape byte without a `// folder rule 4 exemption:` line
		58	saying why. Both known debts are signed in `folder_exemptions` and those
		59	markers.
		60
54	Layers are enforced in the same module table (grep `.layer =` for the graph).	61	Layers are enforced in the same module table (grep `.layer =` for the graph).
55		62
56	\| Layer \| Modules \|	63	\| Layer \| Modules \|

build.zig

@@ @@ -356,6 +356,126 @@ comptime { @@
+/// The domain folders under `src/`. A module lives in the folder of the thing
+/// that owns it, and this is what "owns" costs: an app that links `engine` and
+/// `client` to paint its own way must be able to do so without dragging a
+/// terminal in. `mux_core.wasm` already links that set with no tty anywhere,
+/// which is the proof the rule generalises past this repo's own binaries.
+///
+/// `root` is the shared layer-0 utilities both sides link; `foreign` is the
+/// test fixtures under `test/`, which are nobody's domain and unconstrained.
+const Folder = enum { root, engine, server, client, tui, cli, foreign };
+fn folderOf(path: []const u8) Folder {
+    if (!std.mem.startsWith(u8, path, "src/")) return .foreign;
+    const rest = path["src/".len..];
+    const slash = std.mem.indexOfScalar(u8, rest, '/') orelse return .root;
+    const dir = rest[0..slash];
+    inline for (@typeInfo(Folder).@"enum".fields) |f| {
+        if (std.mem.eql(u8, dir, f.name)) return @field(Folder, f.name);
+    }
+    fatal("folder rule: src/{s}/ is not a domain folder — add it to Folder " ++
+        "or put the module in one that exists", .{dir});
+}
+/// The folders the doc gate and the folder rules both walk. Listed rather
+/// than globbed: a new domain folder is a decision about who owns what, and
+/// it must be made here, in the enum above, and in the rules below together.
+const src_dirs = [_][]const u8{ "src", "src/engine", "src/server", "src/client", "src/tui", "src/cli" };
+/// A folder edge the rules forbid and this repo still has, signed with its
+/// reason. Not a waiver mechanism to reach for: an entry here is a stated
+/// debt, and the rule's whole value is that removing one is a visible diff.
+const FolderExemption = struct { from: []const u8, to: []const u8, why: []const u8 };
+const folder_exemptions = [_]FolderExemption{
+    .{
+        .from = "client",
+        .to = "interact",
+        // The attach loop drives the terminal-facing machinery directly, so
+        // today `client` cannot be linked without a tty — exactly the thing
+        // the rule exists to make visible. Splitting interact into the
+        // transport-driving half and the tty-owning half is the fix, and it
+        // is bigger than a folder move.
+        .why = "client.attach drives interact directly; linking client still pulls a tty in",
+    },
+};
+fn folderExempt(from: []const u8, to: []const u8) bool {
+    for (folder_exemptions) |e| {
+        if (std.mem.eql(u8, e.from, from) and std.mem.eql(u8, e.to, to)) return true;
+    }
+    return false;
+}
+/// The folder rules, checked over the same table the layers are. Layers say
+/// which way an import may point; folders say which domain may know the other
+/// exists — two different questions, and a legal layer edge can still be an
+/// illegal domain edge (`client` importing `tui` points downward and is
+/// exactly what must not compile into a headless app).
+fn checkFolderRules(b: *std.Build) void {
+    for (&mod_table) |spec| {
+        const from = folderOf(spec.path);
+        for (spec.imports) |dep| {
+            const to = folderOf(mod_table[idx0(dep)].path);
+            if (folderExempt(spec.name, dep)) continue;
+            if (from == .client and to == .tui) fatal(
+                "folder rule 3 broken: {s} (src/client/) imports {s} (src/tui/) — " ++
+                    "tui imports client, never the reverse",
+                .{ spec.name, dep },
+            );
+            if ((from == .engine or from == .client) and
+                (to == .tui or to == .server or to == .cli)) fatal(
+                "folder rule 1 broken: {s} (src/{s}/) imports {s} (src/{s}/) — " ++
+                    "engine and client name no tui, server or cli module",
+                .{ spec.name, @tagName(from), dep, @tagName(to) },
+            );
+            if (from == .server and (to == .client or to == .tui)) fatal(
+                "folder rule 2 broken: {s} (src/server/) imports {s} (src/{s}/) — " ++
+                    "the daemon knows of no client and no terminal",
+                .{ spec.name, dep, @tagName(to) },
+            );
+        }
+    }
+    checkNoTerminalBytes(b);
+}
+/// Runtime twin of `idxOf`, for the loops above that read the table as data.
+fn idx0(name: []const u8) usize {
+    for (&mod_table, 0..) |m, i| if (std.mem.eql(u8, m.name, name)) return i;
+    fatal("module table: unknown module '{s}'", .{name});
+}
+/// Folder rule 4: nothing under `src/engine/` or `src/client/` spells a
+/// terminal. Emitting escapes and driving termios is the tui's job, and an
+/// import graph cannot catch a module that writes the bytes itself — so this
+/// reads the sources, the way the doc gate does.
+///
+/// The escape hatch is a line saying `folder rule 4 exemption:` and why. It
+/// is per FILE and deliberately blunt: a file that has to spell VT bytes is a
+/// design fact worth one visible line, not a per-site suppression nobody
+/// reads.
+fn checkNoTerminalBytes(b: *std.Build) void {
+    const needles = [_][]const u8{ "termios", "\\x1b[", "\\x1b]" };
+    for ([_][]const u8{ "src/engine", "src/client" }) |sub| {
+        var paths: std.ArrayList([]const u8) = .empty;
+        zigFilesIn(b, sub, &paths);
+        for (paths.items) |path| {
+            const src = b.build_root.handle.readFileAlloc(b.allocator, path, 4 << 20) catch |e|
+                fatal("folder rule 4: cannot read {s} ({s})", .{ path, @errorName(e) });
+            if (std.mem.indexOf(u8, src, "folder rule 4 exemption:") != null) continue;
+            for (needles) |n| {
+                if (std.mem.indexOf(u8, src, n) != null) fatal(
+                    "folder rule 4 broken: {s} spells `{s}` — driving a terminal " ++
+                        "is src/tui/'s job, and {s} must link into an app that " ++
+                        "paints its own way. Move the bytes, or write one line " ++
+                        "`// folder rule 4 exemption: <why>` in the file",
+                    .{ path, n, sub },
+                );
+            }
+        }
+    }
+}
+/// Every grant the table hands out must be one the source asked for: for
+/// each name in a row's `imports` / `test_imports`, that row's root source
+/// file has to contain `@import("<name>")`. The layer rules cannot see a
+    // The tool is inside its own corpus: a gate its author is exempt from is
+    // an argument, not a rule.
+    var checked: std.ArrayList([]const u8) = .empty;
+    for (src_dirs) |d| zigFilesIn(b, d, &checked);
+    zigFilesIn(b, "tools", &checked);
+    var indexed: std.ArrayList([]const u8) = .empty;
+    for (src_dirs) |d| zigFilesIn(b, d, &indexed);
+    zigFilesIn(b, "test", &indexed);
+    zigFilesIn(b, "tools", &indexed);
+    // build.zig is cited by name in src/cli/main.zig's comments and is a real
@@ @@ -677,6 +795,8 @@ pub fn build(b: *std.Build) void { @@
+    checkGrantsUsed(b);
+    // ...and no domain of server.zig's tests goes unreached (nor the reverse).
+    checkServerTestsReached(b);
+    // ...and every module still sits in the folder of the thing that owns it.
+    checkFolderRules(b);
+    // Two instances per row that has test grants: `mods[i]` is production —
+    // what the exes are built from and what every importer sees — and

src/client/keymap.zig

Old		New
@@ -10,6 +10,7 @@
10	//!	10	//!
11	//! Deliberately platform-free — no posix, no fds, no clocks — this module	11	//! Deliberately platform-free — no posix, no fds, no clocks — this module
12	//! must compile for wasm32-freestanding.	12	//! must compile for wasm32-freestanding.
		13	// folder rule 4 exemption: turning a key event into VT bytes is this module's whole contract, and it does so with no terminal in sight.
13		14
14	const std = @import("std");	15	const std = @import("std");
15		16

src/engine/delta.zig

Old		New
@@ -7,6 +7,7 @@
7	//! Engine and protocol are the whole of its world — no daemon, no clients,	7	//! Engine and protocol are the whole of its world — no daemon, no clients,
8	//! no sockets — which is what lets the tracker be driven directly by a test	8	//! no sockets — which is what lets the tracker be driven directly by a test
9	//! holding nothing but an engine.	9	//! holding nothing but an engine.
		10	// folder rule 4 exemption: the tests drive the engine with VT bytes; no production line here writes an escape.
10	const std = @import("std");	11	const std = @import("std");
11	const Engine = @import("engine").Engine;	12	const Engine = @import("engine").Engine;
12	const proto = @import("protocol");	13	const proto = @import("protocol");

src/engine/engine.zig

Old		New
@@ -1,5 +1,6 @@
1	//! Authoritative headless terminal engine. Wraps ghostty-vt's Terminal	1	//! Authoritative headless terminal engine. Wraps ghostty-vt's Terminal
2	//! and TerminalStream behind the small surface mux needs.	2	//! and TerminalStream behind the small surface mux needs.
		3	// folder rule 4 exemption: ghostty-vt's grid is fed and read in VT bytes — this module IS the VT, and its selection formatter emits SGR.
3	const std = @import("std");	4	const std = @import("std");
4	const vt = @import("ghostty-vt");	5	const vt = @import("ghostty-vt");
5		6

src/engine/protocol.zig

Old		New
@@ -7,6 +7,7 @@
7	//! readInt/writeInt cover without a dependency. A serialization library	7	//! readInt/writeInt cover without a dependency. A serialization library
8	//! (msgpack) becomes due when payloads turn truly structured — cell runs,	8	//! (msgpack) becomes due when payloads turn truly structured — cell runs,
9	//! multi-rect damage, capability negotiation.	9	//! multi-rect damage, capability negotiation.
		10	// folder rule 4 exemption: a delta row IS painted bytes on the wire — composeDelta stamps CUP and EL around a row the far side replays.
10	const std = @import("std");	11	const std = @import("std");
11		12
12	pub const MsgType = enum(u8) {	13	pub const MsgType = enum(u8) {