8a07693c

Design: link, serve, and the one await loop

a73x 2026-08-31 17:57

Commit message

Design: link, serve, and the one await loop

The connection-primitives campaign spec: promote the fd|pipe|quic union
to a shared link row with one awaitFrame, give bind+teardown one owner
in serve.zig, and pumpUntil for the harness. Four audit findings, six
stages, no wire change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TWxBL1HBULH1ZwTNzzKTja

docs/superpowers/specs/2026-08-31-connection-primitives-design.md

@@ @@ -0,0 +1,268 @@ @@
+# Connection primitives: link, serve, and the one await loop
+-08-31. Status: approved design, pre-implementation.
+## Problem
+`dial.zig` states the product's thesis — connecting a client to a daemon is
+*the* operation, so it is a callable primitive — and then the thesis stops at
+dial's own edge. An audit (this date) found four places the codebase re-answers
+a question a primitive should own:
+. **"Wait for one frame of type X"** exists ~10 times: `dial.askOn` (private
+   on purpose), `muxa.awaitFrameFd` / `awaitFrameQuic`, `client.awaitFrames`,
+   the server test harness's `awaitFrame` / `awaitFrameOn` / `firstStateFrame`,
+   and private copies plus inline loops across the `server_test_*` files.
+   `dial.zig`'s own comment ("private on purpose: this loop DROPS every frame")
+   is the causal record: the drop policy was sound, making it private forced
+   every caller with a different policy to write the loop again.
+. **Binding a socket you own** has three production answers: the daemon
+   (`sockpath.claim` + guarded unlink), the agent relay (unguarded unlink),
+   askpass (raw socket/bind/listen, unguarded unlink). Only the daemon carries
+   the delete-by-name-races-a-successor protection that `sockpath.zig` records
+   buying from an incident.
+. **Driving a test daemon to a condition** is 13 hand-rolled
+   `while (spun < N …) pumpOnce(step)` loops with guessed round counts, plus
+   hand-rolled `deadline_ms -|= 100` countdowns in three files.
+. **`muxa.AgentConnection` is a second `client.Transport`**: two independent
+   answers to "a connection that is either an fd or a QUIC client", each with
+   its own send, await, close, and QUIC staging.
+Checked and NOT gaps: the daemon's frame dispatch (`handleDaemonVerb` / `Peer`
+is properly factored), and the one-replay-core invariant (replica / client_core
+/ webhub / wasm_core are four different concerns, not four copies).
+## Decisions (settled in brainstorm)
+- **One campaign, four gaps, staged.** One spec; implementation lands in
+  stages, each independently green.
+- **The Link is promoted to a shared row.** The fd | pipe | quic union moves
+  out of `client.Transport` into a new `src/link.zig`. The await/send
+  primitives are written once against it. `mux a` never imports `client`, so
+  the agent row keeps its isolated suite.
+- **`serve.zig` owns bind + teardown only.** Accept loops stay with their
+  owners — the daemon's nonblocking slot-table accept, askpass's
+  credential-checking serve, webhub's thread-per-conn are real differences,
+  not duplication.
+- **`pumpUntil` goes in the server test harness**, between `pumpOnce` and
+  `serverThread`.
+## Section 1 — the `link` row
+New shared root `src/link.zig`, a table row beside `dial` in the "what both
+sides link" tier. It is the live connection to a daemon, however reached, and
+the verbs every holder duplicates today:
+```zig
+pub const Link = union(enum) {
+    fd: std.posix.fd_t,   // unix socket: one fd, read and write
+    pipe: Pipe,           // --via / handoff ssh: the child + its stdio fds
+    quic: Quic,           // *quic.Client + the qout staging buffer
+};
+// sendFrame(self, t, payload)
+// readFrame(self, alloc) -> Incoming { frame, incomplete, closed }
+// awaitFrame(self, alloc, want, deadline_ms, sink) -> ?Frame   (section 2)
+// pollFd, timeoutMs, service, close
+```
+What it is NOT: policy. Redial/backoff (`client.nextBackoffMs`, handoff,
+muxa's one-reconnect and its `addr`/`key`/`reconnected` state), attach
+semantics, and interpretation of `Incoming` stay with the owners. `Transport`
+keeps `err_fd`, `reason`, and narrate — the handoff story wraps a Link.
+Boundary consequences (load-bearing):
+- `link.zig` imports `term` (frames) and `quic`. **`proxy.zig` and the QUIC
+  modules must never import it** — proxy stays byte-blind per the invariant.
+- **The QUIC send-staging buffer moves into the link.** `Transport.qout` and
+  muxa's `sendFrameQuic` deadline-flush are two answers to "the ring would not
+  take my bytes"; the buffer is a property of the quic link and lives there
+  once.
+- `dial.zig` keeps its public contract. `dial.ask` becomes dial →
+  `Link{.fd}` → `awaitFrame` → close; the private `askOn` is deleted, with
+  `awaitFrame` as its public successor.
+- wasm untouched: `wasm_core` / `client_core` never link this row.
+`Transport` and `AgentConnection` become wrappers holding `link: Link` plus
+their own policy fields. Deleted with the merge: muxa's `awaitFrameFd`,
+`awaitFrameQuic`, `sendFrameQuic`, `waitReady`, and Transport's per-arm
+switches in `writeFrame` / `readFrame` / `service` / `flushQuic` / `close`.
+## Section 2 — the `awaitFrame` contract
+Non-matching frames go to a sink, and the sink may end the wait:
+```zig
+pub const Sink = struct {
+    ctx: ?*anyopaque = null,
+    on: ?*const fn (ctx: ?*anyopaque, frame: proto.Frame) anyerror!void = null,
+};
+pub fn awaitFrame(self: *Link, alloc, want: proto.MsgType,
+                  deadline_ms: ?u32, sink: Sink) !?proto.Frame
+```
+- `sink.on == null` → drop-and-deinit: exactly `dial.askOn` today, so
+  `dial.ask` callers change nothing.
+- muxa's classification (snapshot → `saw_snapshot`; exit_status →
+  `AttachRefused` / `SessionExited`) becomes its sink; a sink error propagates
+  out of the wait. This is why `on` returns `anyerror!void`: muxa's "other"
+  frames are answers, not noise, and that was its whole reason for a second
+  copy.
+- **Ownership rule, stated at the declaration:** a sink that returns normally
+  means keep waiting; frames handed to the sink are the sink's to deinit only
+  if it keeps them, otherwise `awaitFrame` deinits after the call returns.
+- **Deadline is relative `?u32`, null waits forever** (dial's convention).
+  muxa converts from its absolute i64 at its own boundary.
+- Returns `null` = deadline ran out; `error.*` = peer closed, corrupt frame,
+  or the sink's error. The QUIC arm folds `cl.pump()` + `takeFrame` +
+  `cl.dead` into the same loop.
+- `error.NoDaemon` / `error.RequestNotSent` stay dial's: they are about the
+  ask round trip, not the wait.
+Converts: `dial.ask` (internals only), muxa's three await fns,
+`client.awaitFrames`, harness `awaitFrame` / `awaitFrameOn` /
+`firstStateFrame` (the last via a StateFrame-decoding sink), and the
+clipboard/attach/session/modes test loops. Does NOT convert: the wall's pump
+loop — a multiplexed event loop over doorbell + socket, not a
+wait-for-one-type; wrong altitude.
+## Section 3 — the `serve` row: bind + teardown
+New shared root `src/serve.zig`. (askpass — a client module — binds too, so
+it cannot live under `src/server/`.)
+```zig
+pub const Policy = enum {
+    refuse_live,  // daemon socket: sockpath.claim — never steal a path that answers
+    clobber_own,  // agent relay, askpass: the name embeds our identity; a leftover is ours
+};
+pub fn bind(path: []const u8, opts: struct {
+    policy: Policy,
+    backlog: u31 = 128,
+    cloexec: bool = false,
+}) !Bound;
+pub const Bound = struct {
+    fd: std.posix.fd_t,
+    path_id: sockpath.PathId,
+    pub fn close(self: *Bound, path: []const u8) void; // stillAt-guarded unlink, always
+};
+```
+Decisions inside:
+- **All three binders get the `stillAt` guard at teardown.** A behavior
+  change for the agent relay and askpass, and the point: delete-by-name
+  racing a successor's bind applies wherever a name can be re-bound, and
+  askpass's pid-named path is exactly the pid-reuse case its own comment
+  worries about. Cost: one fstatat.
+- **`clobber_own` does the pre-bind `deleteFile`** both current sites
+  hand-roll, written once next to the rationale.
+- **`cloexec` defaults false and the default is load-bearing:** `mux d
+  upgrade` execs the candidate over the running daemon and the listener fd
+  (and the agent sockets) must survive the exec. askpass passes true. The
+  field's comment names the upgrade path so nobody hardens the default.
+- **Length refusal stays split:** `sockpath.tooLong` remains `mux d`'s
+  parse-time refusal on the asking client's stderr; everyone else lets
+  `initUnix` refuse at bind (the agent relay already documents relying on
+  that).
+- **`sockpath.zig` stays** as serve's engine room; `claim` / `PathId` /
+  `answers` / `tooLong` keep their homes. Whether `claim` stays `pub` is an
+  implementation-time call.
+Converted: the daemon listener (`server.zig` init), the agent relay
+(`server_agent.zig`), askpass's listener. Test-local listeners (proxy tests,
+harness fakes) stay on bare `addr.listen` — they own no path anyone could
+race.
+## Section 4 — the harness: `pumpUntil`
+Test-only, in `server_test_harness.zig`:
+```zig
+pub fn pumpUntil(srv: *Server, deadline_ms: u64, ctx: anytype,
+                 pred: fn (@TypeOf(ctx)) bool) !bool;
+```
+- Fixed 5 ms pump step inside; callers state a wall-clock deadline, not a
+  round count. The 13 spin loops with guessed rounds×step become one honest
+  "within N ms".
+- Returning `false` is an assertable value, so no test wedges silently — the
+  deadline turns a hang into a named failure (a wedged `zig test` prints
+  nothing; the pin must be able to fire).
+- Harness `awaitFrame` / `awaitFrameOn` / `firstStateFrame` become thin
+  wrappers over `Link.awaitFrame`; `awaitGridText` keeps its shape but its
+  frame loop goes through the same call; the private copies in
+  `server_test_attach` / `session` / `modes` / `clipboard` are deleted.
+## Section 5 — staging, gates, risk
+Six stages, each a green `make check` with its own commit story; `make ci`
+at delivery. **No wire change anywhere** — every byte on every socket is
+identical before and after. The xversion gate should be a formality; run it
+once at the end.
+. **`link.zig` lands** with unit tests: socketpair for the fd arm (dial's
+   tests are the template), `quicTestServer` for the quic arm, the sink
+   ownership rule pinned. Table row added; nothing converts.
+. **`dial.ask` over it**; `askOn` deleted. dial's tests pass unchanged —
+   they are the contract.
+. **`Transport` wraps a Link** (qout moves in). Gate: e2e + wall tests.
+. **`AgentConnection` wraps a Link**; the three await/send arms deleted.
+   Gate: `make agent`.
+. **`serve.zig` lands**; three binders convert. The guarded-unlink behavior
+   change gets a test each in `server_test_agent` and askpass's suite,
+   modeled on the existing successor-socket test in `server_test_session`.
+. **Harness sweep**: `pumpUntil`, wrapper awaits, delete the private
+   copies. Largest diff, zero production bytes.
+Stages 3–4 are independent of 5–6 and may swap if one stalls.
+Risks named:
+- Stage 3 is the dangerous one. `Transport.close`'s idempotence (the EBADF /
+  double-close panic note) and the pipe-kill ordering must move
+  byte-for-byte, and the wall's redial paths (`detach_ack`, `asked`) must
+  not notice the wrapper.
+- Stage 4: reconnect classification (`refusalPending` on BrokenPipe et al)
+  stays muxa policy; only the loops move.
+- Stage 5's behavior change is deliberate and tested, not incidental.
+## Line count: before and after
+Measured 2026-08-31 (`wc -l`, whole tree 55,066 Zig lines). Deletion
+candidates, counted by symbol span:
+| Region | Lines |
+|---|---|
+| `dial.askOn` + doc | 42 |
+| muxa `sendFrameQuic` + `awaitFrameFd` + `awaitFrameQuic` + `waitReady` | 133 |
+| `client.awaitFrames` | 58 |
+| `Transport` per-arm write/service/timeout/flush/read + `close` | 115 |
+| harness `firstStateFrame` + `awaitFrame` + `awaitFrameOn` | 105 |
+| test-private `awaitSelectionReply` / `awaitSnapshotSize` / `awaitMarkerWithoutSnapshot` | 182 |
+| inline poll+readFrame test loops (attach/session/modes/deliver/await) | ~250 |
+| spin loops + `deadline_ms` countdowns | ~60 |
+| three binder sites (bind + teardown blocks) | ~50 |
+| **total removed or moved** | **~995** |
+Estimated additions: `link.zig` ~350 (of which ~120 its own tests),
+`serve.zig` ~180 (of which ~60 tests), `pumpUntil` ~25, harness wrappers
+~40, wrapper glue in `Transport` / `AgentConnection` ~60 → **~655**.
+Net: **roughly −350 lines**, almost all of it test code. Production is
+approximately flat by design — that code *moves* to one owner rather than
+shrinking. The value is one copy of each loop, not fewer bytes; the test tree
+is where consolidation actually deletes.
+These are estimates against measured spans; re-measure at delivery and
+replace this table with the real diffstat.
+## Success criteria
+- `grep -rn "posix.poll" src/ | xargs grep -l readFrame` finds only
+  `link.zig` (and the wall's event loop).
+- One `Link` union in the tree; muxa still does not import `client`.
+- All three production binders reach the socket through `serve.bind` and the
+  guarded unlink.
+- No `while (spun < N)` pump loops remain in `src/server/`.
+- `make ci` green; xversion gate green; wire bytes unchanged.