summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/next-daemon.md319
1 files changed, 319 insertions, 0 deletions
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=<socket>:<name>` and `--attach=<host>:<name>` (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=<name>` (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.