diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-29 12:22:50 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-29 18:17:34 -0300 |
| commit | cb747d385019564e2141f7d9b01d03b394b469b8 (patch) | |
| tree | 162a0610e9b079ebf8fa9130018f5b2124855737 /docs | |
| parent | ef0ec0f2025f596823ea98dc6088d0d63432bb81 (diff) | |
| download | pardes-cb747d385019564e2141f7d9b01d03b394b469b8.tar.gz pardes-cb747d385019564e2141f7d9b01d03b394b469b8.zip | |
docs/next-daemon.md: Phase 1 notes: the forks decided, what the census missed, what is deferred, and the gate's numbers
How the tape and the walker came out (a tree at the host boundary, the
replay a mode of the same binary, three replicas, digests per field),
the annotations the walker needed (`len` besides local, derived and
authority), the render-time writes moved into the step, the clock and
host facts taped, the unit tests that had passed on a stale frame, and
the two per-frame costs the A/B found and that are gone (the geometry
key fed field by field, the paint-ahead worker started inside the
render). The gate's numbers close it.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-daemon.md | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md index 500b53fe..903a80ad 100644 --- a/docs/next-daemon.md +++ b/docs/next-daemon.md @@ -409,3 +409,149 @@ Everything of ours lives in `/root/pardes-test`, nothing outside it. - A dropped connection is a hangup: the session detaches, and `pardes --attach` takes it back, as after a Detach. - sun_path is 104 bytes there, not 108. + +## Phase 1 notes + +Built 2026-10-29 (`src/walk.zig`, `src/tape.zig`, the hooks across the +core; `pardes-snap --tape`, `pardes-monkey --tape`, `zig build replay`). +Decisions taken at the forks, with the ponytail lens: + +- **The tape is a tree recorded at the host boundary, both ways.** Each + call the host makes into the core (`tape.Input`: update, serveFs, pump, + perform, the shell's acknowledgements and failures, a Restore...) is + recorded with its arguments; each call the core makes out -- a Host + function, wrapped generically over the vtable's fields, or a syscall of + its own (`tape.site`, which yields around it; every old `turn.yield()` + is one) or a read of the clock or environment (`tape.value`) -- with its + result. `done` and `ret` close each, so a 9P request served while a + step is out lands inside that step's syscall: turn order is tape order. + A replica drives the same functions and its host answers from the tape; + one that makes a call the recording did not diverges on the spot, + before any digest. `turn.yield` panics in a replica, so an untaped + syscall is a stack trace. +- **The replay is a mode of the same binary** (`PARDES_REPLAY=<tape> + pardes`), not a harness of its own: an error travels as this build's + number, and the code replayed is the code that recorded. Three replicas + run one after another: two that draw (the first's memory held while the + second runs, so it lies elsewhere) and one that never renders. The + headless one steps over the presents it does not make but takes what + the host told the core inside them (`acknowledge_panel_presentation`). +- **Fields a host writes between calls** (`native_images`, + `present_skipped`, `active`...) are found by a diff of a short list at + every crossing, not by touching the frontends. +- **The digest** is taken after every call the host made at the top (a + pump, in the tty), as one per field of the core, its stream and each + pane, its file and places, so a divergence names the field. + `PARDES_RECORD_EVERY` digests after every input, nested ones too, to + find the step one starts at. +- **The walker needed a fourth annotation, `len`**: a fixed array written + only as far as a length field says (`jumps`/`njumps`, a message's text) + is undefined beyond it, 0xAA in a safe build and a fault where it holds + a slice. Integers are hashed by value (a `u21`'s padding bits are not + its value). +- **View geometry** is `File.geometry`, a lazy cache keyed by a hash of + what it is made of: revision, length, path, scroll, hscroll, the pane's + size, tags and query, tables as far as read, context declarations, the + output origin, and the pane's `view` (wrap, layered context, row + metrics, rect height), which `sync` sets. A hundred readers a frame ask + for it, so the key is one hash of those facts laid out as words (fed + field by field it cost 4% of every frame). A step reading it (`wrapAt`, + `wrapRow`, `ensureCursorVisible`, a body drag, `zz`) makes it on demand, + and the render draws from what the step made: made afresh for every + frame as well (to show an input the key missed only as a headless + divergence), it cost a scroll a third walk of the rows, 4% of a + PageDown. An input the key misses shows as a stale frame in a golden. +- **Render wrote more than the census found**, all moved into the step: + context declarations, the notice bands and their chips' columns (a + click on a chip was routed by the last frame's), the header's caret + reveal (`tagnav.golden` moved: after `g l B B` typed in one burst the bar + stays scrolled, as a human typing it sees it), the tables' reading (a + first look of 4096 lines, a count, wherever it is asked; the rest a + frame's taped clock budget a tick), the tty filter palette and body + chrome (derived). A view's paint-ahead stays the render's own prefetch: + instead of queuing an effect it is asked of the host once the frame is + presented (`Stream.askAhead`, in the pump), so a replica that draws + nothing asks for none; query rows' paints count apart from it. (Asked + inside the render, its worker's thread start cost a held `j` 10% in the + live tty measurement.) +- **Clock.** `advance`'s wakes are the recording session's + (`tape.value(.wake, nextWake)`): a picture decoding or a fade asks a + frame, and a replica that draws none must still take the session's + ticks. The budgets of Places, Names and Tables are taped verdicts + (`tape.over`), as are a message's time of day (TZ included), File.mtime + and the pump's clock read (made whether or not it waits). A message's + stamp and an unattended session's expiry of it read the clock through + the tape too, not the session clock: that is the last pump's, and + stamped by it a message written over 9P after an idle spell was as old + as the spell and went at once (fs.py's `unattended_messages_expire`). +- **A pointer seen through a sliding pane** is taped + (`Pardes.pointerCell`): what was under it is the frame the user saw. +- **The host's facts**: the session directory (getcwd, asked once at + init), `$SHELL` and whether it is there, `$HOME` for `~`, a `Shell` that + is not there, a missing interpreter, a directory refused above, a file + deleted on disk (`File.deleted` is an input). The rest of the core's + getenv (PARDES_DUMP and the XDG dirs in dump.zig, TMPDIR for kitty + media, PARDES_TEST_CLOCK in the render) is the host's or authority-only. + Per read rather than "captured once into session state": less code, and + the same for a replica. +- **Authority-only**: worker futures and their Io (a future's presence + too), the 9P server's state (`fs`: fids, opens, the log; serveFs itself + is replayed in turn order, 9p_io's own writes into `fs` are not), the + store file every window of the user shares, which a replica keeps in + memory, and Recent read from it. **Local**: the surface, presentation, + frame stats, animations, the effect and event queues (drained by every + pump before its digest). **Derived**: the geometry, notices, highlights, + line index, tables, node trees, rail ticks, a compiled regex, an image's + decoded pixels, PDF rasters. +- **Terminals** replay from their taped pty bytes (they are `output` + events) and are digested as their active screen, cursor and scroll + numbers; their kitty images are left out until phase 5. +- **Worker results**: the census's render-polled ones (image decode, PDF + lanes) are derived state; the rest already arrive as events. + +- **Unit tests that mutate and render** without a step now step + (`p.sync()`) first, as every host does; three of them had passed on the + last frame's stale state: a prompt chip a body click had already closed, + a `.center` landing measured on no wrap map at all (it centres by lines, + so under wrap a line above can now push the cursor down where + `ensureCursorVisible` takes the view back: that test is unwrapped now), + and a context row count a scroll had not refreshed. The perf gate's + `deep-sel` cell was one more: its view, placed from the last frame's + map, stopped six lines short of the 2 MB line it selects in. In view, + that line showed `File.rawAtDisplay` measuring a line's whole rest + before walking to a column (20 ms a frame, Debug); it walks to the + column only now, and the cell is the baseline's (91 us against 106). + +What proved wrong or missing in the design: +- The census missed the host writes between calls, the pointer through + the presentation, the render-time writes above, `Stream.start` (host + code doing core work, made harmless by the futures being authority's), + getcwd, `access(2)` for `$SHELL`, File.mtime's clock, and a deadlock in + vaxis's queue (a `yes` stopped being read; fixed on this line, found by + the new measurement). +- `windowed`/`native_images` are watched host writes for now, not View + state (phase 4); the semantics hash in the hello is not done (there is + no hello in phase 1), so a tape from another build is not refused yet. +- Deferred: the GUI's own host-to-core calls (font requests, opacity, + `core.advance`/`render` are inputs, the rest not yet), PDF lanes and + Handover yields (never reached by the gate; a replica would panic on + them, which is the point), `Stream.runHere`'s yield (a host with no + workers). + +The gate on the final line (on main vukknslx): `pardes-snap --tape`, +110/110 scripts, 128 tapes, 384 replica runs, 33,093 digests, no +divergence; `pardes-monkey --tape`, 50 seeds of 70 steps, 150 replica +runs, 37,800 digests, none; `zig build replay` (the 110 scripts and 20 +seeds) clean; `snap` 110/110 with no golden changed but `tagnav`; +unit-test tty, pane-test, 9p-io-test and fs-test pass, unit-test gui +fails only its two known tests. Perf, base (main with perf --live and +the queue fix) against this line, ReleaseFast, interleaved A B A ... A, +medians of runs, the base's own spread as the A/A noise. The perf +harness's gesture cells (render, keys, PageDown, wheel, edit, deep-sel) +0.97-1.03 at an A/A of 2-7%, and on the final line, measured on the +shared perf cores, 0.91-0.97 at 10-31%. The live tty on a quiet machine: +core time p50 0.96-0.97, keystroke-to-present p50 0.98-1.03 (A/A 1-23%), +`yes | head -c 1G` 0.96, a million-line open 1.01. The live GUI's core +p50 1.00-1.04 (A/A 2-18%), present-bound at the window's 30 ms. Two +costs the A/B found are gone (the geometry key, the paint-ahead's +thread start in the render). |
