diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-29 17:01:35 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-29 19:21:09 -0300 |
| commit | c2b4f235e78735102c691677f08bd1b2403168df (patch) | |
| tree | 0c13bfe79fe79901bb47e1cb8e401440bd1e1f37 /docs | |
| parent | 97bb0e816513b805ca13358d8a14ba117f586403 (diff) | |
| download | pardes-c2b4f235e78735102c691677f08bd1b2403168df.tar.gz pardes-c2b4f235e78735102c691677f08bd1b2403168df.zip | |
screen_state.zig: a terminal crosses to a replica as its screen's state, ghostty's own records by content address, a delta a screen of row hashes and the blobs the peer lacks, history fetched by absolute row
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-daemon.md | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md index a39484b8..e3be6af8 100644 --- a/docs/next-daemon.md +++ b/docs/next-daemon.md @@ -648,3 +648,101 @@ Found and fixed 2026-10-29 (`src/tty/tty.zig`, `waitInput`). past its row's end ...`). A suite started as a shell's `&` job runs with SIGINT ignored, so four host_io tests whose Ctrl-C must stop a `sleep` fail there; started otherwise, they pass. + +## Screen-state terminal notes + +Built 2026-10-29 (`src/screen_state.zig`), a pure encode and apply pair +over byte buffers for the phase 5 stream; no transport yet. Only tests +reference it, so the tty and GUI binaries carry none of it: no symbol of +it is linked into the tty built from this tree. The local path's A/B, base +against that tty, is the Tty throughput notes' keystroke-to-present. + +- **Both kinds of blob are ghostty's own snapshot records,** not a cell + format of ours. The terminal-wide state (modes, colours and palette, + title, pwd, tab stops, mouse modes, scrolling region) is a TERMINAL + record. A row is the PAGE record of a one-row page the row is cloned + into, which carries its styles, graphemes, hyperlinks, wide cells, wrap + and prompt marks exactly. The replica decodes them with ghostty's + decoders and writes a row with `Screen.clonePartialRowGrowCapacity`. +- **A row's address is a hash of what it shows** (Wyhash of its flags, + its width and its cells by value), not of its blob: ghostty keeps the + source page's style ids when it clones a row, so equal rows give blobs + that differ. The width is in the address, because a blank row is the + same at every width. +- **A delta** is a header (cursor, kitty keyboard flags, the active + area's first row as an absolute row, the history's extent), the TERMINAL + record's address, an address for each active row, an address for each + row that scrolled off since the acknowledged state (the tail, up to a + screen of them), and the blobs for the addresses the peer does not hold. + An unchanged row costs 8 bytes. +- **One delta per peer is in flight,** against the state it acknowledged, + as FrameAck keeps one frame in flight for the tty. A slow peer skips the + states in between. The peer holds exactly the blobs of the state it + acknowledged, at most two screens of rows and the meta, so the authority + knows what it holds without asking. At 207 ms this means at most about 5 + deltas a second to the FreeBSD box; phase 6's predicted echo is meant to + cover typing there. +- **Absolute rows** come from a tracked pin at the last active top. The + rows scrolled since are the distance to the new top; if the pin's page + was pruned, the count jumps past every row the replica could hold. A + resize renumbers (an epoch), and the peer starts afresh. Scrollback is + fetched by absolute row (`encodeRows`, `applyRows`). +- **The replica writes into a ghostty Terminal,** a terminal pane's own, + so `src/terminal.zig` draws it unchanged. A test renders a replica's + terminal pane and its authority's in two cores: the bodies are equal, + cell for cell. +- **Gates.** + - The soak drives an authority with pty bytes and lands deltas at + random, both skipping states and delaying a delta while the authority + moves on. Resizes and fetches of holes also come at random. After each + delta it checks the replica's screen against the authority's as + encoded, and every history row the replica holds outside its holes + against the authority's row at that number. + - It passed with synthetic shell, TUI and `yes` streams at 4 seeds (in + the unit tests, with a 64 KB scrollback so it prunes). It also passed + with 197 recorded streams at 3 seeds each (the test that + PARDES_SCREEN_STATE=<dir> turns on): the 192 pane outputs of the snapshot scripts' + tapes, plus real vim, nvim, htop, less and btop sessions recorded + through a pty. Its corpus and recorder are in `.scratch/daemon/term`. +- **Numbers** (ReleaseFast: `PARDES_SCREEN_STATE=<dir> zig build core-test + -Dplatform=tty -Doptimize=ReleaseFast -Dtest-filter=screen_state`, which + runs under std.testing's checking allocator): + - Encode, 200x60, every row new: p50 250 us, p99 487 us, 29.8 KB. + - Encode, 200x60, nothing new: p50 71 us, p99 139 us, 534 bytes. That + is the 60 rows hashed and the TERMINAL record encoded to hash it. + - Under `yes` as fast as ghostty takes it in-process (9 to 12 MB/s), + with a delta every 16 ms: 62 deltas a second, 63 KB/s on the wire, + 1 KB a delta (60 rows and the tail's 60, all held). That is bounded by + the frame rate, not the output. + - Under varied text at 36 to 55 MB/s: 355 KB/s on the wire, 5.6 KB a + delta. + - The replica applies a `yes` delta in 2.4 ms, most of it pushing the + rows scrolled past into its history (a row at a time). A delta of + varied text applies in 0.24 ms under the C allocator and 0.95 ms + under the checking one. +- **What proved wrong in the design.** + - "Scrollback fetched on demand" alone loses rows. A row that changed + after the last delta and then scrolled off would sit stale in the + replica's history. The tail fixes the rows that scrolled within a + screen. Older ones, which the replica never saw or saw before they + last changed, are holes: rows it must fetch before it shows them. + - The address had to include the row's width, as above. The soak found + this: a replica reused an 80-column blank row after a resize to 10. + - ghostty narrows pages lazily, so an active row can be wider than its + terminal: only the terminal's columns are hashed and encoded. +- **Not done, or a gap.** + - Kitty images in terminals. + - pardes's own state derived from the stream is not carried: its + `MarkedHandler` prompt phase, command-output pins and the replies it + writes to the pty. ghostty's prompt marks on rows do cross. + - The view's scroll offset is per client and is not sent. + - A replica's core must not resize its pane's terminal itself; the + authority sizes it. + - The replica's history extent follows its own pruning under the + authority's limit, so it can be a page off, and its oldest rows can + be ones the authority has dropped. + - A fetch sends every row as a blob (phase 6's cache will send + addresses). No zstd. + - A replica pushes a flood's rows into its history one at a time. + - The integration into the stream and the cores (a replica pane's + State fed by `apply` instead of `.output`) is the next piece. |
