summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-30 18:21:15 -0300
committerGabriel Schneider <[email protected]>2026-10-30 20:25:56 -0300
commite2d74d9160a491d270b271904d5c4338dd203cf9 (patch)
tree649838996858a091a53df9d64476431ee6648198 /docs
parent2fb0d38b1e233d8ccba0f185bc7c8acec94234e8 (diff)
downloadpardes-e2d74d9160a491d270b271904d5c4338dd203cf9.tar.gz
pardes-e2d74d9160a491d270b271904d5c4338dd203cf9.zip
docs/next-daemon.md: phase 6's instant interaction notes: what stopped each input, counted by name; pardes's own steps over a terminal speculated (H14), its view moved here and put back on a rollback, applied again over each delta; a pane's teardown no stop; the echo's lost predictions waiting for their keys; the authority's yes or no guessed; an input's time its client's; mosh's rules checked; before and after per action class at 0/30/80/207 ms and through the box, the soak's blink, the replicas harness; what is left
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs')
-rw-r--r--docs/next-daemon.md220
1 files changed, 220 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md
index 74930734..b1ee51d5 100644
--- a/docs/next-daemon.md
+++ b/docs/next-daemon.md
@@ -4134,3 +4134,223 @@ before it.
then `test/daemon.py` 20, `--far`, `--window-clients`, `--manage`, `--gui`
5, `--upgrade` from Debug and `test/fs.py` against ReleaseSafe builds. All
pass.
+
+## Phase 6: instant interaction notes
+
+Built 2026-10-30 (`src/replica.zig`, `src/tape.zig`, `src/terminal.zig`,
+`src/echo.zig`, `src/detached/wire.zig`'s `stamp`, one line in
+`src/pardes.zig`; PARDES_TEST_LATENCY's `I` and `U` lines in
+`src/gui/gui.zig`). The user: "make sure to use the mosh
+tricks so that user interaction to type/scroll/move the cursor feels
+instant specially when they don't require a request going to the daemon",
+and "measure it too since I don't want to catch those myself". The
+measure is test/soak.py's `instant` mode (the hunter's, per action class
+against a local session's own frontend) and a bench of my own that says
+what stopped each input (`.scratch/daemon/instant/harness/classes.py`).
+Decisions at the forks, with the ponytail lens:
+
+- **What stopped an input is counted by name.** A speculation that
+ meets a host call, a site or a poison records which (`Tape.poisoned_by`),
+ and the client's PARDES_REPLICA_STATS line ends `stops name:n,...`
+ (PARDES_REPLICA_TRACE says it with the input). Every number below that
+ says why an input waited comes from it.
+- **pardes's own steps over a terminal are speculated (H14).** Until now
+ every input of a client whose keyboard was in a terminal waited a round
+ trip (`a terminal has the keyboard`): normal-mode keys over its history,
+ the wheel, Ctrl-u. The blanket poison goes. What reaches the program
+ (a key in tty mode, a paste, a mouse report) is a pty write, a host
+ call, and stops as before; the predicted echo covers it. The rest reads
+ the emulator and may move its view:
+ - **Its view moves here.** A screen-state replica's speculation may
+ scroll a terminal (`terminal.viewOnly`: `scrollGrid`, `followOutput`);
+ nothing else of an emulator. The rollback copy holds no emulator, so
+ the replica keeps each terminal's view as the copy was taken
+ (`Replica.views`), a delta sets it the authority's, and a rollback
+ puts it back, between the units it replays in the order the deltas
+ came among them (a delta's view comes after the units it shows: a
+ neutral unit of another's that scrolled, replayed over it, scrolled
+ twice; the harness's per-delta check found it).
+ - **Applied again over each delta.** What it did depends on the
+ emulator, here the last delta's and there what the pty said since.
+ The stream sends a client its terminals before the authority steps
+ any input and the rows a step read before its unit, so a speculation
+ over a terminal (`Pending.terminal`: it read a terminal's rows,
+ moved a view, or a terminal had the keyboard) is put back and applied
+ again over each delta or rows that come while it waits
+ (`overTerminals`): when its unit comes it read the emulator the
+ authority's step read.
+ - **No digest in a speculation.** A first version kept a terminal
+ speculation's digest to check its unit's against; but a blob born
+ under the copy and digested keeps its word past the epoch's free of
+ it (src/walk.zig), and a later blob at that address read as it (the
+ harness's Debug blob check, seed 11 at 207 ms). Gone: it is confirmed
+ by its records, as any speculation is.
+ - **Never kept to replay later.** A unit confirmed on the fast path
+ with more applied on top is kept in `since`, to replay at the next
+ rollback, over the deltas that came after it. One over a terminal is
+ taken at once instead, over the emulator its step read, and those on
+ top applied again.
+ - Closing a terminal stops (`retirePane`: its pty's end is the
+ authority's); the blanket poison had covered it, and the in-process
+ harness's host has no `close_pty` to stop at.
+ - Found on the way, others' to fix and fixed in main since: with more
+ of a terminal's steps speculated, the replicas harness met H18 more
+ often (a client typing at another size than the last typist: the
+ session's emulator reflowed inside the step, the rows sent for the
+ replicas' holes came renumbered, their replay read blanks; seeds 10,
+ 11 and 17 at 207 ms, `pane 0.ovl`, `pane 0.sel_snap`). Main met it too
+ (seed 53 of 60 at 207 ms). Fixer 1's `resize_to` and fixer 2's `read`
+ through the rows cache (wwkwwlzt, tysmmuzx) fix it: on them, 20 seeds
+ at each RTT, none diverged.
+- **A pane closes in a speculation.** `deinitEmulator` asked the authority
+ before it looked for an emulator, so the reap after any close (a file's
+ pane, a picker's, a preview's) stopped the input after it: 4 of the
+ finder's 6 stops.
+- **The authority's yes or no is guessed (mosh's way).** Fixer 2's
+ `tape.authority` makes a step that reads what only the authority holds
+ wait for it: whether a script reads a pane's events, which every Look
+ and click's command asks, put every Look a round trip late. A bool
+ answer is now guessed in a speculation from the authority's last answer
+ to the same question (`Tape.answers`, filled as units replay), recorded
+ as the answer, so its unit confirms the guess or rolls it back. Lists
+ (the closed panes the Panes picker shows, Recent) change with what the
+ user does and are still asked: opening the Panes picker waits a round
+ trip (its typing does not).
+- **An input's time is its client's.** A speculation guessed the
+ session's clocks (`Tape.guess`: the last unit's reading, the time since,
+ a round trip), and a step that read one recorded the guess; the
+ authority read its own, so a message's millisecond (Ctrl-W's, a jump's)
+ always and an edit's second across a turn sometimes recorded otherwise:
+ a rollback each, which a window counts as seen (fixer 1: 1 to 8 a
+ minute, window clients worst). Now the input carries the guess (wire
+ 18's `stamp` frame before its event; `Pending.guess`, the same at every
+ reapply), and the authority's step reads it as its clocks (`Tape.stamp`,
+ `stampOf`; within a second of its own, else its own), so the two record
+ the same time. A message's linger is then off by the guess's error, tens
+ of milliseconds.
+- **The echo's lost predictions wait for their keys.** Found by measuring
+ at 207 ms: the shell's typing was predicted (24 of 26) and drawn almost
+ nowhere, key to output p50 65 ms. A drop with keys still in flight (a
+ delta that moved the screen's top, here the pty's resize at the first
+ key; or a misprediction) restarted the predictions at the screen's
+ cursor, where those keys' echo was about to land: every key after it was
+ judged wrong (5 of 6), and once wrong, nothing was drawn until an echo
+ was confirmed, which none could be. Now the keys typed after a loss wait
+ for the newest key in flight to show (`lose`, the `deferred` path keys
+ behind Tab take), then are predicted over it.
+- **mosh's rules, checked** (its source is in ~/05-genizah/mosh now,
+ src/frontend/terminaloverlay.cc `new_user_byte`): a printable character
+ (inserted, the rest of the row shifted right), Backspace (the rest
+ shifted left), Left and Right; CR moves the predicted cursor to the next
+ line, tentative; everything else (Home, End, Delete, Up, Down, any other
+ CSI or control) makes it tentative, nothing predicted. pardes predicts
+ the same less the mid-line insert and delete (a line editor redraws what
+ is right of the cursor; fish's suggestions mispredict a shift) and CR.
+ Nothing mosh does is missing that would raise the measured share: at a
+ prompt every letter is predicted.
+
+Measured. Before is main at uxwrlzlw with the counting (`base2`), after
+is this line on mqkxnsqu (`new2`; fixer 1's line between them changes
+none of what is measured here, and the line has since moved onto
+vplsqtyz); both ReleaseFast, unstamped, on the perf cores, the box's
+session the same build cross-compiled. The hunter's `instant` mode
+(test/soak.py, its xvmytsym copy pointed at my box directories): a
+class's 25 inputs a frame or more apart in one client, against a local
+session's own frontend measured in the same run. `at once` is the share
+that neither stopped nor showed later than half a round trip (a window's
+two frames).
+
+- **A terminal's history, by keys (Ctrl-b, k, Ctrl-u) and by the wheel**
+ (tty; at once, then key to output p99 ms; local p99 0.6 to 1.2 ms):
+
+ | | 0 ms | 30 ms | 80 ms | 207 ms | the box |
+ |---|---|---|---|---|---|
+ | term_scroll_keys | 0% 15.2 → 100% 1.1 | 0% 54.3 → 100% 1.5 | 0% 101.2 → 100% 0.9 | 0% 232.2 → 100% 0.9 | 4% 428.6 → 100% 1.4 |
+ | term_scroll_wheel | 0% 1.5 → 100% 0.6 | 0% 48.6 → 100% 0.6 | 0% 99.1 → 100% 0.6 | 0% 226.3 → 100% 0.6 | 0% 207.7 → 100% 0.6 |
+
+ The window client's, the same at once: 0% (4% on the box) → 100% at
+ every cell. (A window's p99 in this mode is the first frame after the
+ read, which a window draws whether or not the input waited: its at
+ once is the measure.)
+- **Shell typing at a prompt** (tty, p99 ms; every letter predicted
+ before and after, 25 of 25): 0.8 → 1.4 at 0 ms, 1.5 → 1.1 at 30, 0.8 →
+ 0.9 at 80, 49.0 → 27.7 at 207, 210.6 → 18.0 on the box. My own bench's
+ shell class at 207 ms (lines of `echo` and three words, Backspace,
+ Enter): p50 65 ms (main, ReleaseFast) → 1.8 ms (this line, Debug), the
+ echo judged wrong 5 of 6 → 0.
+- **Every file class stays at once** (type, move by keys and by click,
+ scroll by keys and the wheel, select, the picker's typing): 100% before
+ and after at every cell and on the box, tty p99 0.5 to 1.5 ms after
+ (a local session's 0.6 to 0.9; its wheel 48 ms, the glide).
+- The gate: `instant: pass` at 0, 30, 80, 207 ms and through the box
+ (before: 4 to 6 breaches a cell, each a terminal class's, 28 in all).
+- What stopped inputs, by name (my bench, 207 ms, before; `stops` in
+ PARDES_REPLICA_STATS): the shell's keys `pty_write` (their echo is
+ predicted), a terminal's history `scroll a terminal` 23 and `a terminal
+ has the keyboard` 3 of 27, the finder `close a terminal` 4 and
+ `preview` 2, a Look the authority's `readsEvents` 11 of 12 and
+ `resolve` (the first open of a file) 1, a Save `kind` (and then its
+ write), the Panes picker's opening the authority's closed panes; typing
+ in a file, moving, scrolling a file, selecting: none. After: the
+ shell's `pty_write`, the finder's `preview`, a Look's first `resolve`,
+ a Save's `kind`, the picker's opening.
+- **The soak's blink** (test/soak.py `local --minutes 2.5`, its gate,
+ a tty and a window client a cell at 0, 30, 80 and 207 ms, far):
+ before (`base2`) visible rollbacks 0.0 to 1.0 a minute, the window at
+ 80 ms 4.2 (13 in 3.1 min, a breach), mispredicted inputs 1 to 13 a
+ client, and that line's crashes and rejoins (fixer 1's since). Fixer 1's
+ own build, with them fixed: windows 2.2 to 2.7 a minute, ttys 0 to 1.3,
+ clock guesses all. The final line (this on xymsrmso): 0 visible, 0
+ mispredicted, 0 rejoins at every cell, tty and window; `soak: pass`.
+- **The replicas harness** (ReleaseFast, 20 seeds x 120 inputs x 3
+ clients): inputs that stopped 731/649/790 at 30/80/207 ms → 453/390/398;
+ confirmed on the fast path 6249/6246/5953 → 6695/6755/6753; mispredicted
+ 220/305/458 → 15/15/21; none diverged, none unequal (before, main at
+ uxwrlzlw: seed 9 at 207 ms unequal at quiescence, as main at vplsqtyz
+ still was).
+- **The final line** (this on xymsrmso, fixer 1's line): the gate at
+ 207 ms passes again, every class at once in both clients (tty p99 1.7
+ to 4.4 ms, a local session's 0.5 to 1.4 ms; shell typing 25 of 25
+ predicted, p99 28 ms); and through the box, every class at once in
+ both clients (tty p99 0.5 to 2.4 ms, a local session's 1.6 to 3.6;
+ shell typing p99 1.7 ms, 210.6 before).
+
+The gates (on the final line): Debug `core-test` tty, `unit-test` tty,
+`snap` 113/113, `replay` (20 seeds), `replicas` (4 seeds) and `--echo`,
+`test/daemon.py` 20 cycles, `--far`, `--window-clients`, `--manage`,
+`--gui`, `--upgrade`, `test/fs.py`: all pass; `core-test` gui and
+`unit-test` gui fail only main's two (the tag caret, the tagline pointer
+mapping). ReleaseSafe (`zig build -Doptimize=ReleaseSafe`):
+`test/daemon.py` 20 cycles, `--far`, `--window-clients`, `--manage` and
+`test/fs.py` pass. The new unit tests: a terminal's history
+by keys at once with a delta while they wait (replica.zig); keys still on
+their way when their predictions go (echo.zig); an edit's second across a
+turn confirmed on the fast path (replica.zig, which fails without the
+stamp).
+
+Not done, and why:
+- Opening the Panes picker and Recent wait a round trip (their lists are
+ the authority's, and change with what the user does); the finder's
+ preview reads the file it previews (a host call); a Save waits for its
+ `kind` site and then its write; the first Look of a pane waits once (no
+ answer to guess from yet). Each is one round trip, never wrong.
+- The first key typed into a shell scrolled back waits a round trip:
+ typing snaps the view to the bottom, but the key is a pty write and its
+ speculation, the snap included, is undone; the echo predicts only at the
+ live bottom.
+- Under the in-flight bound (32 deltas) a step can read a terminal state
+ the client was not sent: replayed, its unit diverges (a rejoin), as
+ another client's always could; a speculation of one is confirmed by its
+ records, so it is caught at the next digest a replay checks (fixer 1's
+ check when nothing is left on top), not at once.
+- A window counts every misprediction followed by a present as seen,
+ whatever it drew (a tty only one that wrote to its terminal): an upper
+ bound, now 0 in the soak.
+- A terminal's history is not fetched ahead of its view: a scroll back
+ (at once now) into rows a flood skipped shows them blank for a round
+ trip. Asking for two screens around the view diverged a replica in the
+ harness (seed 10 at 30 ms) before H18's fix, which may have been H18
+ met in the other order of events it made; dropped, not tried since.
+- The window's present is its frame (a software present in the test, up
+ to a frame): a prediction is drawn in the same pass as its key, so it
+ cannot come sooner than the window's own frame.