From b48f79a1c19c4c96c30d29d5f8ac5ad19c8e3475 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 5 Nov 2026 15:40:52 -0300 Subject: docs: the state file and the dumps as they are now: the reference's Dump and Restore paragraph (a label, `/dumps`, `Dump export ` to carry one, Restore of a label or a path, the words for a label the file keeps none of), its DumpDir row (the state file's directory, one that cannot be read kept aside), `/recent` kept in the state file, `/dumps` among the root files, the snapshots and the stats, and the log's `dump` and `restore` records; building.typ's Upgrade (`upgrade-` in the state file, the build before's `.dump` still read); setup.typ's new list of the files pardes keeps (the startup file and the crash record, the state file, the blob cache, the runtime directory's, and the build before's to delete); next-store.md's decision (everything on disk through xitdb, with the measured costs) over W4's, the closed panes under it and its tests as they are; and the changelog's entry, what a user must know: labels where dump files were, `Dump export`, `.dump` files read for one release, Recent read once from its old file, DumpDir now the state file's directory, the old cache directory no longer read, an unreadable state file kept aside Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge --- docs/next-store.md | 124 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 92 insertions(+), 32 deletions(-) (limited to 'docs/next-store.md') diff --git a/docs/next-store.md b/docs/next-store.md index 89997ee2..3c8a2f7d 100644 --- a/docs/next-store.md +++ b/docs/next-store.md @@ -1,4 +1,4 @@ -# The store: Recent's file, and this session's closed panes +# The store: the state file, the blob cache, and this session's closed panes > We should have some persistent state that is bounded (a houndred or so > MiB at most) stored on the fs and shared among all pardes windows. It will @@ -6,22 +6,66 @@ > picker and this should include panes from the current session that were > deleted/closed. -## The decision (2026-11-05) - -**Recent is a file of at most 200 lines**, `$XDG_STATE_HOME/pardes/recent` -(else `~/.local/state/pardes/recent`), a line a file, the newest first: -` `. Every session reads it at start, and -again on use (Recent, `/recent`) when a stat of it says another session -wrote it since. A step that changed the list writes it at its end: `flock` -on the file (held by another session: the next step tries again, so a -frame never waits for one; at exit the lock is waited for), the file read -again with this session's changes put over it (`recent.List.merge`) when -another session wrote it since, and the whole list written over it in -place. A line that is no entry is passed over: a missing, unreadable or -foreign file is an empty list, a reader meeting a write half done reads it -again once its stat moves on, a line a crash tore is one entry fewer, and -pardes always starts. A rename of a new file over it (atomic) cost twice -the write in Debug for nothing the lenient read does not already give. +## The decision (2026-11-05, the persistence step): everything on disk through xitdb + +What pardes keeps on disk goes through xitdb (`src/Db.zig`; architecture +ยง14): two files, both BLAKE3-keyed, both with xitdb's header-last commit, +so a kill or a full disk leaves the last commit whole. + +**The state file**, `pardes.xitdb` in the DumpDir (`$XDG_DATA_HOME/pardes`, +else `~/.local/share/pardes`), one a user: Recent is documented as shared +by every window, a Restore is any session's. Its root is a map: + +- `recent`: Recent's 200 lines as one value, the format the `recent` file + had. A session reads it at start (after the startup config, whose DumpDir + says where the file is) and on use when the file's committed size has + moved; a step that changed it reads, merges (`recent.List.merge`) and + writes it in one transaction under the file's lock, taken without + waiting: busy, the next step tries again. Not fsynced, as the file never + was: a commit is 20 us without fsync and 5.2 ms with xitdb's two on this + machine's btrfs, against 124-148 us for the whole flush after an open. + Measured: 133-135 us for that flush (Debug, 200 files), and 12,325 bytes + of file a Recent change (its 12,089 bytes of lines and 236 of xitdb's). +- `dumps/