summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 23:05:05 -0300
committerGabriel Schneider <[email protected]>2026-10-29 23:05:14 -0300
commit2d86687b98f389232b213dfa67cfa731b0280fbb (patch)
tree1c8f4455f864325853ca488298e9329e3c44f18a
parent77c4a6e346e08538abc410f85a86bec7e8dbedb3 (diff)
downloadpardes-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]>
-rw-r--r--docs/next-daemon.md227
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`.