beatrina 0.8.6

package/host/journal-store.mjs

@@ -0,0 +1,749 @@
+// journal-store.mjs — the durable document journal, answered by the HOST.
+//
+// A transcription of spike/journal.R. The page's history engine
+// (lib/history/transaction-engine.js) accepts edits in memory;
+// lib/history/journal.js turns each accepted transaction into a RECORD and
+// hands ordered batches here. This is the store: an append-only NDJSON journal
+// plus a full checkpoint per document, under the user's own app-data directory,
+// 0700/0600. It never evaluates anything and never reads a document's text for
+// any purpose but writing it back.
+//
+// WHY THE HOST AND NOT A CHILD. The supervisor evaluates no user code, it is
+// never behind a running cell, and a journal append is a few hundred bytes.
+// Spawning a process to write a kilobyte would buy nothing but a queue. Every
+// function here takes a request, touches disk and RETURNS the frame, so if a
+// measurement ever says otherwise, moving them is a routing change.
+//
+// ── the on-disk shape ──────────────────────────────────────────────────────
+//
+//   <root>/<key>/                 key = the document's durable key, ':' → '__'
+//     journal.ndjson              one record per line: "<bytes>\t<json>\n"
+//     checkpoint.json             the newest checkpoint envelope (a JSON string
+//                                 the page's checkpoint codec wrote)
+//     checkpoint.rev              the revision of that envelope
+//     pins/<rev>.json             a named version, with its content
+//     meta.json                   display name, file binding, gaps, updated
+//     journal.corrupt-<time>      bytes cut from a journal that did not end at
+//                                 a line boundary — kept as evidence
+//
+// The record line carries its own BYTE length so a torn write is detected at
+// the next open: the tail is cut at the last complete, contiguous line and the
+// cut bytes are moved aside rather than deleted. Contiguity (each record's
+// baseRevision equals the previous record's revision) is checked on every
+// append; a mismatch is refused as `discontiguous` and the page re-bases with a
+// full checkpoint. Nothing here rewrites an accepted record.
+//
+// What is NOT promised, in words: there is no fsync. The bytes are handed to
+// the operating system; a power cut before it writes them loses the tail, and
+// the next open says so. The store is safe against the process dying, not
+// against the machine dying.
+//
+// ── the encoding rule, which is the whole reason journalFrame() exists ──────
+//
+// Records travel as VERBATIM JSON STRINGS in both directions: the page
+// serialised each one and signed it (sha), and re-encoding would be the
+// fidelity bug relay_frame exists to prevent. `journalFrame()` splices their
+// bytes into the reply by hand. JSON.stringify would ALSO be faithful here —
+// but the page's checkpoint codec verifies a SHA-256 over the exact bytes it
+// wrote, and "faithful enough today" is not a property a signature check can
+// rely on. The bytes go through untouched.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { privateModeHeld, stateDir } from "./user-dirs.mjs";
+
+const TAB = 0x09;
+const NL = 0x0a;
+export const JOURNAL_KEY_RE = /^[a-z]+:[A-Za-z0-9._~-]{1,200}$/;
+export const JOURNAL_MAX_REPLY_BYTES = 6e6;      // under the 8 MB frame cap, with room
+const envOf = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+
+/** A UTC stamp in the journal's evidence-filename shape: %Y%m%d-%H%M%S. */
+const stamp = () => {
+  const d = new Date();
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+};
+const bytesOf = (text) => Buffer.byteLength(text, "utf8");
+
+/**
+ * The journal store. One per host; the cache of scanned documents lives on it
+ * rather than in module state, so a second store (a test's) cannot inherit the
+ * first's idea of where a tail is.
+ */
+export function createJournalStore() {
+  const enabled = envOf("CARMAR_NO_JOURNAL") !== "1";
+  const cache = new Map();
+
+  const root = () => {
+    const explicit = envOf("CARMAR_HISTORY_DIR");
+    if (explicit) return explicit;
+    return path.join(stateDir(), "history");
+  };
+  /**
+   * Per-document byte budget. Above it, records at or below the newest
+   * checkpoint are compacted away (the checkpoint holds the state and both Undo
+   * stacks; pins hold their own content), never the tail.
+   */
+  const budget = () => {
+    const v = Number(envOf("CARMAR_HISTORY_BUDGET"));
+    return !Number.isFinite(v) || v < 65536 ? 64 * 1024 * 1024 : v;
+  };
+  const validKey = (key) => typeof key === "string" && JOURNAL_KEY_RE.test(key);
+  const dirOf = (key) => path.join(root(), key.replace(":", "__"));
+
+  /** A directory only this user may enter; created on first use. */
+  const ensureDir = (p) => {
+    if (!fs.existsSync(p)) {
+      fs.mkdirSync(p, { recursive: true });
+      if (!fs.existsSync(p)) throw new Error("could not create the history directory");
+    }
+    fs.chmodSync(p, 0o700);
+    return p;
+  };
+
+  const err = (type, id, code, message, extra = {}) => ({ type, id, error: message, code, ...extra });
+
+  // ── the journal file ─────────────────────────────────────────────────────
+
+  /**
+   * Every complete, contiguous record line, with the byte count where the
+   * verified prefix ends. Byte scanning on purpose: the length prefix counts
+   * BYTES (that is what a torn write leaves), so a character-indexed walk would
+   * drift on the first multi-byte record.
+   */
+  const scan = (file) => {
+    const empty = { records: [], revisions: [], offsets: [], end: 0, last: null, torn: false };
+    if (!fs.existsSync(file)) return empty;
+    let raw;
+    try { raw = fs.readFileSync(file); } catch { return empty; }
+    const total = raw.length;
+    if (!total) return empty;
+    const records = []; const revisions = []; const offsets = [];
+    let pos = 0; let torn = false; let last = null;
+    while (pos < total) {
+      let t = pos;
+      while (t < total && t < pos + 12 && raw[t] !== TAB) t += 1;
+      if (t >= total || raw[t] !== TAB) { torn = true; break; }
+      const len = Number.parseInt(raw.subarray(pos, t).toString("latin1"), 10);
+      if (!Number.isInteger(len) || len < 2) { torn = true; break; }
+      const start = t + 1;
+      const stop = start + len;                       // exclusive
+      if (stop >= total || raw[stop] !== NL) { torn = true; break; }
+      const slice = raw.subarray(start, stop);
+      // An embedded NUL (a zeroed sector reads as one) is corruption, and
+      // corruption ends the verified prefix rather than the scan. R's
+      // rawToChar refuses it; Buffer.toString would not, so it is checked.
+      if (slice.includes(0)) { torn = true; break; }
+      const json = slice.toString("utf8");
+      let parsed = null;
+      try { parsed = JSON.parse(json); } catch { parsed = null; }
+      if (!parsed || typeof parsed !== "object" || typeof parsed.revision !== "number"
+          || typeof parsed.baseRevision !== "number"
+          || (last != null && parsed.baseRevision !== last)) { torn = true; break; }
+      records.push(json);
+      revisions.push(Math.trunc(parsed.revision));
+      offsets.push(pos);
+      last = Math.trunc(parsed.revision);
+      pos = stop + 1;
+    }
+    return { records, revisions, offsets, end: pos, last, torn };
+  };
+
+  /** Cut a torn tail at the last complete record, keeping the cut bytes. */
+  const repair = (file, s) => {
+    if (!s.torn) return false;
+    let size;
+    try { size = fs.statSync(file).size; } catch { return false; }
+    if (!Number.isFinite(size) || s.end >= size) return false;
+    const raw = fs.readFileSync(file);
+    const evidence = `${file}.corrupt-${stamp()}`;
+    fs.writeFileSync(evidence, raw.subarray(s.end), { mode: 0o600 });
+    fs.chmodSync(evidence, 0o600);
+    fs.writeFileSync(file, raw.subarray(0, s.end));
+    fs.chmodSync(file, 0o600);
+    return true;
+  };
+
+  const writePrivate = (file, text) => {
+    fs.writeFileSync(file, Buffer.from(text, "utf8"));
+    fs.chmodSync(file, 0o600);
+    if (!privateModeHeld(file)) throw new Error("could not make the history file private");
+  };
+
+  /** Atomic replace within the same directory: write a sibling, rename over. */
+  const replace = (file, text) => {
+    const temp = path.join(path.dirname(file), `.carmar-journal-${crypto.randomBytes(8).toString("hex")}`);
+    writePrivate(temp, text);
+    try { fs.renameSync(temp, file); } catch (e) {
+      try { fs.unlinkSync(temp); } catch { /* gone */ }
+      throw new Error("could not replace the history file atomically; the previous one was left unchanged");
+    }
+  };
+
+  const readMeta = (dir) => {
+    const file = path.join(dir, "meta.json");
+    if (!fs.existsSync(file)) return { schema: 1, gaps: [], pins: [] };
+    try {
+      const meta = JSON.parse(fs.readFileSync(file, "utf8"));
+      return meta && typeof meta === "object" && !Array.isArray(meta) ? meta : { schema: 1, gaps: [], pins: [] };
+    } catch { return { schema: 1, gaps: [], pins: [] }; }
+  };
+  const writeMeta = (dir, meta) => {
+    meta.updated = Date.now();
+    replace(path.join(dir, "meta.json"), JSON.stringify(meta));
+  };
+  const checkpointRevisionOf = (dir) => {
+    const file = path.join(dir, "checkpoint.rev");
+    if (!fs.existsSync(file)) return null;
+    const v = Number.parseInt(String(fs.readFileSync(file, "utf8")).split("\n")[0], 10);
+    return Number.isInteger(v) ? v : null;
+  };
+
+  /** The store's view of one document: scanned, repaired if torn, cached. */
+  const stateOf = (key) => {
+    const dir = dirOf(key);
+    const cached = cache.get(key);
+    if (cached && cached.dir === dir) return cached;
+    ensureDir(dir);
+    const file = path.join(dir, "journal.ndjson");
+    const s = scan(file);
+    const repaired = repair(file, s);
+    const cp = checkpointRevisionOf(dir);
+    const st = {
+      dir, path: file,
+      last: s.last != null ? s.last : cp,
+      checkpoint: cp,
+      repaired,
+      bytes: fs.existsSync(file) ? fs.statSync(file).size : 0,
+    };
+    cache.set(key, st);
+    return st;
+  };
+
+  const pinsOf = (dir) => {
+    const p = path.join(dir, "pins");
+    if (!fs.existsSync(p)) return [];
+    const out = [];
+    for (const f of fs.readdirSync(p).filter((n) => /^[0-9]+\.json$/.test(n))) {
+      try {
+        const pin = JSON.parse(fs.readFileSync(path.join(p, f), "utf8"));
+        if (pin && typeof pin === "object") out.push({ revision: pin.revision, name: pin.name, at: pin.at });
+      } catch { /* an unreadable pin is not a pin; the list goes on */ }
+    }
+    return out;
+  };
+
+  // ── the writer lease: WHO may append, decided on disk, fenced by an epoch ──
+  //
+  // `open` issues a lease {pid, port, epoch, at} and returns the epoch; every
+  // append and checkpoint must carry it, and a write whose epoch is not the
+  // current one is refused as `fenced` — the old writer learns it lost the
+  // document rather than interleaving into it. A LIVE other holder is reported,
+  // and the caller gets no epoch unless it asks for a `takeover`, which bumps
+  // the epoch. A dead holder is simply replaced. The epoch is monotone per key
+  // and comes from the lease FILE, so a restarted supervisor cannot reissue one.
+  const leaseRead = (dir) => {
+    const file = path.join(dir, "lease.json");
+    if (!fs.existsSync(file)) return null;
+    try {
+      const v = JSON.parse(fs.readFileSync(file, "utf8"));
+      return v && typeof v === "object" ? v : null;
+    } catch { return null; }
+  };
+  const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+
+  const lease = (dir, takeover) => {
+    const file = path.join(dir, "lease.json");
+    const prior = leaseRead(dir);
+    const mePid = process.pid;
+    const alive = Boolean(prior && typeof prior.pid === "number" && prior.pid !== mePid && pidAlive(prior.pid));
+    if (alive && takeover !== true) {
+      return { held: { pid: Math.trunc(prior.pid), port: prior.port, epoch: prior.epoch }, epoch: null };
+    }
+    const epoch = prior && typeof prior.epoch === "number" ? Math.trunc(prior.epoch) + 1 : 1;
+    const me = { pid: mePid, port: Number.parseInt(envOf("CARMAR_PORT", "0"), 10) || 0, epoch, at: Date.now() };
+    try { replace(file, JSON.stringify(me)); } catch {
+      return { held: null, epoch: null, error: "The writer lease could not be written." };
+    }
+    return { held: null, epoch, takenOver: alive };
+  };
+
+  const leaseCurrent = (dir, epoch) => {
+    if (typeof epoch !== "number" || !Number.isFinite(epoch)) return false;
+    const prior = leaseRead(dir);
+    return Boolean(prior && typeof prior.epoch === "number" && Math.trunc(prior.epoch) === Math.trunc(epoch));
+  };
+
+  /**
+   * Why a write is refused, or null when the lease is current. Two answers,
+   * because they ask for different things: `unleased` (no epoch at all — this
+   * window never opened the key) is cured by `journal_open`; `fenced` (an epoch
+   * no longer current) is another window's takeover and nothing here cures it.
+   */
+  const leaseRefusal = (type, id, dir, epoch) => {
+    if (typeof epoch !== "number" || !Number.isFinite(epoch) || leaseRead(dir) == null) {
+      return err(type, id, "unleased", "This window holds no writer lease for this document; open it first.");
+    }
+    if (!leaseCurrent(dir, epoch)) {
+      return err(type, id, "fenced", "Another window took over this document's history. This window no longer writes it.");
+    }
+    return null;
+  };
+
+  // ── the ops ───────────────────────────────────────────────────────────────
+
+  const open = (id, key, meta, takeover) => {
+    if (!enabled) return err("journal_open", id, "unavailable", "The document journal is disabled (CARMAR_NO_JOURNAL=1).");
+    if (!validKey(key)) return err("journal_open", id, "invalid_key", "A journal needs a durable document key.");
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_open", id, "io", e.message); }
+    const stored = readMeta(st.dir);
+    if (meta && typeof meta === "object" && Object.keys(meta).length) {
+      stored.display = meta;
+      try { writeMeta(st.dir, stored); } catch { /* the open still stands */ }
+    }
+    const l = lease(st.dir, takeover);
+    if (l.error) return err("journal_open", id, "io", l.error);
+    return { type: "journal_open", id, key, heldBy: l.held ?? null, epoch: l.epoch ?? null,
+      takenOver: l.takenOver === true,
+      exists: st.last != null || st.checkpoint != null,
+      checkpointRevision: st.checkpoint,
+      durableRevision: st.last,
+      repaired: st.repaired === true, bytes: st.bytes, budget: budget(),
+      pins: pinsOf(st.dir), meta: stored.display ?? null, gaps: stored.gaps ?? [] };
+  };
+
+  /**
+   * READ-ONLY: does the store keep a history for `key`, from what PATH was it
+   * last saved, and does THAT path still exist? The page asks this to tell a
+   * copied file from a moved one. Unlike `open` this takes no lease and CREATES
+   * NOTHING — a probe of an unknown key must not leave an empty history
+   * directory behind, so it never calls stateOf().
+   */
+  const probe = (id, key) => {
+    if (!enabled) return err("journal_probe", id, "unavailable", "The document journal is disabled (CARMAR_NO_JOURNAL=1).");
+    if (!validKey(key)) return err("journal_probe", id, "invalid_key", "A journal needs a durable document key.");
+    const dir = dirOf(key);
+    if (!fs.existsSync(dir)) return { type: "journal_probe", id, key, exists: false, path: null, pathExists: false };
+    const stored = readMeta(dir);
+    const cp = checkpointRevisionOf(dir);
+    const exists = fs.existsSync(path.join(dir, "journal.ndjson")) || cp != null;
+    const p = stored.display && stored.display.path;
+    const okPath = typeof p === "string" && p.length > 0;
+    return { type: "journal_probe", id, key, exists: Boolean(exists),
+      path: okPath ? p : null, pathExists: Boolean(okPath && fs.existsSync(p)) };
+  };
+
+  /** The JSON of the last record, for the exact-retry rule. */
+  const tailJson = (st) => {
+    const s = scan(st.path);
+    return s.records.length ? s.records[s.records.length - 1] : null;
+  };
+
+  const append = (id, key, records, epoch) => {
+    if (!enabled) return err("journal_append", id, "unavailable", "The document journal is disabled.");
+    if (!validKey(key)) return err("journal_append", id, "invalid_key", "A journal needs a durable document key.");
+    const refused = leaseRefusal("journal_append", id, dirOf(key), epoch);
+    if (refused) return refused;
+    const list = Array.isArray(records) ? records : (records == null ? [] : [records]);
+    if (!list.length || !list.every((r) => typeof r === "string" && r.length > 0)) {
+      return err("journal_append", id, "invalid_record", "Append needs one or more serialised records.");
+    }
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_append", id, "io", e.message); }
+    // Validate the WHOLE batch before writing a byte of it.
+    let last = st.last;
+    const lines = new Array(list.length);
+    for (let i = 0; i < list.length; i += 1) {
+      const json = list[i];
+      let parsed = null;
+      try { parsed = JSON.parse(json); } catch { parsed = null; }
+      if (!parsed || typeof parsed !== "object" || parsed.key !== key
+          || typeof parsed.revision !== "number" || typeof parsed.baseRevision !== "number"
+          || parsed.revision !== parsed.baseRevision + 1
+          || typeof parsed.sha !== "string" || !/^[a-f0-9]{64}$/.test(parsed.sha)) {
+        return err("journal_append", id, "invalid_record", "A record is malformed or belongs to another document.");
+      }
+      if (last != null && parsed.baseRevision !== last) {
+        // An exact retry of the record already at the tail is acknowledged, not
+        // refused: the ack may have been lost, and the page must be able to ask
+        // again with the same bytes.
+        if (parsed.revision === last && i === 0 && list.length === 1 && tailJson(st) === json) {
+          return { type: "journal_append", id, key, durableRevision: last, retried: true };
+        }
+        return err("journal_append", id, "discontiguous",
+          `The journal ends at revision ${last}, not ${Math.trunc(parsed.baseRevision)}.`, { lastRevision: last });
+      }
+      if (last == null && parsed.baseRevision !== 0 && st.checkpoint == null) {
+        return err("journal_append", id, "discontiguous", "An empty journal starts at revision 0.", { lastRevision: 0 });
+      }
+      lines[i] = `${bytesOf(json)}\t${json}\n`;
+      last = Math.trunc(parsed.revision);
+    }
+    const added = lines.reduce((sum, l) => sum + bytesOf(l), 0);
+    if (st.bytes + added > budget() * 2) {
+      return err("journal_append", id, "quota",
+        `This document's history has reached its ${Math.trunc(budget() / 1048576)} MB budget; checkpoint to compact it.`);
+    }
+    try {
+      fs.appendFileSync(st.path, Buffer.from(lines.join(""), "utf8"));
+      fs.chmodSync(st.path, 0o600);
+    } catch (e) { return err("journal_append", id, "io", e.message); }
+    st.last = last;
+    st.bytes += added;
+    return { type: "journal_append", id, key, durableRevision: last };
+  };
+
+  /** Move every record above `revision` into a superseded-evidence file. */
+  const supersede = (st, revision) => {
+    const s = scan(st.path);
+    const keep = s.revisions.map((r) => r <= revision);
+    if (keep.every(Boolean)) return false;
+    const gone = s.records.filter((_, i) => !keep[i]);
+    const evidence = `${st.path}.superseded-${stamp()}`;
+    writePrivate(evidence, gone.map((r) => `${bytesOf(r)}\t${r}\n`).join(""));
+    const kept = s.records.filter((_, i) => keep[i]);
+    replace(st.path, kept.map((r) => `${bytesOf(r)}\t${r}\n`).join(""));
+    st.bytes = fs.statSync(st.path).size;
+    const keptRevs = s.revisions.filter((_, i) => keep[i]);
+    st.last = keptRevs.length ? Math.max(...keptRevs) : null;
+    return true;
+  };
+
+  /**
+   * Drop records at or below the checkpoint once the file is over budget.
+   * Never a byte of the tail; pins carry their own content.
+   */
+  const compact = (st, checkpoint) => {
+    if (st.bytes <= budget()) return 0;
+    const s = scan(st.path);
+    const kept = s.records.filter((_, i) => s.revisions[i] > checkpoint);
+    const before = st.bytes;
+    const text = kept.map((r) => `${bytesOf(r)}\t${r}\n`).join("");
+    try { replace(st.path, text); } catch { return 0; }
+    st.bytes = bytesOf(text);
+    return before - st.bytes;
+  };
+
+  const checkpoint = (id, key, revision, generation, envelope, meta, rebase, epoch) => {
+    if (!enabled) return err("journal_checkpoint", id, "unavailable", "The document journal is disabled.");
+    if (!validKey(key)) return err("journal_checkpoint", id, "invalid_key", "A journal needs a durable document key.");
+    const refused = leaseRefusal("journal_checkpoint", id, dirOf(key), epoch);
+    if (refused) return refused;
+    if (typeof revision !== "number" || !Number.isFinite(revision) || revision < 0
+        || typeof envelope !== "string" || !envelope.length) {
+      return err("journal_checkpoint", id, "invalid_checkpoint", "A checkpoint needs a revision and its envelope.");
+    }
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_checkpoint", id, "io", e.message); }
+    const rev = Math.trunc(revision);
+    const tailEnd = st.last != null ? st.last : (st.checkpoint != null ? st.checkpoint : 0);
+    if (rev < tailEnd && rebase !== true) {
+      return err("journal_checkpoint", id, "stale_checkpoint",
+        `The journal is already at revision ${tailEnd}.`, { lastRevision: tailEnd });
+    }
+    if (rev < tailEnd) {
+      // A RE-BASE: the page's history no longer follows this tail. The records
+      // above `revision` are not deleted — they are moved aside as evidence,
+      // exactly like a torn tail — and the journal continues from the checkpoint.
+      try { supersede(st, rev); } catch (e) { return err("journal_checkpoint", id, "io", e.message); }
+    }
+    const stored = readMeta(st.dir);
+    try {
+      replace(path.join(st.dir, "checkpoint.json"), envelope);
+      replace(path.join(st.dir, "checkpoint.rev"), `${rev}\n`);
+    } catch (e) { return err("journal_checkpoint", id, "io", e.message); }
+    let gap = null;
+    if (rev > tailEnd) {
+      // Records between the tail and this checkpoint never reached the store
+      // (an outage, an overflow, another opening). Say so, durably.
+      gap = { from: tailEnd, to: rev, at: Date.now() };
+      stored.gaps = [...(stored.gaps ?? []), gap];
+    }
+    if (meta && typeof meta === "object" && Object.keys(meta).length) stored.display = meta;
+    try { writeMeta(st.dir, stored); } catch { /* the checkpoint still stands */ }
+    st.checkpoint = rev;
+    st.last = rev;
+    const pruned = compact(st, rev);
+    return { type: "journal_checkpoint", id, key, checkpointRevision: rev, prunedBytes: pruned, gap };
+  };
+
+  const readEnvelope = (dir) => {
+    const file = path.join(dir, "checkpoint.json");
+    if (!fs.existsSync(file)) return null;
+    return fs.readFileSync(file, "utf8");
+  };
+
+  /**
+   * Everything recovery needs: the checkpoint envelope and the tail after it,
+   * page by page when the tail is long.
+   */
+  const load = (id, key, afterRevision) => {
+    if (!enabled) return err("journal_load", id, "unavailable", "The document journal is disabled.");
+    if (!validKey(key)) return err("journal_load", id, "invalid_key", "A journal needs a durable document key.");
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_load", id, "io", e.message); }
+    const wantEnvelope = afterRevision == null;
+    const envelope = wantEnvelope ? readEnvelope(st.dir) : null;
+    const from = typeof afterRevision === "number" ? Math.trunc(afterRevision)
+      : (st.checkpoint == null ? -1 : st.checkpoint);
+    const s = scan(st.path);
+    let records = s.records.filter((_, i) => s.revisions[i] > from);
+    const cap = Math.max(JOURNAL_MAX_REPLY_BYTES - bytesOf(envelope ?? "") - 4096, 0);
+    let running = 0;
+    const fits = records.map((r) => { running += bytesOf(r) + 2; return running <= cap; });
+    const more = fits.some((f) => !f);
+    records = records.filter((_, i) => fits[i]);
+    const meta = readMeta(st.dir);
+    return { type: "journal_load", id, key, aliases: meta.aliases ?? [],
+      checkpointRevision: st.checkpoint, durableRevision: st.last,
+      more, repaired: st.repaired === true, gaps: meta.gaps ?? [], pins: pinsOf(st.dir),
+      __raw: { records, checkpoint: envelope } };
+  };
+
+  /** Records in a revision range, verbatim, for the time machine's walk-back. */
+  const read = (id, key, fromRevision, toRevision) => {
+    if (!validKey(key)) return err("journal_read", id, "invalid_key", "A journal needs a durable document key.");
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_read", id, "io", e.message); }
+    const s = scan(st.path);
+    const lo = typeof fromRevision === "number" ? Math.trunc(fromRevision) : 0;
+    const hi = typeof toRevision === "number" ? Math.trunc(toRevision) : 2147483647;
+    let records = s.records.filter((_, i) => s.revisions[i] >= lo && s.revisions[i] <= hi);
+    let running = 0;
+    const fits = records.map((r) => { running += bytesOf(r) + 2; return running <= JOURNAL_MAX_REPLY_BYTES; });
+    const more = fits.some((f) => !f);
+    records = records.filter((_, i) => fits[i]);
+    return { type: "journal_read", id, key, more, __raw: { records } };
+  };
+
+  /** The time-machine list: one row per record, newest first, bounded. */
+  const versions = (id, key, beforeRevision, limit) => {
+    if (!validKey(key)) return err("journal_versions", id, "invalid_key", "A journal needs a durable document key.");
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_versions", id, "io", e.message); }
+    const s = scan(st.path);
+    const cap = Math.max(1, Math.min(Math.trunc(Number(limit ?? 200)) || 200, 1000));
+    const before = typeof beforeRevision === "number" ? Math.trunc(beforeRevision) : 2147483647;
+    let idx = [];
+    for (let i = s.revisions.length - 1; i >= 0; i -= 1) if (s.revisions[i] < before) idx.push(i);
+    idx = idx.slice(0, cap);
+    const rows = idx.map((i) => {
+      const r = JSON.parse(s.records[i]);
+      const edit = r.kind === "edit";
+      return { revision: r.revision, kind: r.kind, id: r.id, at: r.at,
+        label: (edit ? (r.entry && r.entry.label) : r.label) ?? null,
+        origin: edit ? ((r.entry && r.entry.origin) ?? null) : "user",
+        generation: r.generation ?? null,
+        abandoned: edit ? (Array.isArray(r.abandoned) ? r.abandoned.length : 0) : 0 };
+    });
+    return { type: "journal_versions", id, key, rows,
+      more: idx.length === cap && idx.length < s.revisions.length,
+      pins: pinsOf(st.dir), gaps: readMeta(st.dir).gaps ?? [] };
+  };
+
+  /**
+   * A named version: the page sends the content it reconstructed for that
+   * revision, so a pin outlives compaction of the records that led to it.
+   */
+  const pin = (id, key, revision, name, state) => {
+    if (!validKey(key)) return err("journal_pin", id, "invalid_key", "A journal needs a durable document key.");
+    if (typeof revision !== "number" || !Number.isFinite(revision) || revision < 0
+        || typeof name !== "string" || !name.trim().length
+        || typeof state !== "string" || !state.length) {
+      return err("journal_pin", id, "invalid_pin", "A pin needs a revision, a name and the content at that revision.");
+    }
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_pin", id, "io", e.message); }
+    const dir = path.join(st.dir, "pins");
+    try {
+      ensureDir(dir);
+      const head = JSON.stringify({ schema: 1, revision: Math.trunc(revision),
+        name: name.trim().slice(0, 120), at: Date.now() });
+      // `state` is the page's JSON, spliced verbatim for the record's reason.
+      replace(path.join(dir, `${Math.trunc(revision)}.json`),
+        `${head.slice(0, head.length - 1)},"state":${state}}`);
+    } catch (e) { return err("journal_pin", id, "io", e.message); }
+    return { type: "journal_pin", id, key, revision: Math.trunc(revision), pins: pinsOf(st.dir) };
+  };
+
+  const unpin = (id, key, revision) => {
+    if (!validKey(key) || typeof revision !== "number" || !Number.isFinite(revision)) {
+      return err("journal_unpin", id, "invalid_pin", "Unpin needs a document key and a revision.");
+    }
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_unpin", id, "io", e.message); }
+    try { fs.unlinkSync(path.join(st.dir, "pins", `${Math.trunc(revision)}.json`)); } catch { /* already gone */ }
+    return { type: "journal_unpin", id, key, pins: pinsOf(st.dir) };
+  };
+
+  /** The content of one pin, verbatim. */
+  const pinRead = (id, key, revision) => {
+    if (!validKey(key) || typeof revision !== "number" || !Number.isFinite(revision)) {
+      return err("journal_pin_read", id, "invalid_pin", "Reading a pin needs a document key and a revision.");
+    }
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_pin_read", id, "io", e.message); }
+    const file = path.join(st.dir, "pins", `${Math.trunc(revision)}.json`);
+    if (!fs.existsSync(file)) return err("journal_pin_read", id, "missing_pin", "No such named version.");
+    return { type: "journal_pin_read", id, key, revision: Math.trunc(revision),
+      __raw: { pin: fs.readFileSync(file, "utf8") } };
+  };
+
+  /**
+   * Save As: the history follows the document to its new key. The old key's
+   * directory is renamed; the old key is kept in `meta.aliases` so a checkpoint
+   * the engine stamped with it still verifies. A history already under the new
+   * key is set aside as abandoned first — the file the user just wrote there
+   * supersedes it.
+   */
+  const rename = (id, from, to) => {
+    if (!validKey(from) || !validKey(to)) return err("journal_rename", id, "invalid_key", "A rename needs two durable document keys.");
+    if (from === to) return { type: "journal_rename", id, from, to, renamed: false };
+    const src = dirOf(from); const dst = dirOf(to);
+    if (!fs.existsSync(src)) return err("journal_rename", id, "missing", "There is no history under the old key.");
+    cache.delete(from); cache.delete(to);
+    if (fs.existsSync(dst)) {
+      try { fs.renameSync(dst, `${dst}.abandoned-${stamp()}`); } catch {
+        return err("journal_rename", id, "io", "The history already at the new key could not be set aside.");
+      }
+    }
+    try { fs.renameSync(src, dst); } catch {
+      return err("journal_rename", id, "io", "The history could not be moved to its new key.");
+    }
+    const meta = readMeta(dst);
+    meta.aliases = [...new Set([...(meta.aliases ?? []), from])];
+    try { writeMeta(dst, meta); } catch { /* the rename still stands */ }
+    return { type: "journal_rename", id, from, to, renamed: true, aliases: meta.aliases };
+  };
+
+  /**
+   * Set aside a document's whole history (the user declined to recover it):
+   * the directory is renamed, listed as abandoned, deletable from Settings.
+   */
+  const archive = (id, key) => {
+    if (!validKey(key)) return err("journal_archive", id, "invalid_key", "A journal needs a durable document key.");
+    const dir = dirOf(key);
+    cache.delete(key);
+    if (!fs.existsSync(dir)) return { type: "journal_archive", id, key, archived: false };
+    try { fs.renameSync(dir, `${dir}.abandoned-${stamp()}`); } catch {
+      return err("journal_archive", id, "io", "The history could not be set aside.");
+    }
+    return { type: "journal_archive", id, key, archived: true };
+  };
+
+  /** Every document the store knows, for the recovery list and Settings. */
+  const list = (id) => {
+    if (!enabled) return { type: "journal_list", id, documents: [], enabled: false };
+    const r = root();
+    const dirs = fs.existsSync(r)
+      ? fs.readdirSync(r, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => path.join(r, d.name))
+      : [];
+    const documents = [];
+    for (const dir of dirs) {
+      const name = path.basename(dir);
+      const abandoned = /\.abandoned-[0-9-]+$/.test(name);
+      const key = name.replace(/\.abandoned-[0-9-]+$/, "").replace("__", ":");
+      if (!validKey(key)) continue;
+      const meta = readMeta(dir);
+      const jf = path.join(dir, "journal.ndjson");
+      const cf = path.join(dir, "checkpoint.json");
+      documents.push({ key, dir: name, abandoned, meta: meta.display ?? null, updated: meta.updated ?? null,
+        checkpointRevision: checkpointRevisionOf(dir),
+        bytes: (fs.existsSync(jf) ? fs.statSync(jf).size : 0) + (fs.existsSync(cf) ? fs.statSync(cf).size : 0),
+        pins: pinsOf(dir).length });
+    }
+    return { type: "journal_list", id, enabled: true, root: r, documents };
+  };
+
+  /** Deliberate deletion of one document's history. The page confirms first. */
+  const remove = (id, key) => {
+    if (!validKey(key)) return err("journal_delete", id, "invalid_key", "A journal needs a durable document key.");
+    const dir = dirOf(key);
+    cache.delete(key);
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+    return { type: "journal_delete", id, key, deleted: !fs.existsSync(dir) };
+  };
+
+  /** The whole history of one document as one JSON text, for the user to keep. */
+  const exportBundle = (id, key) => {
+    if (!validKey(key)) return err("journal_export", id, "invalid_key", "A journal needs a durable document key.");
+    let st;
+    try { st = stateOf(key); } catch (e) { return err("journal_export", id, "io", e.message); }
+    const s = scan(st.path);
+    const envelope = readEnvelope(st.dir);
+    const head = JSON.stringify({ format: "carmar-history-export", schema: 1, key,
+      exported: Date.now(), checkpointRevision: st.checkpoint, meta: readMeta(st.dir) });
+    const text = `${head.slice(0, head.length - 1)},"checkpoint":${envelope == null ? "null" : JSON.stringify(envelope)},"records":[${s.records.join(",")}]}`;
+    if (bytesOf(text) > JOURNAL_MAX_REPLY_BYTES) {
+      return err("journal_export", id, "too_large", "This history is too large to export over the kernel connection.");
+    }
+    return { type: "journal_export", id, key, __raw: { bundle: text } };
+  };
+
+  /** One frame for one command; the wire vocabulary in one place. */
+  const answer = (cmd) => {
+    switch (cmd.type) {
+      case "journal_open": return open(cmd.id, cmd.key, cmd.meta && typeof cmd.meta === "object" ? cmd.meta : null, cmd.takeover === true);
+      case "journal_probe": return probe(cmd.id, cmd.key);
+      case "journal_append": return append(cmd.id, cmd.key, cmd.records, cmd.epoch);
+      case "journal_checkpoint": return checkpoint(cmd.id, cmd.key, cmd.revision, cmd.generation, cmd.envelope,
+        cmd.meta && typeof cmd.meta === "object" ? cmd.meta : null, cmd.rebase === true, cmd.epoch);
+      case "journal_archive": return archive(cmd.id, cmd.key);
+      case "journal_rename": return rename(cmd.id, cmd.from, cmd.to);
+      case "journal_load": return load(cmd.id, cmd.key, cmd.afterRevision);
+      case "journal_read": return read(cmd.id, cmd.key, cmd.fromRevision, cmd.toRevision);
+      case "journal_versions": return versions(cmd.id, cmd.key, cmd.beforeRevision, cmd.limit ?? 200);
+      case "journal_pin": return pin(cmd.id, cmd.key, cmd.revision, cmd.name, cmd.state);
+      case "journal_unpin": return unpin(cmd.id, cmd.key, cmd.revision);
+      case "journal_pin_read": return pinRead(cmd.id, cmd.key, cmd.revision);
+      case "journal_list": return list(cmd.id);
+      case "journal_delete": return remove(cmd.id, cmd.key);
+      case "journal_export": return exportBundle(cmd.id, cmd.key);
+      default: return err(cmd.type, cmd.id, "unknown_op", `The document journal has no op named ${cmd.type}.`);
+    }
+  };
+
+  /**
+   * A guard every answer goes through. The send is best-effort, so a throw
+   * while BUILDING the frame means no frame is sent at all — the page's promise
+   * never settles and the pane waits out its timeout. A refusal is a reply;
+   * silence is a hang.
+   */
+  const answerGuarded = (cmd) => {
+    try {
+      const frame = answer(cmd);
+      if (!frame || typeof frame !== "object") return err(cmd.type, cmd.id, "failed", "The store produced no reply.");
+      return frame;
+    } catch (e) { return err(cmd.type, cmd.id, "failed", e && e.message ? e.message : String(e)); }
+  };
+
+  return { enabled, root, budget, validKey, dirOf, scan, stateOf, pinsOf, leaseRead, cache,
+    open, probe, append, checkpoint, load, read, versions, pin, unpin, pinRead,
+    rename, archive, list, remove, exportBundle, answer, answerGuarded };
+}
+
+/**
+ * Serialise a journal frame, splicing verbatim JSON fields in by hand.
+ * `frame.__raw` holds them: `records` (an array of JSON object texts) and any
+ * scalar JSON text (`checkpoint`, `pin`, `bundle`), emitted as JSON STRINGS
+ * (quoted) because the page decodes them itself.
+ */
+export function journalFrame(frame) {
+  const raw = frame.__raw;
+  const body = { ...frame };
+  delete body.__raw;
+  const head = JSON.stringify(body);
+  if (!raw) return head;
+  const extra = [];
+  if (raw.records) extra.push(`"records":[${raw.records.join(",")}]`);
+  for (const name of Object.keys(raw)) {
+    if (name === "records") continue;
+    const value = raw[name];
+    extra.push(`"${name}":${value == null ? "null" : JSON.stringify(value)}`);
+  }
+  if (!extra.length) return head;
+  return `${head.slice(0, head.length - 1)}${head === "{}" ? "" : ","}${extra.join(",")}}`;
+}