Skip to content

Commit 8179219

Browse files
ndemiancclaude
andcommitted
feat(sessions): sessionStore.js — the persistence spine, with fast-retrieval proven
First implementation slice (design: docs/levelcode-chat-sessions-design.md + levelcode-sessions-experience.md). Pure Node, no vscode, unit-tested like update.js/mcpConfig.js. Provides slugging, sortable ids, append-only session files (meta + events), tolerant parse (torn last line dropped), the pure deriveEntry() that folds a session into an index row, and the index as a rebuild-on-corruption CACHE (scanProject is the source of truth). Verifies the fast-retrieval requirement by counting real fs reads: - listing/getting a session created 25 days ago reads the in-memory index — ZERO session-file reads, ZERO directory scans (age-independent); - switching (resume) reads EXACTLY ONE session file whether the corpus is 4 or 51 (corpus-size-independent); - a corrupt index.json silently rebuilds by scanning — never load-bearing. sessionStore: 9 tests. Full extension suite: 28 suites, 0 failures. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 220d0b6 commit 8179219

2 files changed

Lines changed: 466 additions & 0 deletions

File tree

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
// @ts-check
2+
'use strict';
3+
4+
/*
5+
* sessionStore.js — the persistence spine for LevelCode chat sessions.
6+
*
7+
* Pure Node (fs / path / crypto), no `vscode` — so it unit-tests like update.js and mcpConfig.js.
8+
* The design lives in docs/levelcode-chat-sessions-design.md (storage) and
9+
* docs/levelcode-sessions-experience.md (why the shapes are what they are).
10+
*
11+
* The one property this module exists to guarantee is FAST RETRIEVAL that does not degrade with a
12+
* session's age or with the size of the corpus:
13+
*
14+
* • LISTING / SEARCHING reads the in-memory INDEX, never the session files. `loadIndex` is paid once;
15+
* `getEntry` / `listEntries` are pure lookups over that array. A chat created 25 days ago (or a
16+
* year ago) costs exactly the same as one created a minute ago — the index carries its metadata.
17+
* • SWITCHING (resume) reads exactly ONE file — that session's `.jsonl` — via `readSession`. It never
18+
* scans the directory or touches its neighbours, so wall-clock is bounded by that one session's
19+
* size, not by how many sessions exist or how old this one is.
20+
* • The index is a CACHE, never load-bearing: `loadIndex` rebuilds it by scanning on any corruption,
21+
* and `scanProject` (reading the files) is always the source of truth (anti-Copilot #vscdb).
22+
*
23+
* Storage layout (per project):
24+
* <root>/<project-slug>/
25+
* index.json cache of derived entries — rebuildable by scanning
26+
* <session-id>.jsonl one meta line + append-only events
27+
*/
28+
29+
const fs = require('fs');
30+
const path = require('path');
31+
const crypto = require('crypto');
32+
33+
/** Bump only on an incompatible on-disk change; `loadIndex` refuses a newer index and rebuilds. */
34+
const SCHEMA_V = 1;
35+
36+
const INDEX_NAME = 'index.json';
37+
const PREVIEW_MAX = 96;
38+
39+
// ── slug & ids (pure) ──────────────────────────────────────────────────────────────────────────
40+
41+
/**
42+
* A project path → a human-readable, filesystem-safe directory slug.
43+
* "/Users/ada/code/thin.ly" → "-Users-ada-code-thin-ly"
44+
*
45+
* Every run of non-`[A-Za-z0-9_]` collapses to a single "-"; the LEADING dash is kept (it encodes the
46+
* absolute-path root and matches the convention Claude Code and this repo's own memory dir already use),
47+
* a trailing dash is trimmed. The slug is intentionally lossy (two unicode-only paths can collide); that
48+
* is safe because the REAL path is stored in each file's meta line — a collision degrades to "listed
49+
* under a shared name", never to "lost" (design §3 keying). Callers disambiguate on `meta.project`.
50+
*/
51+
function projectSlug(projectPath) {
52+
const s = String(projectPath == null ? '' : projectPath).replace(/[^A-Za-z0-9_]+/g, '-').replace(/-+$/, '');
53+
return s || '-'; // the filesystem root (or an empty path) still needs a directory name
54+
}
55+
56+
/**
57+
* A sortable, filesystem-safe session id: `YYYY-MM-DDTHH-MM-SS-<rand>` (colons/dots → dashes, so it is a
58+
* legal filename and lexicographically time-ordered). `now`/`rand` are injected for deterministic tests;
59+
* default to the clock and 4 base36 chars of randomness.
60+
*/
61+
function newSessionId(now, rand) {
62+
const d = now instanceof Date ? now : new Date();
63+
const stamp = d.toISOString().replace(/[:.]/g, '-').slice(0, 19); // 2026-07-28T09-12-33
64+
const r = rand != null ? String(rand) : crypto.randomBytes(3).toString('hex').slice(0, 4);
65+
return stamp + '-' + r;
66+
}
67+
68+
// ── paths (pure) ───────────────────────────────────────────────────────────────────────────────
69+
70+
function projectDir(root, slug) { return path.join(root, slug); }
71+
function sessionFile(root, slug, id) { return path.join(root, slug, String(id) + '.jsonl'); }
72+
function indexFile(root, slug) { return path.join(root, slug, INDEX_NAME); }
73+
74+
// ── event encoding & parsing (pure) ──────────────────────────────────────────────────────────────
75+
76+
/** The birth line — written once, so even a one-message crash leaves a listable session (design §4). */
77+
function metaLine(id, projectPath, createdAtIso, title) {
78+
return { kind: 'meta', v: SCHEMA_V, id: String(id), project: String(projectPath == null ? '' : projectPath),
79+
createdAt: String(createdAtIso), title: title == null ? null : String(title) };
80+
}
81+
82+
function encodeEvent(event) { return JSON.stringify(event) + '\n'; }
83+
84+
/**
85+
* Parse a session file's text into `{ meta, events }`. Tolerant by construction: append-only means the
86+
* only way a line is malformed is a torn final write (crash mid-append), so a trailing unparseable line
87+
* is DROPPED rather than throwing — the crash costs at most the in-flight event (design §prior-art).
88+
*/
89+
function parseSession(text) {
90+
const lines = String(text == null ? '' : text).split('\n');
91+
let meta = null;
92+
const events = [];
93+
for (let i = 0; i < lines.length; i++) {
94+
const line = lines[i];
95+
if (!line) { continue; } // blank (incl. the trailing newline's empty tail)
96+
let obj;
97+
try { obj = JSON.parse(line); }
98+
catch { if (i === lines.length - 1) { break; } else { continue; } } // torn last line → stop; a mid-file junk line → skip
99+
if (obj && obj.kind === 'meta' && !meta) { meta = obj; }
100+
else { events.push(obj); }
101+
}
102+
return { meta, events };
103+
}
104+
105+
// ── derive an index entry from a parsed session (pure — the heart of the cache) ──────────────────
106+
107+
function truncate(s, n) { const t = String(s == null ? '' : s); return t.length > n ? t.slice(0, n - 1) + '…' : t; }
108+
109+
/**
110+
* Fold a parsed session into the compact entry the History list reads. PURE and total — every field
111+
* degrades gracefully so a partial/old-schema session still yields a listable row (never throws).
112+
*/
113+
function deriveEntry(meta, events) {
114+
const evs = Array.isArray(events) ? events : [];
115+
const id = meta && meta.id ? String(meta.id) : null;
116+
const createdAt = meta && meta.createdAt ? meta.createdAt : (evs[0] && evs[0].t) || null;
117+
118+
let title = null, updatedAt = createdAt, model = null, state = 'active', lifecycle = 'active', pinned = false;
119+
let turns = 0, firstUser = null;
120+
const editCounts = new Map(); // path → times edited (order-preserving via Map)
121+
const spark = [];
122+
123+
for (const e of evs) {
124+
if (!e || typeof e !== 'object') { continue; }
125+
if (e.t) { updatedAt = e.t; }
126+
switch (e.kind) {
127+
case 'user': turns++; if (firstUser == null && e.content != null) { firstUser = String(e.content); } break;
128+
case 'assistant': case 'agent': if (e.model) { model = e.model; } break;
129+
case 'title': if (e.title != null) { title = String(e.title); } break;
130+
case 'end': if (e.state) { state = String(e.state); } break;
131+
case 'label':
132+
if (e.lifecycle) { lifecycle = String(e.lifecycle); }
133+
if (typeof e.pinned === 'boolean') { pinned = e.pinned; }
134+
break;
135+
}
136+
// files edited + the activity sparkline come from agent turns (explicit `edits` + `tools` count)
137+
if (e.kind === 'agent' || e.kind === 'edit') {
138+
const paths = e.kind === 'edit' ? (e.path ? [e.path] : []) : (Array.isArray(e.edits) ? e.edits.map((x) => x && x.path).filter(Boolean) : []);
139+
for (const p of paths) { editCounts.set(p, (editCounts.get(p) || 0) + 1); }
140+
}
141+
if (e.kind === 'agent') { spark.push(Number.isFinite(e.tools) ? e.tools : (Array.isArray(e.edits) ? e.edits.length : 0)); }
142+
}
143+
144+
if (title == null) { title = (meta && meta.title != null) ? String(meta.title) : (firstUser != null ? truncate(firstUser, 56) : null); }
145+
const filesEdited = [...editCounts.entries()].sort((a, b) => b[1] - a[1]).map(([p]) => p);
146+
147+
return { id, title, createdAt, updatedAt, turns, model, state, lifecycle, pinned,
148+
filesEdited, spark, preview: firstUser != null ? truncate(firstUser, PREVIEW_MAX) : null };
149+
}
150+
151+
// ── writing (append-only) ────────────────────────────────────────────────────────────────────────
152+
153+
/** Create a session: its directory + the meta birth line. Idempotent-ish (a re-create just rewrites meta). */
154+
function createSession(root, slug, id, projectPath, createdAtIso, title) {
155+
fs.mkdirSync(projectDir(root, slug), { recursive: true });
156+
fs.writeFileSync(sessionFile(root, slug, id), encodeEvent(metaLine(id, projectPath, createdAtIso, title)));
157+
return sessionFile(root, slug, id);
158+
}
159+
160+
/** Append ONE event line. The only write on the hot (per-turn) path — a tiny, crash-safe append. */
161+
function appendEvent(file, event) { fs.appendFileSync(file, encodeEvent(event)); }
162+
163+
// ── reading ONE session (the switch path — exactly one file) ─────────────────────────────────────
164+
165+
/** Read + parse a single session file. This is what `resume`/switch calls: one file, size-bounded. */
166+
function readSession(file) { return parseSession(fs.readFileSync(file, 'utf8')); }
167+
168+
// ── the index (cache; rebuildable by scanning) ───────────────────────────────────────────────────
169+
170+
function listSessionFiles(root, slug) {
171+
let names;
172+
try { names = fs.readdirSync(projectDir(root, slug)); }
173+
catch { return []; } // no project dir yet → no sessions
174+
return names.filter((n) => n.endsWith('.jsonl')).map((n) => path.join(root, slug, n));
175+
}
176+
177+
/** Sort newest-first for the default History order. */
178+
function sortEntries(entries) {
179+
return entries.slice().sort((a, b) => String(b.updatedAt || b.createdAt || '').localeCompare(String(a.updatedAt || a.createdAt || '')));
180+
}
181+
182+
/**
183+
* The SOURCE OF TRUTH: derive every entry by reading the files. O(corpus) and only paid when the cache is
184+
* absent or corrupt — never on a normal list. This is what makes the index safe to treat as a throwaway.
185+
*/
186+
function scanProject(root, slug) {
187+
const entries = [];
188+
for (const file of listSessionFiles(root, slug)) {
189+
try { const { meta, events } = readSession(file); const e = deriveEntry(meta, events); if (e.id) { entries.push(e); } }
190+
catch { /* a single unreadable file must not sink the scan */ }
191+
}
192+
return sortEntries(entries);
193+
}
194+
195+
/**
196+
* Load the index CACHE for a project. Reads index.json and validates it; on ANY problem — missing,
197+
* malformed, wrong/newer schema, not an array — it silently REBUILDS by scanning and reports `rebuilt`,
198+
* so a corrupt index can never hide sessions that still exist on disk. Returns { v, entries, rebuilt }.
199+
*/
200+
function loadIndex(root, slug) {
201+
try {
202+
const raw = fs.readFileSync(indexFile(root, slug), 'utf8');
203+
const obj = JSON.parse(raw);
204+
if (obj && obj.v === SCHEMA_V && Array.isArray(obj.entries)) {
205+
return { v: SCHEMA_V, entries: sortEntries(obj.entries), rebuilt: false };
206+
}
207+
} catch { /* fall through to rebuild */ }
208+
return { v: SCHEMA_V, entries: scanProject(root, slug), rebuilt: true };
209+
}
210+
211+
/** Persist the index atomically (tmp + rename) so a crash never leaves a half-written cache. */
212+
function writeIndex(root, slug, entries) {
213+
fs.mkdirSync(projectDir(root, slug), { recursive: true });
214+
const tmp = indexFile(root, slug) + '.' + process.pid + '.tmp';
215+
fs.writeFileSync(tmp, JSON.stringify({ v: SCHEMA_V, entries: sortEntries(entries) }));
216+
fs.renameSync(tmp, indexFile(root, slug));
217+
}
218+
219+
/** Incrementally replace-or-insert one entry (by id) — the per-seal update, no full rescan. */
220+
function upsertEntry(entries, entry) {
221+
const out = (Array.isArray(entries) ? entries : []).filter((e) => e && e.id !== entry.id);
222+
out.push(entry);
223+
return sortEntries(out);
224+
}
225+
226+
// ── FAST RETRIEVAL (pure, in-memory — no disk) ───────────────────────────────────────────────────
227+
228+
/**
229+
* Look up one entry by id in an ALREADY-LOADED index. Pure: it takes the in-memory `index` and never
230+
* touches disk, so retrieving a 25-day-old (or any-age) session's metadata is a memory op, independent
231+
* of the corpus. For very large corpora a Map cache is a drop-in; a linear find over a few thousand
232+
* entries is already sub-millisecond.
233+
*/
234+
function getEntry(index, id) {
235+
const entries = index && Array.isArray(index.entries) ? index.entries : [];
236+
for (const e of entries) { if (e && e.id === id) { return e; } }
237+
return null;
238+
}
239+
240+
/** The sorted list view (pure). Optional lifecycle filter (e.g. 'active' hides archived). */
241+
function listEntries(index, opts) {
242+
const o = opts || {};
243+
let entries = (index && Array.isArray(index.entries) ? index.entries : []).slice();
244+
if (o.lifecycle) { entries = entries.filter((e) => (e.lifecycle || 'active') === o.lifecycle); }
245+
return sortEntries(entries);
246+
}
247+
248+
module.exports = {
249+
SCHEMA_V,
250+
projectSlug, newSessionId, projectDir, sessionFile, indexFile,
251+
metaLine, encodeEvent, parseSession, deriveEntry,
252+
createSession, appendEvent, readSession,
253+
listSessionFiles, scanProject, loadIndex, writeIndex, upsertEntry,
254+
getEntry, listEntries
255+
};

0 commit comments

Comments
 (0)