dsh-engram 0.5.1 → 0.6.0

package/lib/jit.js

@@ -0,0 +1,224 @@
+/**
+ * dsh-engram JIT push (PROPOSAL-evolution §4 v0.6-C).
+ *
+ * The measured failure mode: pull-only recall is dormant — the model rarely
+ * calls `engram_recall` on its own (24 calls / 8 details across 112 real
+ * sessions). JIT flips the direction: when a deterministic, high-precision
+ * event makes a known memory immediately relevant, append ONE short line to
+ * the prompt at that moment:
+ *
+ *   - error recurrence — the same `cmd:` signature fails a second time, and a
+ *     prior error/procedure memory already exists for it;
+ *   - file focus — the same file is edited twice in a row, and a memory is
+ *     anchored to that file (preference > fact/decision);
+ *   - goal completion — a goal completes/blocks while active ESR tasks remain.
+ *
+ * Invariants:
+ *   - append-only per session: a pushed line is never edited or withdrawn, so
+ *     the prefix changes at most once per push (the ledger prices the rewrite);
+ *   - no hit, no line (silence beats noise);
+ *   - hard budget: `maxLines` per session, `maxLineChars` per line;
+ *   - pure rules, zero LLM, fail-contained.
+ *
+ * The resume brief (§v0.7) is deliberately not here yet.
+ */
+
+import { cmdTag } from "./capture.js";
+import { shortId, workspaceKey as wk } from "./util.js";
+
+const EDIT_TOOLS = new Set(["write", "str_replace_editor", "edit"]);
+const RUN_TOOLS = new Set(["bash", "shell", "exec"]);
+
+function clip(text, max) {
+  const flat = String(text ?? "").replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+
+function basename(p) {
+  const parts = String(p ?? "").split("/");
+  return parts[parts.length - 1] || String(p ?? "");
+}
+
+function dirname(p) {
+  const parts = String(p ?? "").split("/");
+  parts.pop();
+  return parts.join("/");
+}
+
+function isMemory(row) {
+  return row !== null && typeof row === "object" && typeof row.id === "string";
+}
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.maxLines] hard cap per session (default 3)
+ * @param {number} [opts.maxLineChars] hard cap per line (default 220)
+ * @param {(push: {sessionId: string, workspace: string, session: object, line: string, chars: number, kind: string}) => void} [opts.onPush]
+ * @param {object} [opts.log]
+ */
+export function createJit({ maxLines = 3, maxLineChars = 220, onPush = null, log = void 0 } = {}) {
+  const lineCap = Number.isFinite(maxLines) && maxLines >= 0 ? Math.trunc(maxLines) : 3;
+  const charCap = Number.isFinite(maxLineChars) && maxLineChars > 0 ? Math.trunc(maxLineChars) : 220;
+  const states = new Map();
+  const totals = { pushes: 0, byKind: { error: 0, focus: 0, goal: 0 } };
+
+  function stateFor(sessionId, workspace) {
+    let state = states.get(sessionId);
+    if (state === void 0) {
+      state = {
+        sessionId,
+        workspace: typeof workspace === "string" ? workspace : "",
+        lines: [],
+        seen: new Set(),
+        failures: new Map(),
+        lastFile: "",
+        sameFile: 0,
+        focusSent: new Set(),
+        goalSent: false,
+      };
+      states.set(sessionId, state);
+    } else if (typeof workspace === "string" && workspace.length > 0) {
+      state.workspace = workspace;
+    }
+    return state;
+  }
+
+  function push(state, session, kind, line) {
+    if (lineCap === 0 || state.lines.length >= lineCap) return false;
+    const text = clip(line, charCap);
+    if (text.length === 0 || state.seen.has(text)) return false;
+    state.lines.push(text);
+    state.seen.add(text);
+    totals.pushes += 1;
+    totals.byKind[kind] = (totals.byKind[kind] ?? 0) + 1;
+    try {
+      onPush?.({
+        sessionId: state.sessionId,
+        workspace: state.workspace,
+        session,
+        kind,
+        line: text,
+        chars: text.length,
+      });
+    } catch (error) {
+      log?.warn?.(`engram jit onPush failed: ${String(error)}`);
+    }
+    return true;
+  }
+
+  function failLine(state, session, domain, tag) {
+    const rows = domain?.searchMemories?.({ workspace: state.workspace, tag, status: "active", limit: 8 }) ?? [];
+    const memory = rows.find((row) => isMemory(row) && row.kind === "procedure" && /^fixed:/.test(row.text ?? ""))
+      ?? rows.find((row) => isMemory(row) && row.kind === "error");
+    if (memory === void 0) return false;
+    return push(
+      state,
+      session,
+      "error",
+      `[JIT] ${clip(tag, 40)} failed again ×2 — ${memory.kind} #${shortId(memory.id)}: ${clip(memory.text, 92)} · engram_detail ${memory.id}`,
+    );
+  }
+
+  function focusLine(state, session, domain, path) {
+    if (state.focusSent.has(path)) return false;
+    state.focusSent.add(path);
+    const rows = domain?.listMemories?.(state.workspace, 300) ?? [];
+    const dirTag = `dir:${dirname(path)}`;
+    const anchored = rows.filter(
+      (row) => isMemory(row)
+        && row.status === "active"
+        && (row.filePath === path || (Array.isArray(row.tags) && row.tags.includes(dirTag))),
+    );
+    const memory = anchored.find((row) => row.kind === "preference")
+      ?? anchored.find((row) => ["fact", "decision", "procedure"].includes(row.kind));
+    if (memory === void 0) return false;
+    return push(
+      state,
+      session,
+      "focus",
+      `[JIT] focus ${clip(basename(path), 36)} ×2 — ${memory.kind} #${shortId(memory.id)}: ${clip(memory.text, 92)} · engram_detail ${memory.id}`,
+    );
+  }
+
+  return {
+    /** Observe a tool result; may push an error-recurrence or file-focus line. */
+    observeToolResult(exec, result, domain) {
+      try {
+        const session = exec?.agent?.session;
+        const sessionId = session?.id;
+        const cwd = session?.header?.cwd;
+        if (typeof sessionId !== "string" || sessionId.length === 0) return;
+        if (typeof cwd !== "string" || cwd.length === 0) return;
+        const state = stateFor(sessionId, wk(cwd));
+        const name = String(exec?.name ?? "").toLowerCase();
+        const args = exec?.arguments ?? {};
+
+        if (RUN_TOOLS.has(name) && result?.isError === true && typeof args.command === "string") {
+          const tag = cmdTag(args.command);
+          if (tag === null) return;
+          const count = (state.failures.get(tag) ?? 0) + 1;
+          state.failures.set(tag, count);
+          if (count === 2) failLine(state, session, domain, tag);
+          return;
+        }
+
+        if (EDIT_TOOLS.has(name) && result?.isError !== true) {
+          const path = String(args.path ?? args.file_path ?? args.filePath ?? "");
+          if (path.length === 0) return;
+          if (state.lastFile === path) state.sameFile += 1;
+          else {
+            state.lastFile = path;
+            state.sameFile = 1;
+          }
+          if (state.sameFile === 2) focusLine(state, session, domain, path);
+        }
+      } catch (error) {
+        log?.warn?.(`engram jit tool observe threw: ${String(error)}`);
+      }
+    },
+
+    /** Observe a session event; may push a goal-completion line. */
+    observeEvent(session, event, domain) {
+      try {
+        if (event?.type !== "goal/change") return;
+        const data = event?.data;
+        if (data === null || typeof data !== "object") return;
+        if (data.operation !== "complete" && data.operation !== "block") return;
+        const goal = data.goal;
+        if (goal === null || typeof goal !== "object") return;
+        const sessionId = session?.id;
+        const cwd = session?.header?.cwd;
+        if (typeof sessionId !== "string" || sessionId.length === 0) return;
+        if (typeof cwd !== "string" || cwd.length === 0) return;
+        const state = stateFor(sessionId, wk(cwd));
+        if (state.goalSent) return;
+        const tasks = domain?.listTasks?.(state.workspace) ?? [];
+        const active = tasks.filter((task) => task?.state === "active");
+        if (active.length === 0) return;
+        const shown = active.slice(0, 2).map((task) => `${task.id} ${clip(task.name, 48)}`).join("; ");
+        const more = active.length > 2 ? ` +${active.length - 2}` : "";
+        state.goalSent = true;
+        push(state, session, "goal", `[JIT] goal ${data.operation} — open: ${shown}${more} · esr_status`);
+      } catch (error) {
+        log?.warn?.(`engram jit event observe threw: ${String(error)}`);
+      }
+    },
+
+    /** The frozen JIT block for this session ("" when nothing was pushed). */
+    textFor(session) {
+      const sessionId = session?.id;
+      if (typeof sessionId !== "string") return "";
+      return states.get(sessionId)?.lines.join("\n") ?? "";
+    },
+
+    /** Drop per-session state at teardown. */
+    dispose(sessionId) {
+      states.delete(sessionId);
+    },
+
+    /** Push counters for /stats + diagnostics. */
+    stats() {
+      return { ...totals, byKind: { ...totals.byKind }, sessions: states.size };
+    },
+  };
+}

package/lib/ledger.js

@@ -0,0 +1,458 @@
+/**
+ * Context Ledger — the accounting layer of the "context portfolio"
+ * (docs/PROPOSAL-evolution.zh.md §4 v0.6-A).
+ *
+ * Every engram mechanism either spends context (injected index / recall / ESR
+ * blocks, held in the prompt prefix for the rest of the session) or saves it
+ * (pruned / compacted tool results that stop replaying). The ledger turns that
+ * into one auditable number per session, workspace and day:
+ *
+ *   net = avoided − injected − rewriteChars × (1 − cacheDiscount)
+ *
+ * where `rewriteChars` is the prefix size invalidated by a prune (KV cache
+ * break). `cacheDiscount` is the fraction a cached prefix would have cost
+ * (0.1 = 10%, the conservative L0 assumption), so the penalty is the
+ * non-discounted remainder.
+ *
+ * Zero LLM, deterministic, fail-contained. Two layers:
+ *   - live per-session accumulator, ticked by `assistant/message` events
+ *   - durable daily rollup at `~/.dsh/engram/ledger.json`, delta-flushed so a
+ *     restart loses at most `flushEvery` requests of accounting
+ *
+ * Deliberately NOT here: model-quality deltas, actual provider billing, and
+ * compaction savings whose before/after size the host does not expose yet.
+ * Those stay labelled assumptions, never invented numbers.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const FILE_NAME = "ledger.json";
+/** Matches the estimate used by the GUI (`chars / 4`). */
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_CACHE_DISCOUNT = 0.1;
+const DEFAULT_FLUSH_EVERY = 20;
+
+/** Default ledger file under the engram home. */
+export function ledgerFile(home = path.join(os.homedir(), ".dsh", "engram")) {
+  return path.join(home, FILE_NAME);
+}
+
+/** Local YYYY-MM-DD (calendar days for the user, mirrors usage.dayKey). */
+export function ledgerDayKey(now = Date.now()) {
+  const d = new Date(now);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function clampDiscount(value) {
+  if (!Number.isFinite(value)) return DEFAULT_CACHE_DISCOUNT;
+  return Math.min(1, Math.max(0, value));
+}
+
+function count(value) {
+  return Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+}
+
+function emptyBucket() {
+  return {
+    sessions: 0,
+    requests: 0,
+    injectedChars: 0,
+    avoidedChars: 0,
+    rewriteCount: 0,
+    rewriteChars: 0,
+  };
+}
+
+function addBucket(target, delta) {
+  target.sessions += count(delta.sessions);
+  target.requests += count(delta.requests);
+  target.injectedChars += count(delta.injectedChars);
+  target.avoidedChars += count(delta.avoidedChars);
+  target.rewriteCount += count(delta.rewriteCount);
+  target.rewriteChars += count(delta.rewriteChars);
+  return target;
+}
+
+function deltaOf(session) {
+  const f = session.flushed;
+  return {
+    requests: session.requests - f.requests,
+    injectedChars: session.injectedChars - f.injectedChars,
+    avoidedChars: session.avoidedChars - f.avoidedChars,
+    rewriteCount: session.rewriteCount - f.rewriteCount,
+    rewriteChars: session.rewriteChars - f.rewriteChars,
+  };
+}
+
+function isEmptyDelta(delta) {
+  return (
+    delta.requests === 0 &&
+    delta.injectedChars === 0 &&
+    delta.avoidedChars === 0 &&
+    delta.rewriteCount === 0 &&
+    delta.rewriteChars === 0
+  );
+}
+
+/** Finalize one bucket with the net-token arithmetic (pure). */
+export function finalizeLedgerBucket(bucket, cacheDiscount = DEFAULT_CACHE_DISCOUNT) {
+  const discount = clampDiscount(cacheDiscount);
+  const injectedChars = count(bucket.injectedChars);
+  const avoidedChars = count(bucket.avoidedChars);
+  const rewriteChars = count(bucket.rewriteChars);
+  const netChars = avoidedChars - injectedChars - Math.round(rewriteChars * (1 - discount));
+  return {
+    sessions: count(bucket.sessions),
+    requests: count(bucket.requests),
+    injectedChars,
+    avoidedChars,
+    rewriteCount: count(bucket.rewriteCount),
+    rewriteChars,
+    injectedTokens: Math.ceil(injectedChars / CHARS_PER_TOKEN),
+    avoidedTokens: Math.ceil(avoidedChars / CHARS_PER_TOKEN),
+    netChars,
+    netTokens: Math.round(netChars / CHARS_PER_TOKEN),
+    rewritesCostChars: Math.round(rewriteChars * (1 - discount)),
+  };
+}
+
+function readPersisted(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed === null || typeof parsed !== "object") return null;
+    if (parsed.version !== 1) return null;
+    if (parsed.workspaces === null || typeof parsed.workspaces !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Atomic-ish write: tmp + rename, so a crash never leaves a torn file. */
+function writeJsonAtomic(file, payload) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(payload)}\n`, "utf8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    // best-effort accounting — never throw into the session pipeline
+    return false;
+  }
+}
+
+function contentChars(content) {
+  if (!Array.isArray(content)) return 0;
+  let chars = 0;
+  for (const block of content) {
+    if (block === null || typeof block !== "object") continue;
+    if (typeof block.text === "string") chars += [...block.text].length;
+  }
+  return chars;
+}
+
+/**
+ * Estimate the live prefix size a prune invalidates (in Unicode code points).
+ *
+ * Walks the session surface through the same accessors the host pruner uses
+ * (`surface.nodes` → `eventAt` → `deriveEventMessage`). Fail-contained: an
+ * unknown session shape yields 0, which makes the ledger conservative about
+ * claiming savings.
+ */
+export function estimatePrefixChars(session) {
+  try {
+    const seqs = session?.surface?.nodes;
+    if (seqs === void 0 || seqs === null) return 0;
+    if (typeof session.eventAt !== "function" || typeof session.deriveEventMessage !== "function") return 0;
+    let chars = 0;
+    for (const seq of [...seqs]) {
+      const event = session.eventAt(seq);
+      if (event === void 0 || event === null) continue;
+      const message = session.deriveEventMessage(event);
+      chars += contentChars(message?.content);
+    }
+    return chars;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Create the in-memory ledger + durable rollup writer.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home] engram home (defaults to ~/.dsh/engram)
+ * @param {number} [opts.cacheDiscount] cached-prefix price share (0..1)
+ * @param {number} [opts.flushEvery] requests between durable flushes
+ * @param {boolean} [opts.persist] false = pure in-memory (tests, dry runs)
+ * @param {() => number} [opts.now] clock injection for tests
+ * @param {object} [opts.log] optional logger (warn only)
+ */
+export function createLedger({
+  home = path.join(os.homedir(), ".dsh", "engram"),
+  cacheDiscount = DEFAULT_CACHE_DISCOUNT,
+  flushEvery = DEFAULT_FLUSH_EVERY,
+  persist = true,
+  now = Date.now,
+  log = void 0,
+} = {}) {
+  const file = ledgerFile(home);
+  const discount = clampDiscount(cacheDiscount);
+  const every = Number.isFinite(flushEvery) && flushEvery > 0 ? Math.trunc(flushEvery) : 0;
+  const stored = persist ? readPersisted(file) : null;
+  const state = stored ?? { version: 1, updatedAt: 0, workspaces: {} };
+  const sessions = new Map();
+
+  function ensure(sessionId, workspace) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) return null;
+    let session = sessions.get(sessionId);
+    if (session === void 0) {
+      session = {
+        sessionId,
+        workspace: typeof workspace === "string" ? workspace : "",
+        indexChars: 0,
+        esrChars: 0,
+        jitChars: 0,
+        requests: 0,
+        injectedChars: 0,
+        avoidedChars: 0,
+        prunedChars: 0,
+        compactedChars: 0,
+        rewriteCount: 0,
+        rewriteChars: 0,
+        flushed: { requests: 0, injectedChars: 0, avoidedChars: 0, rewriteCount: 0, rewriteChars: 0 },
+        firstFlush: false,
+      };
+      sessions.set(sessionId, session);
+    } else if (typeof workspace === "string" && workspace.length > 0) {
+      session.workspace = workspace;
+    }
+    return session;
+  }
+
+  function bucketFor(workspace, day) {
+    const ws = typeof workspace === "string" && workspace.length > 0 ? workspace : "(unknown)";
+    const workspaces = state.workspaces;
+    if (workspaces[ws] === void 0 || workspaces[ws] === null || typeof workspaces[ws] !== "object") {
+      workspaces[ws] = {};
+    }
+    const days = workspaces[ws];
+    if (days[day] === void 0 || days[day] === null || typeof days[day] !== "object") {
+      days[day] = emptyBucket();
+    } else {
+      days[day] = { ...emptyBucket(), ...days[day] };
+    }
+    return days[day];
+  }
+
+  function flushSession(session) {
+    if (session === null || session === void 0) return false;
+    const delta = deltaOf(session);
+    if (isEmptyDelta(delta)) return false;
+    try {
+      const day = ledgerDayKey(now());
+      const bucket = bucketFor(session.workspace, day);
+      if (session.firstFlush === false) {
+        bucket.sessions += 1;
+        session.firstFlush = true;
+      }
+      addBucket(bucket, delta);
+      session.flushed = {
+        requests: session.requests,
+        injectedChars: session.injectedChars,
+        avoidedChars: session.avoidedChars,
+        rewriteCount: session.rewriteCount,
+        rewriteChars: session.rewriteChars,
+      };
+      state.updatedAt = now();
+      if (persist) writeJsonAtomic(file, state);
+      return true;
+    } catch (error) {
+      log?.warn?.(`engram ledger flush failed: ${String(error)}`);
+      return false;
+    }
+  }
+
+  function flush() {
+    for (const session of sessions.values()) flushSession(session);
+  }
+
+  return {
+    /** Record the latest injected block size for one component. */
+    noteInjection(sessionId, workspace, component, chars) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        const size = count(chars);
+        if (component === "esr") session.esrChars = size;
+        else if (component === "jit") session.jitChars = size;
+        else session.indexChars = size;
+      } catch (error) {
+        log?.warn?.(`engram ledger noteInjection failed: ${String(error)}`);
+      }
+    },
+
+    /** One model request completed: charge injected chars, credit savings. */
+    tick(sessionId, workspace) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.requests += 1;
+        session.injectedChars += session.indexChars + session.esrChars + session.jitChars;
+        session.avoidedChars += session.prunedChars + session.compactedChars;
+        if (every > 0 && session.requests % every === 0) flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger tick failed: ${String(error)}`);
+      }
+    },
+
+    /** A prune fired: its removed chars stop replaying from the next request. */
+    notePrune(sessionId, workspace, { charsRemoved = 0, rewriteChars = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.prunedChars += count(charsRemoved);
+        session.rewriteCount += 1;
+        session.rewriteChars += count(rewriteChars);
+        flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger notePrune failed: ${String(error)}`);
+      }
+    },
+
+    /** A compaction replaced history: the saved chars stop replaying too. */
+    noteCompaction(sessionId, workspace, { charsSaved = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.compactedChars += count(charsSaved);
+      } catch (error) {
+        log?.warn?.(`engram ledger noteCompaction failed: ${String(error)}`);
+      }
+    },
+
+    /**
+     * A prefix rewrite that is not a prune (e.g. a JIT push appended to the
+     * prompt): charge the full prefix invalidation, credit nothing.
+     */
+    noteRewrite(sessionId, workspace, { chars = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.rewriteCount += 1;
+        session.rewriteChars += count(chars);
+        flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger noteRewrite failed: ${String(error)}`);
+      }
+    },
+
+    /** Session ended: fold the tail into the durable rollup and forget it. */
+    dispose(sessionId) {
+      try {
+        const session = sessions.get(sessionId);
+        if (session === void 0) return;
+        flushSession(session);
+        sessions.delete(sessionId);
+      } catch (error) {
+        log?.warn?.(`engram ledger dispose failed: ${String(error)}`);
+      }
+    },
+
+    flush,
+
+    /**
+     * Read the ledger: persisted rollup + unflushed live deltas. Pure (never
+     * mutates state), so /stats can call it on every request.
+     */
+    summary() {
+      const byWorkspace = {};
+      const byDay = {};
+
+      // persisted floor
+      for (const [ws, days] of Object.entries(state.workspaces ?? {})) {
+        if (days === null || typeof days !== "object") continue;
+        const wsBucket = (byWorkspace[ws] ??= emptyBucket());
+        for (const [day, bucket] of Object.entries(days)) {
+          if (bucket === null || typeof bucket !== "object") continue;
+          addBucket(wsBucket, bucket);
+          const dayBucket = (byDay[day] ??= emptyBucket());
+          addBucket(dayBucket, bucket);
+        }
+      }
+
+      // live, not-yet-flushed tail
+      const today = ledgerDayKey(now());
+      for (const session of sessions.values()) {
+        const delta = deltaOf(session);
+        if (isEmptyDelta(delta)) continue;
+        const ws = session.workspace.length > 0 ? session.workspace : "(unknown)";
+        const wsBucket = (byWorkspace[ws] ??= emptyBucket());
+        if (session.firstFlush === false) wsBucket.sessions += 1;
+        addBucket(wsBucket, delta);
+        const dayBucket = (byDay[today] ??= emptyBucket());
+        if (session.firstFlush === false) dayBucket.sessions += 1;
+        addBucket(dayBucket, delta);
+      }
+
+      const totals = emptyBucket();
+      for (const bucket of Object.values(byWorkspace)) addBucket(totals, bucket);
+
+      const finalizedWorkspaces = {};
+      for (const [ws, bucket] of Object.entries(byWorkspace)) {
+        finalizedWorkspaces[ws] = finalizeLedgerBucket(bucket, discount);
+      }
+      const finalizedDays = Object.entries(byDay)
+        .map(([day, bucket]) => ({ day, ...finalizeLedgerBucket(bucket, discount) }))
+        .sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : 0));
+
+      return {
+        version: 1,
+        updatedAt: state.updatedAt ?? 0,
+        charsPerToken: CHARS_PER_TOKEN,
+        cacheDiscount: discount,
+        openSessions: sessions.size,
+        totals: finalizeLedgerBucket(totals, discount),
+        byWorkspace: finalizedWorkspaces,
+        byDay: finalizedDays,
+      };
+    },
+  };
+}
+
+/** Read the durable ledger without creating a live instance (GUI / tests). */
+export function readLedger({ home, cacheDiscount = DEFAULT_CACHE_DISCOUNT } = {}) {
+  const stored = readPersisted(ledgerFile(home));
+  const workspaces = {};
+  const days = {};
+  if (stored !== null) {
+    for (const [ws, wsDays] of Object.entries(stored.workspaces)) {
+      if (wsDays === null || typeof wsDays !== "object") continue;
+      const wsBucket = (workspaces[ws] ??= emptyBucket());
+      for (const [day, bucket] of Object.entries(wsDays)) {
+        if (bucket === null || typeof bucket !== "object") continue;
+        addBucket(wsBucket, bucket);
+        addBucket((days[day] ??= emptyBucket()), bucket);
+      }
+    }
+  }
+  const totals = emptyBucket();
+  for (const bucket of Object.values(workspaces)) addBucket(totals, bucket);
+  return {
+    version: 1,
+    updatedAt: stored?.updatedAt ?? 0,
+    charsPerToken: CHARS_PER_TOKEN,
+    cacheDiscount: clampDiscount(cacheDiscount),
+    totals: finalizeLedgerBucket(totals, cacheDiscount),
+    byWorkspace: Object.fromEntries(
+      Object.entries(workspaces).map(([ws, bucket]) => [ws, finalizeLedgerBucket(bucket, cacheDiscount)]),
+    ),
+    byDay: Object.entries(days)
+      .map(([day, bucket]) => ({ day, ...finalizeLedgerBucket(bucket, cacheDiscount) }))
+      .sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : 0)),
+  };
+}