diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-29 23:05:05 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-29 23:05:14 -0300 |
| commit | 2d86687b98f389232b213dfa67cfa731b0280fbb (patch) | |
| tree | 1c8f4455f864325853ca488298e9329e3c44f18a /docs/next-daemon.md | |
| parent | 77c4a6e346e08538abc410f85a86bec7e8dbedb3 (diff) | |
| download | pardes-2d86687b98f389232b213dfa67cfa731b0280fbb.tar.gz pardes-2d86687b98f389232b213dfa67cfa731b0280fbb.zip | |
docs/next-daemon.md: Phase 5 part B terminal notes: what crosses and where in the stream, the authority's steps batched, deltas in flight against the version last sent, the replica's terminal the authority's to the row, what a step reads sent before it, and the numbers
ReleaseFast, 20 seeds of three clients at 30, 80 and 207 ms, the shell running a TUI, a session with clears and 8 MB of yes: no divergence, every terminal the authority's at quiescence and 23,508 deltas each the authority's screen at its version (and with a filled heap). Under the flood 72-76 deltas a second a replica (one in flight would be 4.8 at 207 ms), 10 KB/s of deltas and 101 KB/s of units a peer, encode a frame 15-16 us at three peers and 13-15 at one, apply 34-37 us p50. Bench 200x60: yes 65 KB/s a peer, apply 65-72 us (was 2.4 ms); varied text 356 KB/s, apply 0.47-0.49 ms. Local A/B against main within its runs; against base page-down and wheel are main's since. What is not done: kitty images, the units' bytes under a flood, the first text-mode step after a flood sending its history, a stale view slot the rollback copy follows (part A's), echo prediction.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs/next-daemon.md')
| -rw-r--r-- | docs/next-daemon.md | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md index 0f3a494c..c7cb719d 100644 --- a/docs/next-daemon.md +++ b/docs/next-daemon.md @@ -1568,3 +1568,230 @@ table; a table once per store file would shrink both, a change to the store's format left until a close's cost matters. The live keystroke cells were not run (perf rule: `--live` only for a change to terminal output); a dump is off the hot path. + +## Phase 5 part B terminal notes + +Built 2026-10-29: screen-state terminals wired into the replicas +(`src/screen_state.zig`, `src/replica.zig`, `src/tape.zig`, +`src/terminal.zig`; `zig build replicas`). Transport-free: bytes in, bytes +out, proven in part A's in-process harness; the remote agent's stream +carries them. Decisions taken at the forks, with the ponytail lens: + +- **What crosses.** The authority's units, as in part A, but a pty's + output is recorded without its bytes. Then, per peer, its terminals' + messages. Each one is u8 pane, u32 the pane's serial (a slot's next pane + is another), u8 kind, and the kind's bytes: + - to a replica (the remote's 0x06): 1, a delta; 2, rows (`encodeRows`); + - to the authority (0x04): 1, an acknowledgement (u32 seq); 2, a request + for rows (u64 lo, u64 hi, absolute); 3, a delta refused: start this + terminal afresh. +- **Where they go in the stream.** Each replica steps every unit on its + own core, and a step in a terminal pane reads the emulator (rows, + cursor, modes, marks). So before the authority steps any input that is + not a pty's output, and once a frame, it sends a peer its own steps since + the last unit (`Authority.pending`, below) and then what the peer is owed + of the terminals (`Screens.flush`); after a step that read a terminal's + history, before its unit, the rows the peer lacks (`Screens.fill`). A + replica takes them in that order between units, and a step it replays + reads the terminal its authority's step read. Nothing goes after an + output step: a flood is paced by the frame rate, not by pty reads. +- **The authority's own steps are batched.** One unit a pty read was + 2000 units a second under `yes`: each rolled back every replica that had + pending input, and each carried a digest of one word a field, about + 12 KB (28 MB/s a peer). `Authority.output` steps into an open batch + without a digest; `pending` sends the batch as one unit with one digest, + before any other input is stepped and once a frame. Under screen state a + digest is one word (the harness's trace mode keeps the fields, to name + one). Units under the flood went from 28 MB/s to 0.1 MB/s a peer. +- **Several deltas in flight, against the version last sent.** Each state + sent is a version of its terminal (`Track`), made once for every peer: a + hash of each active row, the TERMINAL record, and what pardes keeps of + the stream (the OSC 133 marks, `terminal.marksOf`). A peer's delta is + against the version it was last sent. The stream is ordered and loses + nothing, so the peer has that one by the time it applies the next, and + the replica holds exactly that version's blobs. Up to 32 are in flight (13 + at 207 ms and 60 Hz). A peer at the bound gets nothing until an + acknowledgement frees room, then the newest version, the ones between + skipped. Peers at the same base get the same bytes (one encode for all). + A delta against a base the replica does not have (one lost, or it started + afresh) is refused, and its acknowledgement asks for a reset. + - Rejected: mosh's base at the last *acknowledged* state with a + throwaway number. On a stream that loses nothing it only makes deltas + bigger and the replica keep more. +- **The replica's terminal is the authority's, to the row.** + - Its history is exactly as long as the authority's: no byte limit of its + own, trimmed to the authority's count at each delta. Row numbers and + the scrollbar then say the same on both sides, which steps read. + - It takes the authority's viewport, its cursor's semantic content (a + prompt's input, which `promptInputReady` reads) and its marks. + - Its emulator is written by `apply` and fetched rows alone. A replica's + core never ingests, resizes (the authority sizes it; a resize's own + core work, its pointer selections cleared, still runs) or replies to + its program; its pty writes are off the tape on both sides. + - No digest covers an emulator under screen state (`State.digest`); the + harness compares screens instead. +- **What an ingest tells pardes is taped.** Over a terminal, pardes keeps + positions: the text-mode cursor, selections, the edit copy, the pointer's + rows. An ingest moves them when it prunes or erases history or clears the + screen. The authority records what it told them (each tracked row's row + after it and whether it was erased, the clear, whether the pages lived: + `Site.positions`); a replica, which ingests nothing, takes that, and the + rest of the logic runs alike on both. +- **History a step reads is sent before its unit.** Scrolled past more than + a screen at once between deltas, rows are holes on the replica, blank + until fetched. A step in text mode reads a terminal's whole grid, and + the replica's replay of that step must read what the authority's read, + which a fetch an RTT later cannot give. The authority keeps each peer's + holes as the replica does (`Peer.holes`, from what it sent), and after a + step that read a terminal's rows (`State.read`, set outside the render) + sends each peer those it lacks, before the step's unit (`Screens.fill`). + A history row never changes, so each goes once. Scrolled into view, holes + are blanked and asked for (`Replica.screenRequest`); the answer fills + them an RTT later. +- **A flood costs the replica a counter, not its rows.** When a delta + scrolls more than the replica's screen and history hold, nothing it + holds is in the new state: its rows stay where they are, renumbered, the + active ones and the tail written from the delta, the rest holes. Growing + and trimming a history's rows one by one was the 2.4 ms a `yes` delta + took. +- **Speculation stays off terminals.** An input whose live pane is a + terminal is not speculated: its step reads the emulator, the last + delta's here and the pty's newer one there. It waits for the authority + (a key in tty mode already did, at its pty write). Phase 6 predicts the + echo. +- **Rollback never brings a terminal's past back.** + - The rollback copy never held an emulator (State is skipped), and a + replica's emulators, their State included, are allocated on the C heap, + outside its rollback epoch (`terminal.emulator_gpa`, `State.gpa`). + Deltas write them while a copy is held, and nothing of them is a copy's + to save, keep or put back. Without that, a rollback freed a delta's + pages (the test below crashes). A first fix, the epoch paused while a + delta was written, was not enough: the copy also saved emulator memory + reached through a stale pointer (below), and put its old bytes back. + - The core's cache of a terminal's rows is marked stale after a delta, + dropped when a copy is taken and emptied when one is put back: it is a + grid's worth of text, and the copy's would be of an older grid (without + the mark, the test reads it). + +Found on the way: +- **A view's slot that is live is stale, and the copy follows it.** views.zig + keeps a parked view's share as copies, stale while that view is live + (a column tag's text, `Text.own`, freed by the live view since). The + rollback copy walks every slot: a stale pointer that lands on a live + allocation saves it, and a rollback puts its old bytes back. Part A was + safe while every free under a held copy was put off, which holds again + now that a delta's writes are outside the epoch. A ReleaseFast harness + run found it (heap corruption after 20 seeds), a safe build's check that + named what was freed under the copy pinned it. ponytail: the copy still + follows the stale slots; skipping the live view's slot diverged (part of + it is read), and is the next fix in views.zig, not here. +- A pane's `cwd` inherited from a terminal's pane is a pointer, and the + walker follows it: a digest of a pane next to a shell digested the + shell's emulator. It mattered when a digest was taken outside the + authority's tape (`pending`'s first version). +- `resizeGrid` does core work before it resizes (the pointer selections + of a narrowed terminal): skipping it whole on a replica diverged. + +Measured. Correctness ran beside builds; the timings alone on the perf +cores (ReleaseFast). + +- **Correctness.** + - The soak (unit tests, and the 197 recorded streams at 3 seeds): several + deltas in flight, landing late and in order, one in 50 lost (refused, + then a reset), random resizes and fetches. After every delta the + replica's screen, history extent and viewport are the authority's as + encoded, and every history row it holds outside its holes is the + authority's. None failed, Debug or ReleaseFast. + - `zig build replicas`: three clients typing in their own views over + 30, 80 and 207 ms links while the shell runs a TUI, a shell's session + with clears, then 8 MB of `yes` read 4 KB at a time. In ReleaseFast, + 20 seeds at each RTT, there was no divergence, every replica's digest + and every terminal at quiescence was the authority's, and each of the + 23,508 deltas applied matched the authority's screen at its version. + The same held in Debug: 4 seeds at each RTT, and 20 at 30 and at + 80 ms; and in ReleaseFast with every replica allocation filled with + 0xff (`PARDES_REPLICA_FILL`), 20 seeds at each RTT. +- **The terminals in the harness** (ReleaseFast, 20 seeds, three clients; + a peer's numbers while the flood runs): + + | | 30 ms | 80 ms | 207 ms | + |---|---|---|---| + | deltas a replica applied a second | 76.3 | 75.7 | 71.7 | + | delta bytes a second | 10.3 KB | 10.5 KB | 10.0 KB | + | unit bytes a second | 101.6 KB | 102.0 KB | 101.5 KB | + | encode a frame, every peer, p50 / p99 | 15 / 36 us | 16 / 42 us | 16 / 31 us | + | the same, one peer | 13 / 28 us | 14 / 30 us | 15 / 30 us | + | apply a delta, p50 / p99 | 37 / 494 us | 35 / 442 us | 34 / 400 us | + | rows fetched on demand, all runs | 1103 | 649 | 786 | + | rows sent before a step that read them, all runs | 18.0 MB | 18.5 MB | 10.0 MB | + + One delta in flight would have been one an RTT: 4.8 a second at 207 ms. + The rate is the frame's (60) and the inputs' (a delta before each). +- **The bench** (`PARDES_SCREEN_STATE=<dir> zig build core-test + -Doptimize=ReleaseFast -Dtest-filter=screen_state`, 200x60, the floods + under the C allocator): + - encode a version, every row new: p50 273 us, p99 394 us, 29.8 KB; + nothing new: 71 / 95 us, 549 bytes; + - `yes` at 19-20 MB/s: 63 deltas a second, 65 KB/s a peer (1038 bytes a + delta), encode a frame 28 us at one peer and 29 at three, apply p50 65 + to 72 us and p99 202 to 265 us (it was 2.4 ms); + - varied text at 59-64 MB/s: 356 KB/s a peer, encode a frame 52 / 54 us, + apply p50 468 to 493 us. +- **Part A's costs, with terminals** (the harness, three clients): + speculative apply p50 28 to 42 us; copy p50 95 to 151 us (1.3 to 1.5 + MB); rollback p50 331 to 442 us, p99 1.6 ms at 80 and 207 ms. At 30 ms + the copy's p99 is 7.8 ms and a rollback's 17 ms: a register holding a + terminal's whole grid (`%` then `y` in a shell's text, 2 MB after the + flood) is copied whole by every speculation. Registers could be pinned + as file texts are; left as found. +- **No local regression.** `pardes-perf-live --live`, A and the new tty + interleaved A B A ... A (4 runs of the new one, 5 of A) on the perf cores; + the median of the runs' p50s, new/A, present and core: + + | | against main (kuovmsxw) | against base | A/A (base) | + |---|---|---|---| + | key-down | 1.02 / 1.02 | 0.94 / 0.94 | 1.00 / 1.01 | + | key-right | 1.02 / 1.03 | 1.00 / 0.95 | 0.99 / 1.01 | + | edit-char | 1.01 / 1.00 | 0.99 / 0.99 | 1.00 / 1.00 | + | page-down | 0.92 / 0.95 | 1.22 / 1.05 | 1.00 / 0.99 | + | wheel | 0.83 / 0.85 | 1.13 / 1.10 | 1.00 / 1.00 | + | `yes \| head -c 32M` wall | 0.92 | 1.12 | 0.94 | + | a 1M-line open | 1.03 | 1.14 | 0.97 | + + Against main, this line's own A/B, every cell's runs overlap main's. + Page-down and wheel against the base read 1.21 and 1.12 in an earlier + run too, and 0.92 and 0.83 against main: main's since the base, not + this line's. What the local path gained: a counter a pty read, a resize + and a scroll; a flag a frame and a store when rows are built; and, for a + terminal with positions over it, a taped value (a null check) and two + stack arrays. + +Not done, and why: +- Kitty images in terminals still do not cross. +- Units under a flood still cost about 0.1 MB/s a peer: an output step is + about 45 bytes of tape (its input, the pump, a host call), 2000 a second. + Phase 6's zstd takes most of it (each step's records are alike); or a + host could feed a pane's queued reads to the core as one. +- The first step in text mode after a flood sends its terminal's whole + history of holes, up to a few MB, ahead of its unit (ponytail: a step + reads every row, its motion surface). +- A 9P run waiting on a replica's marks (`noteMarks`) reads them from the + last delta, not from the output step; its writes are the authority's, but + `sent_command` could differ. The output pins (`out_start`, `out_end`) + stay the authority's. +- Text reads outside `buildRows` (a pointer selection's copy in tty mode, + 9P's screen reads) do not ask for the rows; 9P's are the authority's + anyway. +- **A hazard for part A, not fixed here.** The rollback copy follows a + view's stale slot (above). If a stale pointer lands on a live allocation + that a speculation then writes in place, the rollback puts the old bytes + back over that allocation's new owner. Emptying a slot's pointers when + its view goes live (views.zig `unpark`) would end it; the copy skipping + the live slot instead diverged, so part of it is still read. +- Echo prediction (phase 6): a key into a terminal waits a round trip. +- A replica steps every output step of the authority's (bytes-less), about + 2000 a second under a flood, each a core step. +- The GUI was not measured: its host is unchanged, and the core's terminal + path is the tty's. +- The other agent wires it in: the tty and GUI hosts, `Screens` per + attached peer, and a replica frontend drawing after `screen`. |
