summaryrefslogtreecommitdiff
path: root/docs/next-daemon.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-29 18:31:11 -0300
committerGabriel Schneider <[email protected]>2026-10-29 21:13:33 -0300
commitb4c7b2ff828d258dde78ff2dcded3b226e6d874d (patch)
tree468e1a9d0dd8c88db7b66c69cb3341402048d733 /docs/next-daemon.md
parent84b673d6c01e647c2eaeb6464d1f0a0004b7bd20 (diff)
downloadpardes-b4c7b2ff828d258dde78ff2dcded3b226e6d874d.tar.gz
pardes-b4c7b2ff828d258dde78ff2dcded3b226e6d874d.zip
docs/next-daemon.md: phase 2 notes (the walker dump, crossing builds, load and revive, what the design missed); the GUI's Restore test keeps the dump's serial
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs/next-daemon.md')
-rw-r--r--docs/next-daemon.md121
1 files changed, 121 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md
index d4f9130e..7da2804f 100644
--- a/docs/next-daemon.md
+++ b/docs/next-daemon.md
@@ -1310,3 +1310,124 @@ Not done, and why:
- test/fs.py's `mounted-startup` still hangs on main (lyntonns). The same
hang shows with main's own binary in a workspace of its own, so it is
not this line's.
+
+## Phase 2 notes
+
+Built 2026-10-29 (`src/walk.zig` Dump/Load, `src/dump.zig`, terminal.zig's
+dump hooks; `pardes-snap --dump`, `pardes-monkey --dump`, and both in
+`zig build replay`). Decisions taken at the forks, with the ponytail lens:
+
+- **The dump is the digest's preimage.** It walks exactly what the digest
+ walks (local, derived and authority fields stay out), so `digest(load(
+ dump(x))) == digest(x)` is the definition of complete, and the gate. The
+ dump is `magic`, a table of every type the roots' walk reaches (each
+ struct's and union's fields by name with their types' places, each
+ enum's names and values, each number's width), then the values as the
+ tape lays them out but for an enum or union tag by its place in the
+ table, and a pointer or slice met again written as a reference to the
+ first. The table is a comptime graph of the roots: a session's is 324
+ types in 23 KB, of a fresh session's 96 KB dump.
+- **Crossing builds: by name, and positional when it need not be.** A
+ table byte-identical to this build's is read field after field, no name
+ asked (the join's same-build path: no separate strict format). Any other
+ is matched by name: a field added takes its default, one removed is
+ passed over, an enum value by its name (Builtin's ordinals shift with
+ every builtin added), numbers widened or narrowed by value, arrays as
+ far as they fit, one that came to hold a `len` read either way. A field
+ whose kind changed takes its default and is said; with no default the
+ value it is in is refused, and an element of an array of optional
+ pointers (the session's panes) is then left out with its place in the
+ layout (`dropMissing`), never more. What was let go is the session's
+ first message after the load. A pane whose terminal another build could
+ not read is a fresh terminal (`ensureKind`).
+- **Roots, not wrappers.** A session's dump is three roots: the core,
+ read *into* a core `Pardes.create` made (its local, derived and
+ authority fields stay create's: no defaults to invent for an arena or a
+ host), its 9P mounts (state the user made, inside the 9P server's
+ authority `fs`), and which file panes' files were on disk when it was
+ made (one gone by the load is said deleted, so Del asks: its text is
+ nowhere else; one never on disk comes back as it was). A pane's dump
+ (the store's, a handover's) is a Pane alone.
+- **Aliasing by reference.** Zerox twins share their text and undo again,
+ an `inherited` cwd points at its pane again. Keyed by address, length
+ and type, which is also what made twins dump their text once.
+- **Terminals are ghostty 1.4's snapshot** (`terminal.State.dumpWrite`):
+ both screens, history, styles, links, and the kitty images with their
+ pixels and placements (the known gap in test/kitty.zig closed), plus a
+ walk dump of pardes's own parts (unsent replies, the view, the OSC 133
+ command cycle, its output pins as screen points). The snapshot is at
+ the ground state: a sequence the program had begun at the dump's moment
+ is lost (ponytail: the stream would have to track its continuation, a
+ cost on every pty read). ghostty calls its format a work in progress:
+ a ghostty bump that changes it makes a terminal another build cannot
+ read, which degrades as above.
+- **Clean files' text is in the dump.** A join cannot read the
+ authority's disk, and the session is what it holds. A file changed on
+ disk since comes back as the watch a load emits finds it (as on open: a
+ clean pane reloads, an unsaved one is marked changed), not by a read in
+ the load. The store keeps a closed pane's record under 8 MiB by a slim
+ form (no terminal history, no undo, a clean file's text read again on
+ reopen), as it kept terminals without history before.
+- **Load and revive are two halves.** `load` makes the core and nothing
+ else (what the gate checks, and what a replica takes); `revivePane` and
+ `reviveSession` give it to a host: a new shell under each terminal's
+ history (alternate screen left, keys, mouse and paste modes reset, the
+ banner; the old shell's REPL, Tty+ word and sent command dropped; a
+ command pane finished), watches, PDFs opened again (MuPDF's document is
+ derived: `Document.handle` is optional now), Recent and the store, the
+ ThemeFile asked for again, the startup config. The screen stays the
+ dump's until the host resizes: setting this process's `opts` size first
+ reflowed twice and lost where a terminal's view was.
+- **`opts` is local** (how this process was started: allocators, socket
+ names, store path), and so are `dump_out` and the effect and input
+ queues' counters (the queues were local, their heads and lengths were
+ walked: a loaded core read a garbage effect). Pipe's runs, an Edit's,
+ Handover's dump in flight and its carrier, and the host's fallback file
+ table are authority: host errands, not state.
+- **Restore keeps serials.** Renumbering would rewrite every serial the
+ session holds (attachments, query owners, places, messages, LSP and
+ callstack requests); Restore hangs up every connection anyway. The next
+ serials are past the old session's; `restored`/`restoredcol` records
+ are gone. A Restore over an older session keeps the host's facts (cell
+ pixels, row metrics, native images) and the higher of the request
+ sequences.
+- **A failed load leaves nothing**: the loader records each allocation it
+ made and frees them all (`rollback`), and a `dumpFree` for a custom
+ type's insides. ghostty's snapshot decode itself leaks when an
+ allocation inside it fails: the OOM Restore test runs without a
+ terminal.
+- **Handover** dumps `Carried` (the kind, a column's tag, each pane's
+ dump, weights, owners) behind `pardes-carried\n`; a new window's `-l`
+ of it is an empty core that adopts the panes, its settings this
+ process's (the old carried dump brought the source window's theme and
+ settings along). Panes carried now keep their undo.
+- **No v1 reader.** A ZON dump is refused before anything is replaced
+ (`not a pardes dump: it does not begin as one`), and a ZON record in
+ the store does not reopen. Dumps are `.dump` files now.
+
+What proved wrong or missing in the design:
+- The walker's list rule (exactly `items` and `capacity`) never matched in
+ a safe build: Zig 0.17's ArrayList has a `pointer_stability` lock there,
+ so phase 1's digest hashed every list's capacity and a dump wrote it.
+ Both take a list's items now.
+- "pty masters passed as fds where Handover passes them today": Handover
+ passes none (it refuses terminals: their shells are the window's
+ children), and phase 3 made Detach happen in place, so no dump carries
+ a master. A loaded terminal gets a new shell; the daemon's Adopt is the
+ way back to the old ones.
+- There are no crash dumps: crash.zig records the panic message only.
+ None was added: a panic handler would walk state that may be what broke
+ and allocate inside the handler. The path that exists is Dump, rebuild,
+ Restore, which the by-name load is for (a session read by name is a
+ unit test over the whole type graph).
+- Two behaviours of the old dump were its approximations, and goldens
+ moved to the real session: a terminal's view comes back where it was
+ (load.snap's old view was not the dumped one), its prompt rows stay
+ hidden in text mode (OSC 133 marks are in the snapshot), its Filter, a
+ pane's message and typed text over its history are kept, and a query
+ pane comes back a live query, not plain text.
+- Not done: the web shell (`-Ddump=` embeds a dump) was not built; a
+ native dump should load there by name. A dump is read whole, not
+ decoded as it arrives (the join can stream it; decoding as it arrives
+ needs a reader over a stream, not a slice). Native byte order: every
+ host pardes runs on is little-endian.