summaryrefslogtreecommitdiff
path: root/docs/next-daemon.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 17:01:35 -0300
committerGabriel Schneider <[email protected]>2026-10-29 19:21:09 -0300
commitc2b4f235e78735102c691677f08bd1b2403168df (patch)
tree0c13bfe79fe79901bb47e1cb8e401440bd1e1f37 /docs/next-daemon.md
parent97bb0e816513b805ca13358d8a14ba117f586403 (diff)
downloadpardes-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/next-daemon.md')
-rw-r--r--docs/next-daemon.md98
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.