summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 12:22:50 -0300
committerGabriel Schneider <[email protected]>2026-10-29 18:17:34 -0300
commitcb747d385019564e2141f7d9b01d03b394b469b8 (patch)
tree162a0610e9b079ebf8fa9130018f5b2124855737
parentef0ec0f2025f596823ea98dc6088d0d63432bb81 (diff)
downloadpardes-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]>
-rw-r--r--docs/next-daemon.md146
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).