summaryrefslogtreecommitdiff
path: root/docs/next-daemon.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/next-daemon.md')
-rw-r--r--docs/next-daemon.md232
1 files changed, 232 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md
index 0fe72b76..5039c81e 100644
--- a/docs/next-daemon.md
+++ b/docs/next-daemon.md
@@ -2312,3 +2312,235 @@ Not done, and why:
9p(1) is still one round trip per message (1 s for a read at 207 ms).
A python helper for remote scripting could pipeline the same way;
nobody scripts that way yet.
+
+## Phase 6: predicted echo notes
+
+Built 2026-10-30 (`src/echo.zig`; hooks in `src/replica.zig`; a field on
+the core and one call at the end of `body_layer.renderBody`; `zig build
+replicas -- --echo`). Transport-free like part B: proven in part A's
+in-process harness, carried by the remote client. A key typed into a
+terminal pane goes to the authority, and its echo comes back as a delta a
+round trip later: 207 ms a character in a shell on the FreeBSD box. The
+replica now draws it at once, mosh's way, and the authority's screen
+confirms or takes it back. Decisions at the forks, with the ponytail lens:
+
+- **Presentation, the replica's own.** The overlay is `Replica.echo`; the
+ core points at it (`Pardes.echo`, `.local`, and in rollback.zig's
+ `unsaved`, so the copy neither saves nor puts it back). No digest, dump
+ or tape sees it, and the core's emulator stays the authority's. Its
+ only write into what is drawn is `Echo.paint`, at the end of
+ `renderBody` for a terminal pane: the cells predicted and the cursor
+ after them, over the body as drawn. A terminal's body is painted
+ straight onto the grid (a body layer is a file's with context rows),
+ and the tty and the GUI both draw the grid's cells and cursor, so both
+ get it. A session's own core has `echo` null: one null test a terminal
+ pane a frame, and no overlay.
+- **What is predicted:** a printable ASCII character at the cursor,
+ Backspace, Left and Right, typed into the view's terminal in tty mode
+ (keys going to its program), on the primary screen, at the live bottom,
+ with the cursor shown. Never for a chord, Enter, Tab, Esc, Up and Down,
+ a paste, or anything on the alternate screen (vim never sees one). More
+ narrowly, so as never to draw what the line editor would not:
+ - a character only over a blank cell or the same character (typing
+ along a fish suggestion); a line edited in its middle, or a
+ suggestion left, is the shell's to redraw;
+ - not in the last column (wrap is the program's);
+ - Backspace only at the end of the line, over a prompt's input or a
+ predicted character; Left over the same; Right over typed text, a
+ prompt's input in the colour of the cell before it (past the text's
+ end fish's Right takes its suggestion).
+ Each prediction is a cell (an absolute row, the authority's numbering
+ that the delta's header carries) and the cursor after it; a newer key's
+ cell replaces an older one's, as mosh's overlay does.
+- **Judged once the authority has the key and its echo has had time.**
+ Each unit of the replica's own says which of its keys the authority
+ stepped (`Echo.confirmed`). A stream that loses nothing keeps the order
+ the authority sent in, and it sends what it owes of the terminals
+ before it steps an input, so a delta that arrives after that unit was
+ made after the key was written. 50 ms after the unit (`grace_ns`,
+ mosh's ECHO_TIMEOUT: the shell's echo, then the authority's next frame)
+ each applied delta judges it: a cell the screen shows goes (confirmed),
+ one it does not is a misprediction and every prediction goes. A
+ predicted space (Backspace's too) is judged neither way, as mosh's
+ blanks are; the cursor after the newest key is judged with it. With no
+ delta at all (nothing changed: no echo), a frame judges it 250 ms
+ later (`stale_ns`).
+- **A key that is not predicted** (Enter, Tab, a chord, or one the rules
+ above refuse) is the next to wait for: once the authority has it, every
+ prediction made before it goes, judged neither way (the deltas from
+ then show that key's doing, which nothing predicted). The keys typed
+ behind it wait (`deferred`) until its grace has passed; then those the
+ authority does not have yet are predicted, in order, over the screen
+ that shows its doing (`catchUp`). One the authority has whose grace is
+ not over puts that off a little. So the characters typed straight on
+ after Tab are drawn where the completion left the cursor once it shows
+ (a round trip and 50 ms after Tab), the rest at once, and never where
+ the cursor was before it.
+ Found by the harness: the first version predicted nothing until the
+ wait was over, and every key typed in that time became a new wait, so a
+ word typed after Tab or Enter at 207 ms was all late (p90 242 ms). An
+ input that is not a key into this terminal (a click, a command) has no
+ deferral: where the keys after it go is not known here until the
+ authority has it.
+- **Shown where the echo is vouched for.** At a shell's prompt, pardes's
+ OSC 133 marks (phase input: a B and no C since) and the cursor's own
+ semantic content say its line editor echoes: drawn at once. Elsewhere
+ (`cat`, a shell without pardes's marks) only once an echo was confirmed
+ there since the last Enter, Tab or chord (`trusted`), so the first
+ character of each line waits a round trip. A key before the last one
+ not predicted vouches for nothing after it: the harness found the
+ characters of `sudo ls`, confirmed after its Enter, vouching for the
+ password prompt that Enter brought up. After a misprediction that was
+ drawn, nothing is drawn until an echo is confirmed again (`doubt`). A
+ password prompt or a program that ignores what is typed confirms none,
+ so nothing typed there is ever drawn.
+- **Underlined off a prompt only.** At a prompt the marks vouch for the
+ echo, and an underline trailing every character for a round trip at
+ 207 ms is noise; off one the trust is mosh's inference, and the
+ underline says so. After a misprediction nothing is drawn at all, which
+ mosh's adaptive underline approximates.
+- **No protocol change.** No echo acknowledgement crosses (mosh's
+ `echo_ack`): the replica's own units stand for it, and the grace for its
+ 50 ms. No termios flag crosses either: a program's echo is inferred from
+ confirmations, as mosh does.
+
+The hook for the remote client (its `Replica` and stream as they are):
+- `Replica.init(..., screens = true)` points its core at its echo
+ (`core.echo = &r.echo`). A replica made another way (the remote line's
+ `initDump`) does that itself once its core exists.
+- Per key: nothing more. `r.input(ev)` predicts after its settle, in
+ `r.view`.
+- Per unit: nothing more. `r.confirm(unit)` tells it which of its keys the
+ authority has.
+- Per delta: nothing more. `r.screen(msg)` judges after each delta it
+ applies.
+- Per frame, before drawing: `if (r.echoFrame()) dirty = true;` judges
+ what is stale, predicts the keys deferred whose wait is over, and says
+ whether the overlay changed since the last call; `r.echo.changed` says
+ the same between frames (after `r.input` and `r.screen`), for a client
+ that draws only when its state moved (the remote line's `moved`).
+- Draw its own view (`core.view == r.view`): the overlay is drawn in no
+ other, and over a terminal in tty mode only.
+- The clock is the monotonic one (`FrameStats.nowNs`) unless `r.echo.now`
+ is set (the harness's virtual clock).
+
+Measured.
+
+- **The harness** (`zig build replicas -Dplatform=tty -- --echo`): one
+ authority and one replica over part A's delayed, jittered link, the
+ authority's pty a shell played in the harness (`FakeShell`): a line
+ editor at a prompt with pardes's marks and Tab completion, and the
+ programs the corpus runs in it. Each key's echo comes 2 ms after the
+ authority writes it. The client types a corpus of 222 keys at a
+ typist's pace (60 to 180 ms a key) and in bursts (12 to 60 ms): lines at
+ a prompt, Backspace, Left and Right, Tab typed straight on, `sudo` and
+ its password, vim, a program that ignores what is typed, `cat` (the
+ kernel's echo, no marks), and a line typed before the last one's prompt.
+ Each client frame (60 Hz, its own phase) is what its screen shows: its
+ core rendered, the overlay where it is drawn. Ground truth is the
+ authority's screen right after each key's echo.
+- **Key to its character on the client's screen** (the simulation's clock;
+ 20 seeds, 3060 keys the shell echoed at each RTT, ms, without → with):
+
+ | | 30 ms | 80 ms | 207 ms |
+ |---|---|---|---|
+ | p50 | 49.8 → 8.7 | 102.3 → 8.7 | 239.0 → 8.9 |
+ | p90 | 59.0 → 15.2 | 111.8 → 15.4 | 247.9 → 15.8 |
+ | max | 66.9 → 65.3 | 121.5 → 114.5 | 261.7 → 251.6 |
+
+ With it, a key waits for the client's next frame, 0 to 16.7 ms. The tty
+ host draws an input's frame at once, so a real client's is the frame's
+ cost. The tail is by design: at 207 ms the p90 of the characters typed
+ straight on after Tab is 38 ms, of a line typed ahead of its prompt
+ 48 ms, and of `cat`'s 179 ms (its first characters of a line wait for an
+ echo to be confirmed); every other part's is 14 to 15 ms.
+- **Accuracy** (the same runs, 4440 keys at each RTT): 3718 to 3720
+ predicted (84%); 714 to 722 not, by the rules (each Enter, Tab, Ctrl-C,
+ Ctrl-D and Esc, everything typed in vim, and the characters behind a
+ key not predicted that the screen showed by the time it was over). Of
+ those predicted, 3238 to 3240 were what the authority's screen showed
+ right after the echo; the other 480, at each RTT, are exactly the
+ password's and the ignoring program's 24 a seed, and none was drawn.
+ Wrong characters drawn: none, at every RTT (0 keys, 0 frames). Frames a
+ password's or the ignoring program's key was drawn: 0. vim's keys
+ predicted: 0. The overlay judged 97 to 132 cells against the screen as
+ mispredictions, all of them undrawn ones (the password's, the ignoring
+ program's), and no cursor. Every frame drawn with a prediction shown
+ (13,083 to 21,009 a cell) had each predicted cell where it was
+ predicted in the rendered surface.
+- **Costs** (ReleaseFast): `paint` p50 50 to 63 ns, p99 86 to 155 ns; the
+ replica's render with a prediction shown p50 54 µs; a key's `typed` is
+ a few array scans.
+- **No divergence**: the replicas harness (ReleaseFast, 20 seeds x 120
+ inputs x 3 clients): none diverged, none unequal, 23,547 deltas checked
+ and none wrong; its deltas a second (76.3, 75.7, 71.7) are part B's to
+ the decimal.
+- **No local regression.** A session's own core draws no overlay
+ (`echo` is null: a unit test says the authority's core has none).
+ `pardes-perf-live --live` (base's driver), main (vtzpkxwu) and this
+ line interleaved A B A ... A on the perf cores (3 runs of the new one, 4
+ of main), ReleaseFast; the median of the runs' p50s, new/main:
+
+ | | new/main | A/A (main) |
+ |---|---|---|
+ | key-down, present / core | 0.99 / 0.99 | 1.00 / 0.99 |
+ | key-right | 0.99 / 1.00 | 1.00 / 1.01 |
+ | edit-char | 0.97 / 0.98 | 0.99 / 0.98 |
+ | page-down | 0.85 / 0.92 | 0.82 / 0.85 |
+ | wheel | 0.97 / 0.99 | 0.98 / 0.98 |
+ | `yes \| head -c 32M` wall | 1.11 | 1.04 |
+ | a 1M-line open | 0.93 | 1.01 |
+
+ Every cell's runs overlap main's. The `yes` cell is the kernel's (Tty
+ throughput notes): main's own runs read 4.5 to 7.1 s in the A/B and 5.8
+ to 7.6 s in the A/A, this line's 5.0 to 7.2 s. What the local path
+ gained: a null test a terminal pane a frame, and 8 bytes of core.
+
+The gates:
+- Unit tests (`zig build core-test -Dtest-filter=echo`): keys typed at a
+ prompt drawn at once in the rendered surface, unflagged, the cursor past
+ them, then confirmed by the echo, Backspace too, and the replica's digest
+ the authority's; a password prompt draws nothing typed and lets it go
+ when stale, and vim's alternate screen predicts nothing; a misprediction
+ takes every prediction back and hides the next until an echo is
+ confirmed, and after Tab the keys behind it are drawn where the
+ completion left the cursor, or not at all if the screen already shows
+ them.
+- `zig build replicas -- --echo` fails on any divergence, unequal end,
+ wrong delta, drawn password or ignored key, predicted vim key, or cell
+ rendered otherwise than predicted; it passes at 20 seeds, Debug and
+ ReleaseFast. `zig build replicas` passes at 20 seeds, ReleaseFast (and 4
+ in Debug).
+- Unit tests tty (`zig build unit-test -Dplatform=tty`, its perf gate
+ too), the full `core-test`, and the 113 snapshot scripts pass; the GUI
+ build's echo tests pass (`core-test -Dplatform=gui`).
+
+Not done, and why:
+- ASCII only: a width table would let the rest of Unicode in (`kindOf`).
+- A line edited in its middle (insert, Backspace), Delete, Home, End, the
+ readline chords, word moves and a paste are not predicted: the line
+ editor redraws what is right of the cursor, which a prediction would
+ have to guess. Each waits a round trip, and the keys typed straight on
+ behind it are drawn when it is over.
+- A key typed after an input that is not a key into this terminal (a
+ click, a command) and that the replica could not apply itself waits for
+ the authority, and so do the keys after it until a pause: where they go
+ is not known here until the authority has it.
+- The echo is inferred, not told. No termios flag and no echo
+ acknowledgement cross. A password prompt is safe because nothing typed
+ there is ever confirmed. A shell at its prompt that does not echo a key
+ (zsh's vi command mode) has it drawn until its grace passes, about a
+ round trip and 50 ms, and then nothing more until an echo is confirmed;
+ so does a program that turns echo off mid-line in `cat`'s plain echo.
+- An echo later than about 30 ms on the authority's host (a loaded box)
+ makes a drawn character go when judged and come back with the echo: a
+ flicker, never a wrong character. The grace could follow the measured
+ echo delay.
+- A shell without pardes's marks (fish's own marks, a shell started
+ without the integration) is trusted only by confirmation, so each line's
+ first character waits a round trip, as in `cat`.
+- The GUI was not run: it draws the grid's cells and cursor that the
+ harness checks in the rendered surface, and its build compiles and
+ passes the echo tests.
+- The remote client (the other line) wires it: `initDump`'s core, the
+ frame hook, its `moved`.