summaryrefslogtreecommitdiff
path: root/docs/next-store.md
blob: 3c8a2f7da9f5c2cfaa15c03e85fc18a917fb2a6a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
# 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
> store stuff for like the recent files picker. We should also have a panes
> picker and this should include panes from the current session that were
> deleted/closed.

## 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/<label>`: a dump each, `pardes-<date>-<time>` (UTC, `-2` and on in
  one second), `upgrade-<pid>`: its number, date, pane count and size, the
  session as a database of its own (walk.Put's maps, by field name: another
  build reads it by name), and the hashes of the texts it keeps beside it.
  One Dump is one fsynced transaction; the newest 32 are kept, the texts no
  kept one names dropped in the same transaction.
- `blobs/<hash>`: each such text (a `.blob` field of 4 KiB and up) once:
  an unchanged text is written once across dumps.
- `last`, `seq`: the newest dump's label, the next number.

At a session's end the file is compacted into `pardes.xitdb.new` and
renamed over it once it is past twice what it holds plus 64 MiB, under the
lock; another session notices the new file by its inode and opens it. A
file there that is no database is kept aside as `pardes.xitdb.broken`.

**A dump travels as an image**: a database in memory holding one dump in
the same shape (deterministic: no random ids, so one session is one
image). The core makes one at a Dump (the host puts it in the state file
under its label, or writes it whole for `Dump export <path>` and
`$PARDES_DUMP`), a Restore of a label is read into one, a handover's
carried panes are one (`handover-<seq>`), and `-l <file>` and
`Restore <path>` read one, an old byte dump (`.dump`) too for one release.

**The far client's blob cache** is `cache.xitdb` in `$XDG_CACHE_HOME/pardes`:
expendable and up to a gigabyte, so never the state file. `blobs/<hash>`,
`seen` (a sorted map of numbers to hashes, the least recently used first),
`size`; past the cap (`PARDES_BLOB_CACHE_MB`, 1 GiB) the oldest go and the
file is compacted, at a client's end.

**Not in a database**: the closed panes (this session's, in memory, as
below), the crash record (one `write(2)` from the panic handler, which may
not lock or allocate), the startup file and themes (edited by hand), and
the kernel's and the shells' files (sockets, locks, the registry, rc
snippets).

**Migration**: Recent is read once from the `recent` file this decision
replaces, else the `store` before it, when the state file holds none yet;
both are left where they are.

## Closed panes

**Closed panes are this session's, in memory**: the newest 64, within
64 MiB together, each a one-pane dump (`dump.savePane`, at most 8 MiB; a
terminal past it is kept without its history, any other pane is not kept)
and where it was. Panes lists them after the open panes, `(closed)`;
Enter, or a Look at `@pN`, brings one back beside the pane that took its
rows. Restore keeps them; the session's end drops them.

## Before it, the same day

**Recent was a file of at most 200 lines**, `$XDG_STATE_HOME/pardes/recent`,
under `flock`, written whole in place; the state file keeps those lines as
one value and reads the file once.

## What went, and why

The store this replaced (2026-10-24, Store.zig 1,135 lines) was one
append-only log of CRC-framed records (`@h`, `@r`, `@c`, `@x`) under
flock, with a resync past torn or garbage records, a compaction by rename,
a 100 MiB cap, and each closed pane a self-describing dump in the file,
read back at its offset. Closed panes were only ever listed by the session
that closed them, so only the file and its bound were shared: an
in-memory list is the same behaviour for far less code and no format (the
position the store's own note held least firmly). Recent needs no log: 200
lines rewritten whole under the lock is a few kilobytes a step that opens
or closes a file.

What a user loses: the closed panes of other sessions, which the log kept
on disk until a compaction and nothing ever listed.

W4's `recent` file read the old `store` once more while it was the newer
of the two; the state file reads `recent`, else `store`, once (the
migration above), and leaves both for an older pardes still running.

## Tests

Db.zig: two windows share Recent (each reads the other's commits on use; a
lock held by a third party delays a write, never loses it); the file holds
the newest 200, newest first; a file that is no database is kept aside and
a new one started; Recent is read once from the `recent` file, else the
`store`, both left in place; two dumps of one label get labels of their own;
a Dump makes the directories of its DumpDir. Store.zig: a session keeps its
newest 64 closed panes; a closed pane comes back where it was, its rows from
the pane that took them, listed `(closed)` in Panes and unlisted once back,
and another session lists none. recent.zig: a merge puts this session's
changes over the list read. dump.zig: an image read by name is the session,
and dumps to the same bytes again; an old `.dump` is read by `-l` and
Restore. upgrade.zig: an older build's record loads its `.dump` file.
replica.zig: the blob cache rehashes what it reads, keeps its cap by least
recent use and compaction, and starts afresh over a file that is no
database. test/behaviour/root_ctl.zig: a Dump and Restore round trip through
9P, a missing label refused in words, the 33rd dump dropping the first, an
unchanged text written once across two dumps, a killed Dump leaving the one
before it whole. test/behaviour/other_files.zig: two sessions on one state
file share Recent. test/process/other_files.zig: a file opened and closed is
in `/recent` closed and still is in the next session; two sessions share
Recent. test/daemon.py: an Upgrade keeps its dump in `/dumps`, and far
clients' cache.