From d2ab76c2f590144100d93d7fe12aeaa83697434f Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Fri, 30 Oct 2026 13:10:49 -0300 Subject: docs/next-daemon.md: phase 6's GUI replica notes: the decisions at its forks (the window client the tty's with a window for a terminal, replica.Link shared; the window's writes into its core one funnel, read over the client's own view; no pump in a client, its window's font, opacity and shader files its own; the wheel a row a turn there; a client's frontend said first; one desktop semantics, a view's words by its frontend; a window's session serving at its step boundary, a client's view no window there; its font and opacity answers taped; the far path amort's; a check once quiet), what was found (a run's output read off a replica's emulator, a cut-off client's silent end, a second's turn in the replica tests), the window client's numbers (keystroke to present at each RTT and through the box, echo predicted and not, its joins, the session's step while it lags), the gates in Debug, ReleaseSafe and on the box, the A/B against base (the core, live tty and live window, idle and busy cores), and what is not done Co-Authored-By: Claude Opus 5.5 --- docs/next-daemon.md | 319 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) diff --git a/docs/next-daemon.md b/docs/next-daemon.md index e1d9e039..ab772b51 100644 --- a/docs/next-daemon.md +++ b/docs/next-daemon.md @@ -3282,3 +3282,322 @@ Not done, and why: in zstd. - **The cache is per user, unencrypted, 0700**: a blob of a file the user could read elsewhere, kept until evicted or the cache is cleared. + +## Phase 6: GUI replica notes + +Built 2026-10-30 (`src/gui/gui.zig` `remote` and the window session's +`Peers`, `src/replica.zig` `Link`, `src/views.zig` `within`, the +`builtins.zig` registry's `here`, `Event.frontend`, wire 16; +`test/daemon.py --window-clients`). A window is now a replica client, of a +terminal's session or a window's, and a window's session serves replicas of +either kind. Decisions at the forks, with the ponytail lens: + +- **The window client is the tty's, with a window for a terminal.** + `pardes-gui --attach=:` and `--attach=:` (ssh, + main.zig `remoteAttach`, now the frontend's own `remote`) make the window + as a session's is (`runNative`) and run `remoteSession` instead of + `localSession`: the dial, the dump's replica checked against the + session's digest, a reader thread, the rejoin after a divergence or an + Upgrade's `refused`, the end in words. What is frontend-free in the tty's + `Remote` moved to `replica.Link` and both use it (`input`, `take`, + `drawn`, `quietCheck`, `rejoins`, `redial`, the stats and checks); the + tty's keeps its draw. `pardes-gui --attach` and `--attach=` (no + colon) re-open a local session's window through the daemon as before. +- **The window's 52 writes into its core are one funnel, read over the + client's own view.** The window feeds its core through `Input.post` + (dispatch, the wheel, the touch and gamepad paths, the timedemo, the + test feed), and a handful of frame chores call `core.update` themselves + (its size, the pointer under a frame that moved, the smooth scroll). In + a client `Input.post` appends to the client's list (`Client.post`, texts copied) and nothing writes the + core. Mapping a pointer reads the core's view fields (its rects, its + presentation, its row metrics), and another client's input may have made + the replica's live view another's: so the window's work runs inside + `Replica.within` (`views.within`: the live view parked, the client's + unparked, put back after exactly as it was, as `drawOne` draws), and its + inputs are applied after, one `Link.input` each. With one client the + live view is its own and `within` is a call. +- **No pump in the client.** Its core moves only by its own inputs and the + session's units; it draws its view between steps (`Replica.draw` through + the window's own `present`), puts back what presenting writes in the + core (a skipped image, a frame owed) and records its frames as the tty + client does. The window's per-frame host chores that write the core stay + out of a client: opacity, font requests and their answers, a scene + effect the GPU refused, user shader files (their compiles' messages). + ponytail: a client's window keeps its own font, opacity and shader + files; the built-in scene effects follow the session's settings. +- **The wheel in a client moves a row a turn.** The window's glide and a + touchpad's fraction run on the core's clock, which in a client is the + session's and moves only with its units. ponytail: whole rows, no glide; + the local window's is unchanged. +- **A client says its frontend first** (`Event.frontend`: windowed, native + images and patches; wire 16, client tag 0x20): the view the session opens + for a joiner copies the live view's, and a window's view of a terminal's + session would have drawn pictures as cells and the window's words would + have been refused there. A terminal's client says it is no window, and + draws pictures as cells (ponytail: a kitty-graphics terminal client was + drawing none before, its shm never probed). +- **The terminal's build and the window's step alike.** The semantics hash + named the platform, so a window could not join a terminal's session (the + FreeBSD box has terminals only) nor a terminal a window's. Their cores + differ in the step only by the window's own words (Fonts, Pet, Font, + TaglineSize, WindowOpacity, Ligatures, Lift and its family, the scene + effects, their leader paths `SPC t f` and `SPC t r`) and the Settings + report. Three ways: refuse cross-build joins (the box and a window's + clients impossible); accept known divergences (Help's index, `SPC t f` + and Settings would each make the other build's clients join again); or + give both builds every word and let the *view's frontend* decide + (kakoune's way: each client its own). The last: a desktop build's + registry is the window's (`builtins.capabilities`), and + `builtins.registry.here` says whether the live view takes a word (a + window's own words in a window's view alone, `Pardes.windowed`, which a + window's build starts true and a client says). `runBuiltinFrom` refuses + the rest in the words the terminal said before ("Lift is GUI-only, + invalid here"), and the leader paths, Help's index, `/commands`, the root + ctl's settings and the Settings report list the view's own. The render + keeps the build's own frontend (`builtins.frontend`: the tty draws no + lift). Local behaviour is unchanged: the 113 snapshots, which hold the + tty's Help index and leader groups, pass as they were. The hash names a + family (`desktop`) for the two; the tty binary carries fonts.zig and the + window's builtins (a few KB). +- **A window's session takes replicas at its step boundary,** as the tty's + does: `Peers` in the window's Shell, its wake an SDL event, `boundary` + after each pump, a Restore and an Upgrade letting clients go + (`dropAll`, `refuseAll`), Detach in a client's view ending that client. + What the tty's session does with clients, the window's does too: one + person's input a wait (`split`: the next SDL input held for the next + wait, so a pump is one unit of it), a pump woken only by a client's post + reads no new time (`mail_only`), and its last window closed with clients + attached is a Detach, not the session's end. +- **A client's view is no window here.** The window's Shell kept the live + view's window in the Gui (`follow`); a client's view live (its input the + last) has none, so `follow` keeps the window it holds (`windowed`, a mask + of the views that are windows), and what the window does to its own view + makes that view live first (`windowView`: an SDL event of the window, + `Input.post`, the frame chores when one is due: its size, its scroll, a + font). Found by the first test with a window typing beside a client: the + window's keys went into the client's view. +- **What the window writes into the core outside a step is taped.** The + window's font (observed, requested, taken, acknowledged, refused), its + opacity's answer and a refused scene effect are core calls now + (`tape.Input`), so a window session's clients replay them; the rest of + its writes were taped already (sizes, pointers, panel acknowledgements, + messages). ponytail: an adopted shell's pane (`Adopt`) and a terminal + reader's failure still write the core directly; neither is taped. +- **The far path is the tty's** (amort's line, merged under this one): + through ssh the window client is far as the tty's is + (`PARDES_REPLICA_FAR` either way), its join's blobs found by hash in the + core it leaves or the cache on disk, its stream in zstd, what it made + kept at its end (`replica.Have`, the same calls in `remoteSession` as in + tty.zig's `remote`, through `Link.load` and `Link.redial`). One wire + version, 16, carries amort's far word (the first message after the + hello) and the frontend (a client's first input). +- **A check once a quiet while, not once a wake.** The tty's client asked + the session's digest on its first wake after a change; a window session + in test mode pumps a frame a tick, a unit each, so no wake ever came + first. A client now asks once it is quiet, 300 ms after its last input + and its last check (`quietCheck`); the answer is in stream order, so it + holds with units flowing. + +Found on the way: +- **A pty/run's answer read the replica's emulator** (vnolzlvq). A run's end + (`ninep/pty.zig finish`) took the command's output off the terminal in + the step; a screen-state replica's emulator is its deltas', which a + lagging client's are states behind, and replaying the end read pins into + pages it never had: ghostty's `leftWrap` overflowed (a window client + stopped while a shell flooded the session aborted 3 runs in 8). The + output is taped now (`.prompt`, the same site as a prompt read after + output); none in 6 since. +- **A client cut off while lagging could end in silence** (ussmwtkk): its + own write found the link shut before its reader did, which ended the + loop as a quit, exit 0, no words. A failed write is the session's hangup. +- **The rejoin's drain** (the coordinator's ymzywopz, on main): the window + client joins its reader before it drains, so it never had that race. +- **A second's turn is a misprediction** (ssruwvql): an edit stamps its + file with the clock's second, which a replica guesses (its last unit's + time, the time since and the link's round trip); a key the session takes + in another second than the guess goes the slow way, replayed. Right, and + rare live (the round trip's jitter against a second); but a test's + replica has no round trip yet and its authority takes the keys after all + are typed, and `another client's input first` counted exact fast + confirmations: under load in a Debug window build (a slower step) they + straddled a second in 11 runs of 40. The two tests that count them start + early in a second now: 0 of 30. +- **Harness traps:** a window's test feed is a pipe, whose lone ESC waits + for the next byte (the parser cannot tell it from a sequence's start), so + the tests send Escape as `CSI 27 u`; a terminal client's Esc is resolved + by the 50 ms wait for more input, which the test terminal's answers to + frames (`CSI 0 n`) can keep refilling while other clients' units arrive + (main's `normal_again`); a window session in test mode starts no daemon + unless PARDES_DAEMON says so. + +Measured. ReleaseFast, unstamped (one semantics here and on the box), the +timings alone on the perf cores (lock.sh), the windows offscreen (SDL's +offscreen driver, software present); the harness scripts are in +`.scratch/daemon/guirep/live/`. + +- **Keystroke to present on a window client, local-only actions** (base's + `pardes-perf-live --live-gui`, its timedemo's keys on a 50k-line file, + through `gui-live.sh`: a local window, or a window client of a terminal's + session detached on that file, through test/delay_relay.py at each RTT + and through the box's link; two rounds; p50 (p99), ms): + + | | key-down | key-right | edit-char | page-down | wheel | + |---|---|---|---|---|---| + | a local window, this line | 31.1 (40.3) / 31.5 (45.5) | 34.8 (44.2) / 35.3 (41.0) | 35.9 (44.4) / 36.5 (46.2) | 37.0 (50.0) / 37.8 (50.3) | 36.5 (47.3) / 36.9 (52.8) | + | a local window, base | 29.0 (35.9) / 31.5 (37.5) | 35.1 (45.9) / 35.3 (42.2) | 36.2 (42.2) / 36.5 (45.1) | 37.2 (48.1) / 37.5 (52.5) | 36.5 (50.0) / 36.8 (44.2) | + | client, direct | 31.3 (40.4) / 28.6 (36.2) | 35.1 (47.3) / 35.1 (54.4) | 36.7 (41.1) / 35.8 (44.0) | 36.0 (46.4) / 35.4 (40.8) | 35.8 (45.1) / 35.2 (45.8) | + | client, relay 30 ms | 29.9 (54.6) / 29.9 (42.7) | 34.9 (45.8) / 36.4 (53.6) | 35.7 (54.0) / 35.8 (45.8) | 34.9 (52.1) / 35.1 (47.3) | 35.1 (44.0) / 35.1 (42.6) | + | client, relay 80 ms | 32.7 (39.5) / 30.5 (36.6) | 38.1 (46.6) / 34.9 (44.0) | 39.1 (57.4) / 35.6 (46.1) | 37.7 (56.5) / 35.1 (43.9) | 38.0 (46.7) / 34.8 (44.5) | + | client, relay 207 ms | 31.1 (35.9) / 30.6 (36.2) | 35.6 (46.3) / 34.6 (59.9) | 35.9 (45.4) / 35.5 (55.3) | 27.9 (56.6) / 34.9 (47.8) | 36.9 (55.3) / 34.6 (50.8) | + | client, the box (far, zstd) | 33.7 (48.1) / 28.3 (43.9) | 31.1 (43.4) / 30.2 (46.4) | 30.9 (44.6) / 29.4 (39.3) | 33.8 (51.0) / 29.6 (48.4) | 28.7 (49.9) / 30.1 (43.2) | + + - **A window client's local-only action is as fast as a local window's + at every RTT, the box's included.** Both are the offscreen software + present's (30 to 38 ms, the final gate's GUI numbers): what the harness + can tell apart is the core's share, the client's render 0.4 to 0.5 ms + p50 (0.1 to 0.9 through the box) against a local window's update and + render 0.24 to 0.6 ms. The client's render runs on its rollback epoch's + allocator, which a local core's does not. + - **Visible rollbacks** (a frame drawn after an input the session + recorded otherwise, an upper bound; of 664 inputs a run): none direct + and at 30 ms, 10 and 0 at 80 ms, 0 and 9 at 207 ms, 15 to 24 through + the box (2.3 to 3.6%). Every other rollback (the session's own pumps' + units before the client's pending inputs: 536 to 610 a run here, 268 + to 295 through the box) is put back and replayed before the next + frame, p99 2.6 to 8.9 ms. +- **Terminal echo** (`echo-gui.py`: a key read off the window's test feed, + to the end of the GPU frame that shows it, PARDES_TEST_LATENCY's notes; + 40 keys; p50 / p90, ms): + + | | file (insert) | shell, predicted | shell, not predicted (PARDES_NO_ECHO) | + |---|---|---|---| + | a local window | 2.8 / 4.6 | | | + | client, direct | 2.5 / 4.5 | 4.3 / 9.7 | 25.5 / 29.7 | + | client, relay 30 ms | 2.6 / 4.7 | 5.1 / 11.0 | 60.4 / 64.8 | + | client, relay 80 ms | 3.1 / 4.6 | 4.7 / 4.9 | 101.9 / 121.9 | + | client, relay 207 ms | 2.7 / 8.2 | 4.4 / 10.0 | 236.8 / 248.9 | + | client, the box (far, zstd) | 4.2 / 5.2 | 4.2 / 4.8 | 242.5 / 243.3 | + + (Through the box, the harness's ssh had `-C` beside the stream's zstd; + a predicted key never waits for the link.) Every key of the shell's was + predicted and confirmed (40 of 40, at each RTT): a key at a prompt shows + in the window's next frame, as a key into a file does, the 0.5 ms of the + tty client's being a terminal's write where a window's is a frame (its + software present's 2.5 ms). Not predicted, it is a round trip and the + session's paced output. +- **Through the box, its join** (far, amort's path): the main test's 400 + lines, 4 blobs, 51 KB sent, dial and load 0.63 s (ReleaseSafe 0.99 s), + its first frame about 2.6 s after it started (ssh's forward is 2.0 s); + its rejoin after a forced divergence from the core it left, 4 blobs of + 4, nothing sent, 0.42 s. The live harness's 3.1 MB file: 3126 KB, 2.3 to + 2.4 s. +- **The session's step while a window client lags** (`lag-gui.py`: a shell + printing a line a millisecond for 12 s, a terminal's client typing a key + every 30 ms, the window stopped with SIGSTOP and cut off at a 256 KB lag; + µs, p50 / p99 / max; ReleaseSafe): the terminal client's inputs 30 / 75 / + 289, the boundaries 49 / 148 / 764, the window cut off (`cut 1`), and let + go on it said "let this client go" and ended. + +Gates (Debug unless said; scripts and logs in `.scratch/daemon/guirep/`): +- **Correctness.** `test/daemon.py --window-clients` (new): window clients + of a terminal's session at 0, 30, 80 and 207 ms beside a terminal's + client, every check of every client the session's digest (28 a run, + none differed); one put off the session's state joined again, and again + across an Upgrade (agreed 7 times), and detached; its far client's first + join 9 blobs, 57 KB, its rejoins 9 of 9 and 10 of 10 from the core it + left, nothing sent; a window's session served a terminal's client and a + window's (agreed 9 and 7 times); nothing left behind. Debug and + ReleaseSafe. `zig build replicas` at 30, 80 and 207 ms: none diverged, + 1545, 1590 and 1512 deltas checked, none wrong. Through the box + (`live/e2e_box_gui.py`: a session on the box, a window client and a + terminal's client from here, a terminal on the box attached beside them, + a file's edits, scrolls and moves, a shell's command, a second window + far, forced off the session's state and joined again): every check + agreed (the window 128, the terminal's 132; ReleaseSafe 131 and 134), + none mispredicted, the second window's first join 4 blobs 51 KB, its + rejoin 4 of 4 from the core it left, nothing sent; nothing left on the + box. +- **The window's own reopen** (`test/daemon.py --gui`, 5 detach and attach + cycles, a second window detached alone): pass, Debug and ReleaseSafe + (SDL's offscreen driver). +- **Suites**, once at the end (before the tests' fix and the rebase below): + `core-test -Dplatform=tty`, `unit-test -Dplatform=tty` (its perf gate), + `snap` 113 of 113, `replay` (113 scripts, 20 monkey seeds, none panicked + or diverged), `replicas`, `9p-io-test`, `fs-test`, `test/daemon.py` 20 + cycles, `--window-clients`, `--upgrade` (unstamped Debug to stamped), + `test/fs.py` (49 s): pass. + `unit-test -Dplatform=gui`: 1568 of 1580, 10 skipped, and the two that + fail on main (`tagline pointer mapping...`, `a tag caret past its row's + end...`); `core-test -Dplatform=gui`: the caret one, and in two of its + full runs a replica test's count of fast confirmations (below, ssruwvql; + after it, the core-test runs pass but for the caret one). + After the rebase onto main's `--ps` (prvoxvzk): `core-test` tty and gui, + `test/daemon.py` 20 cycles (its `manage` included), `--window-clients` + (its `--ps` checks: a terminal's session with window clients listed + alone as `(tty, detached)`, a window's serving clients as `(gui, + attached)`), `--gui` 5 cycles: pass, `core-test -Dplatform=gui` but + for the caret one. +- **ReleaseSafe** (`-Doptimize=ReleaseSafe -Dhome-install=false`, the + binaries the box's second run used): `--version`, a tty in a pty with the + daemon on and off, a window session offscreen for 5 s, `test/daemon.py` + 20 cycles, `--window-clients`, `--gui`, the lag test (`live/lag-gui.py`, + above), `test/fs.py` (38 s), `snap -Doptimize=ReleaseSafe` 113 of 113: + pass. Again after the rebase, built afresh: `test/daemon.py` 20 cycles, + `--window-clients` (its `--ps` checks), `--manage`, `--gui` 5 cycles, + `test/fs.py` (38 s): pass. +- **No local regression.** ReleaseFast, interleaved base new base new base + on the perf cores (`core_optimize` fast on both sides; base is + `.scratch/daemon/base`'s), the median of each side's runs, new/base, + beside base's own A/A; the new binaries are this line before its rebase + onto main's last two (a test's rest and `--ps`, neither on these paths): + - the core in process (`pardes-perf --reps 15`, idle cores, the second + of two runs): the opens 0.98 to 1.03, render 0.96 to 0.98, the keys, + page-down and wheel 0.95 to 1.02 (longline's 0.79 to 0.87, main's + already), the edits 0.90 to 1.03, body-2m 0.95 to 1.02, body-appends 0.95 to 1.02, + deep-sel 0.92 to 0.99 (longline's 360 ms on base, 0.1 ms on main + already), a terminal's cells (sb-64k to sb-8m) 0.88 to 1.02. The first + run's two outliers did not come again: body-appends on the board's + fixture 1.29 (A/A 0.96; then 1.02 alone, A/A 0.99, and 1.06 with the + other cores busy) and resize-cols at 1M lines 1.10 (then 1.02). + - live tty keystroke to present (base's `pardes-perf-live --live`, the + other cores kept busy by spinners at nice 19, as idle cores let the + powersave governor put the package to sleep between keys: base's runs + read 347 to 1651 µs; present p50 / core p50): key-down 1.03 / 1.03, + key-right 1.00 / 0.94, edit-char 1.00 / 0.99, page-down 1.01 / 0.95, + wheel 1.05 / 1.05 (A/A 1.00 to 1.02; base's runs 389 to 469 µs, this + line's 444 to 480), a 1M-line open 1.01, `yes | head -c 32M` 0.63 (A/A + 1.03). + - live window keystroke to present (`--live-gui`, offscreen; present / + core): idle 0.93 to 0.98 / 0.94 to 1.03 (A/A 0.95 to 1.05), busy 0.90 + to 0.97 / 0.98 to 1.03 (A/A 0.85 to 0.97 / 0.97 to 1.10). + +Not done, and why: +- **A window client paints nothing ahead.** A key whose frame the session + owes (an image's, a PDF's lane) waits for its unit; a local window's + paint-ahead is the core's, which a client's moves only by units. +- **No glide in a client, and a touchpad's fractions round to rows** (the + core's clock is the session's there, above). +- **The notice a client gets is in its title and its log, not its frame** + (the session's words: joined again, let go, refused). The tty's draws + them on its notice band, which the window's frame has no slot for + outside the core. +- **A client's window keeps its own font, opacity and shader files**: the + session's `Font`, `Fonts` and `WindowOpacity` move the session's own + window, and a client's follows them only through its core (the scene + effects do; the font does not). `Fonts` reads the machine's font + directories untaped, so its list is the session machine's. +- **An EffectCode's sources differ by backend** (Vulkan or GL): a client of + another build's window reads the session's. +- **A terminal's client draws a window session's pictures as cells**, never + through kitty graphics (no shm across machines). +- **Adopt and a terminal reader's failure write the core untaped** (above): + a client replaying them would diverge and join again. +- **A rejoin opens a new view**: the old one's place, selection and scroll + are the session's to keep, and it lets the old view go. +- **A hit test reads the live view**, which `within` makes the client's for + its own events; a frame chore outside one (a pointer's hover after a + unit moved the frame) reads it as the unit left it. +- **A window client has no SIGHUP to quit on**: its ssh's end is the link's, + read as a hangup. +- **One window a client**: a session's second window through one client + would be a second client. -- cgit v1.3