@ijfw/memory-server 1.5.6 → 1.6.1

package/src/profile/eval/corpus-from-reddit.mjs

@@ -0,0 +1,166 @@
+// corpus-from-reddit.mjs — Gate B v2 corpus ingest. PURE local transform: takes a RAW
+// single-subreddit dump already on disk and emits the {id,docs} corpus loadRealPersonas
+// wants PLUS a disjoint same-register foreigner pool. NO network is ever touched — the
+// operator fetches/exports the subreddit separately (do not redistribute the corpus).
+//
+// EXPECTED RAW INPUT SCHEMA (single subreddit ⇒ same register by construction):
+//   A local file at `dumpPath`, either:
+//     (a) JSONL — one JSON object per line, OR
+//     (b) JSON  — a top-level array of objects, OR { posts:[...] } / { data:[...] }.
+//   Each object must carry an author handle + a text body. Field names are flexible:
+//     author : `author` | `author_fullname` | `user` | `username`
+//     body   : `body` | `selftext` | `text` | `title`+`selftext` (concatenated)
+//   Rows with a deleted/removed/bot/empty author are DROPPED. Single-subreddit input is
+//   assumed (the same-register guarantee the wrong-target control relies on); a `subreddit`
+//   field, if present, is NOT cross-checked here — keep one subreddit per file.
+//
+// FAIL-CLOSED: an author below minDocsPerAuthor or below minTokensPerAuthor is DROPPED
+// (never padded); if fewer than nPersonaAuthors + nForeignAuthors qualify, ingest THROWS.
+// Never evaluate the downstream gate on an underpowered slice — ingest more, don't loosen.
+
+import fs from 'node:fs';
+import { tokenizeWords } from './stylometry-features.js';
+
+export const REDDIT_DEFAULTS = Object.freeze({
+  nPersonaAuthors: 60,      // headline confirmatory N
+  nForeignAuthors: 60,      // same-register foreigner pool (disjoint from personas)
+  minDocsPerAuthor: 2,      // need ≥2 docs for a disjoint train/test split downstream
+  minTokensPerAuthor: 1800, // train(1200)+test(600) floors of real-personas, with headroom
+  minBodyChars: 40,         // drop near-empty bodies before counting docs
+  seed: 1,
+});
+
+const DELETED_AUTHORS = new Set(['[deleted]', '[removed]', 'automoderator', 'deleted', 'removed', '']);
+
+// FNV-1a → uint32. Deterministic, content-independent ordering key (mirrors real-personas).
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i += 1) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+function pickAuthor(r) {
+  return String(r.author ?? r.user ?? r.username ?? r.author_fullname ?? '').trim();
+}
+function pickBody(r) {
+  if (typeof r.body === 'string' && r.body.trim()) return r.body;
+  if (typeof r.selftext === 'string' && (r.title || r.selftext).trim()) {
+    return [r.title, r.selftext].filter(Boolean).join('\n').trim();
+  }
+  if (typeof r.text === 'string' && r.text.trim()) return r.text;
+  if (typeof r.title === 'string' && r.title.trim()) return r.title;
+  return '';
+}
+
+// Parse a local dump (JSONL or JSON array / {posts|data:[...]}). THROWS on missing/unreadable.
+export function parseDump(dumpPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(dumpPath, 'utf8');
+  } catch (e) {
+    throw new Error(`cannot read dump ${dumpPath}: ${e.code || e.message}`);
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) throw new Error(`empty dump ${dumpPath}`);
+  // JSON array or object first (cheap to detect by first non-space char).
+  if (trimmed[0] === '[' || trimmed[0] === '{') {
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      parsed = null;
+    }
+    if (parsed) {
+      if (Array.isArray(parsed)) return parsed;
+      if (Array.isArray(parsed.posts)) return parsed.posts;
+      if (Array.isArray(parsed.data)) return parsed.data;
+      // a single object on one line is not a valid corpus
+    }
+  }
+  // JSONL: one object per line, tolerant of blank lines.
+  const rows = [];
+  for (const line of trimmed.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try {
+      rows.push(JSON.parse(s));
+    } catch {
+      // skip an unparseable line rather than abort the whole ingest
+    }
+  }
+  if (!rows.length) throw new Error(`no parseable rows in dump ${dumpPath}`);
+  return rows;
+}
+
+// groupByAuthor(rows, cfg) → [{ id, docs:[...] }] for authors clearing the floors. Deleted/
+// bot/empty authors and near-empty bodies are dropped. Stable order: by author handle.
+export function groupByAuthor(rows, cfg = REDDIT_DEFAULTS) {
+  const c = { ...REDDIT_DEFAULTS, ...cfg };
+  const byAuthor = new Map();
+  for (const r of rows) {
+    const author = pickAuthor(r);
+    if (DELETED_AUTHORS.has(author.toLowerCase())) continue;
+    const body = pickBody(r);
+    if (!body || body.length < c.minBodyChars) continue;
+    if (!byAuthor.has(author)) byAuthor.set(author, []);
+    byAuthor.get(author).push(body);
+  }
+  const out = [];
+  for (const [id, docs] of byAuthor) {
+    if (docs.length < c.minDocsPerAuthor) continue;
+    const tokens = docs.reduce((s, d) => s + tokenizeWords(d).length, 0);
+    if (tokens < c.minTokensPerAuthor) continue;
+    out.push({ id, docs });
+  }
+  out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return out;
+}
+
+// ingestRedditCorpus(dumpPath, opts) → { corpus, foreigners, stats }.
+//   corpus     — nPersonaAuthors qualifying authors (the {id,docs} loadRealPersonas wants)
+//   foreigners — nForeignAuthors DISJOINT qualifying authors (same-register pool; same file
+//                ⇒ same subreddit ⇒ same register by construction)
+// Selection + partition are a pure function of `seed` and author identity — NEVER of any
+// style distance (selection-bias guard, mirrors real-personas). THROWS if too few qualify.
+export function ingestRedditCorpus(dumpPath, opts = {}) {
+  const cfg = { ...REDDIT_DEFAULTS, ...opts };
+  const rows = parseDump(dumpPath);
+  const qualifying = groupByAuthor(rows, cfg);
+
+  const need = cfg.nPersonaAuthors + cfg.nForeignAuthors;
+  if (qualifying.length < need) {
+    throw new Error(
+      `too few qualifying authors: ${qualifying.length} < ${need} `
+      + `(personas ${cfg.nPersonaAuthors} + foreigners ${cfg.nForeignAuthors}); ingest more — do not underpower`,
+    );
+  }
+
+  // Seeded deterministic order, independent of content/style distance.
+  const ordered = [...qualifying].sort((a, b) => {
+    const ha = fnv1a(`${cfg.seed}:${a.id}`);
+    const hb = fnv1a(`${cfg.seed}:${b.id}`);
+    return ha - hb || (a.id < b.id ? -1 : 1);
+  });
+
+  const corpus = ordered.slice(0, cfg.nPersonaAuthors);
+  const foreigners = ordered.slice(cfg.nPersonaAuthors, cfg.nPersonaAuthors + cfg.nForeignAuthors);
+
+  return {
+    corpus,
+    foreigners,
+    stats: {
+      totalRows: rows.length,
+      qualifyingAuthors: qualifying.length,
+      personaAuthors: corpus.length,
+      foreignAuthors: foreigners.length,
+      minDocsPerAuthor: cfg.minDocsPerAuthor,
+      minTokensPerAuthor: cfg.minTokensPerAuthor,
+    },
+  };
+}
+
+export const __test = { fnv1a, pickAuthor, pickBody };
+export default { ingestRedditCorpus, groupByAuthor, parseDump, REDDIT_DEFAULTS };

package/src/profile/eval/corpus-from-reddit.test.mjs

@@ -0,0 +1,121 @@
+// Gate B v2 — corpus-from-reddit ingest loader. Pure transform from a RAW local
+// single-subreddit dump to the {id,docs} corpus loadRealPersonas wants + a disjoint
+// same-register foreigner pool. The guards: fail-closed on too-few-authors / too-short
+// (never silently underpower), author grouping is deterministic, the foreigner pool is
+// disjoint from the persona corpus, and NO network is ever touched.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  groupByAuthor, ingestRedditCorpus, REDDIT_DEFAULTS,
+} from './corpus-from-reddit.mjs';
+
+// ---- fixtures: synthetic Reddit-shaped rows (no network) ----
+// One long post per row; many rows per author so each author clears the doc-count + token floors.
+function row(author, body, id) {
+  return {
+    author, body, id: id || `${author}-${Math.random().toString(36).slice(2)}`, subreddit: 'testsub',
+  };
+}
+const LONG = 'This is a reasonably long body of text written by a real person on a forum. '
+  + 'It contains several sentences so that the token floor is comfortably cleared by each document. '
+  + 'People tend to ramble a bit when they post, which is convenient for stylometry. '
+  + 'The quick brown fox jumped over the lazy dog while the cat watched from a distance, unimpressed.';
+
+function makeAuthorRows(author, nDocs) {
+  return Array.from({ length: nDocs }, (_, i) => row(author, `${LONG} (post ${i} by ${author})`, `${author}-${i}`));
+}
+
+function writeJsonl(rows) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'reddit-fix-'));
+  const p = path.join(dir, 'dump.jsonl');
+  fs.writeFileSync(p, rows.map((r) => JSON.stringify(r)).join('\n'));
+  return p;
+}
+function writeJson(rows) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'reddit-fix-'));
+  const p = path.join(dir, 'dump.json');
+  fs.writeFileSync(p, JSON.stringify(rows));
+  return p;
+}
+
+// 10 authors × 6 long docs each — comfortably over the floors.
+function tenAuthors() {
+  const rows = [];
+  for (let a = 0; a < 10; a += 1) rows.push(...makeAuthorRows(`u${a}`, 6));
+  return rows;
+}
+// Fixtures use small docs; pass a fixture-scaled token floor (production default = 1800).
+const FIX = { minTokensPerAuthor: 200 };
+
+test('groupByAuthor: groups rows into {id,docs}, drops deleted/bot/empty authors', () => {
+  const rows = [
+    row('alice', 'hello world one'), row('alice', 'hello world two'),
+    row('[deleted]', 'should be dropped'), row('AutoModerator', 'bot post'),
+    row('', 'empty author'), row('bob', 'a post by bob'),
+  ];
+  // minTokensPerAuthor:0 + minDocsPerAuthor:1 isolates the AUTHOR-dropping behavior under test.
+  const grouped = groupByAuthor(rows, { minTokensPerAuthor: 0, minDocsPerAuthor: 1, minBodyChars: 1 });
+  const ids = grouped.map((g) => g.id).sort();
+  assert.deepEqual(ids, ['alice', 'bob']);
+  assert.equal(grouped.find((g) => g.id === 'alice').docs.length, 2);
+});
+
+test('ingest emits the {id,docs} corpus shape loadRealPersonas consumes', () => {
+  const p = writeJsonl(tenAuthors());
+  const { corpus } = ingestRedditCorpus(p, { nPersonaAuthors: 4, nForeignAuthors: 4, ...FIX });
+  assert.ok(Array.isArray(corpus) && corpus.length === 4);
+  for (const author of corpus) {
+    assert.ok(typeof author.id === 'string' && author.id.length > 0);
+    assert.ok(Array.isArray(author.docs) && author.docs.length >= REDDIT_DEFAULTS.minDocsPerAuthor);
+    assert.ok(author.docs.every((d) => typeof d === 'string'));
+  }
+});
+
+test('foreigner pool is DISJOINT from the persona corpus', () => {
+  const p = writeJsonl(tenAuthors());
+  const { corpus, foreigners } = ingestRedditCorpus(p, { nPersonaAuthors: 4, nForeignAuthors: 4, ...FIX });
+  const cIds = new Set(corpus.map((a) => a.id));
+  const fIds = new Set(foreigners.map((a) => a.id));
+  for (const id of fIds) assert.ok(!cIds.has(id), `foreigner ${id} must not be a persona`);
+  assert.equal(foreigners.length, 4);
+});
+
+test('accepts a JSON-array dump as well as JSONL', () => {
+  const p = writeJson(tenAuthors());
+  const { corpus } = ingestRedditCorpus(p, { nPersonaAuthors: 3, nForeignAuthors: 3, ...FIX });
+  assert.equal(corpus.length, 3);
+});
+
+test('FAIL-CLOSED: too few qualifying authors THROWS (never silently underpowers)', () => {
+  const rows = [...makeAuthorRows('only1', 6), ...makeAuthorRows('only2', 6)];
+  const p = writeJsonl(rows);
+  assert.throws(
+    () => ingestRedditCorpus(p, { nPersonaAuthors: 4, nForeignAuthors: 4, ...FIX }),
+    /qualifying authors|too few/i,
+  );
+});
+
+test('FAIL-CLOSED: authors below the doc-count floor are dropped, not padded', () => {
+  // u_short has only 1 doc (< minDocsPerAuthor) → must not appear
+  const rows = [...tenAuthors(), row('u_short', LONG)];
+  const p = writeJsonl(rows);
+  const { corpus, foreigners } = ingestRedditCorpus(p, { nPersonaAuthors: 5, nForeignAuthors: 5, ...FIX });
+  const all = new Set([...corpus, ...foreigners].map((a) => a.id));
+  assert.ok(!all.has('u_short'), 'under-floor author excluded');
+});
+
+test('FAIL-CLOSED: a missing dump file THROWS', () => {
+  assert.throws(() => ingestRedditCorpus('/no/such/dump.jsonl', {}), /ENOENT|not found|read/i);
+});
+
+test('selection is deterministic for a fixed seed (same authors, same order)', () => {
+  const p = writeJsonl(tenAuthors());
+  const a = ingestRedditCorpus(p, { nPersonaAuthors: 4, nForeignAuthors: 3, seed: 7, ...FIX });
+  const b = ingestRedditCorpus(p, { nPersonaAuthors: 4, nForeignAuthors: 3, seed: 7, ...FIX });
+  assert.deepEqual(a.corpus.map((x) => x.id), b.corpus.map((x) => x.id));
+  assert.deepEqual(a.foreigners.map((x) => x.id), b.foreigners.map((x) => x.id));
+});

package/src/profile/eval/corpus-from-transcripts.mjs

@@ -0,0 +1,264 @@
+/**
+ * profile/eval/corpus-from-transcripts.mjs — REAL-CORPUS builder for the
+ * profile-bus eval (v1.6.0). Turns the user's OWN Claude Code transcripts into
+ * the `{ sessions, feedback }` shape the REAL capture/derive pipeline consumes,
+ * so Gate B/C can be run against genuine "learns YOU" data instead of a synthetic
+ * fixture.
+ *
+ * ── PRIVACY (the load-bearing invariant) ───────────────────────────────────
+ * Raw transcript TEXT never leaves this process and is never persisted as a
+ * style record. Each user message is reduced to COUNTS via the REAL
+ * `extractMessageMetadata` (capture.js) and the string is discarded. The ONLY
+ * place raw-ish text survives is a `.session-feedback.jsonl` row's `context`
+ * snippet (the feedback detector's 120-char window) — and that file is written
+ * ONLY to the local, gitignored scratch dir and is NEVER sent to any cloud API
+ * (the cloud only ever sees the DERIVED brief = slugs, plus authored prompts).
+ *
+ * ── METHOD ─────────────────────────────────────────────────────────────────
+ *  1. Walk ~/.claude/projects/<projectDir>/<uuid>.jsonl.
+ *  2. Keep lines: type==='user' AND message.content is a STRING AND NOT isMeta
+ *     AND not a slash-command/hook/system artifact (those are not the user's
+ *     own authored prose — counting them would poison the style fingerprint).
+ *  3. Group by sessionId. For each session: fold per-message metadata into a
+ *     counts-only accumulator (mirrors capture.js flushSession math EXACTLY) and
+ *     run the REAL `detectFeedback` over each human message → feedback rows.
+ *  4. Emit one session record per session with: a `metadata` block in the exact
+ *     `toDeriveMeta`/deriveStyle input shape, a `feedback[]` array in the
+ *     .session-feedback.jsonl shape, a session `ts` (first human-message time),
+ *     and `host: 'claude-code'`.
+ *
+ * Zero deps. Node built-ins only. No network. No LLM.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { extractMessageMetadata } from '../capture.js';
+import { detectFeedback } from '../../feedback-detector.js';
+
+/** Default corpus root: the user's real Claude Code transcript store. */
+export function defaultProjectsRoot() {
+  return join(homedir(), '.claude', 'projects');
+}
+
+/**
+ * A user message line is "authored human prose" iff it is a plain string turn
+ * that is NOT a slash-command expansion, hook-injected context, system reminder,
+ * tool-result echo, or interrupt marker. These artifacts are machine-authored
+ * (or template-expanded) and counting them would corrupt the style signal.
+ */
+const ARTIFACT_PREFIXES = [
+  '<command-name>', '<command-message>', '<command-args>', '<local-command-',
+  '<system-reminder', '<user-memory-input>', 'Caveat:', '[Request interrupted',
+  '<bash-', '<task-', '<post-tool-use', '<pre-tool-use',
+];
+function isAuthoredHumanText(text) {
+  if (typeof text !== 'string') return false;
+  const t = text.trim();
+  if (!t) return false;
+  for (const p of ARTIFACT_PREFIXES) if (t.startsWith(p)) return false;
+  // A pasted system-reminder block mid-text is still machine context.
+  if (t.startsWith('<') && t.includes('</')) return false;
+  return true;
+}
+
+/** Per-session counts accumulator — identical math to capture.js flushSession. */
+function freshAcc(sessionId) {
+  return {
+    session_id: sessionId,
+    first_ts: null, last_ts: null,
+    msg_count: 0, total_chars: 0, total_emojis: 0,
+    code_msgs: 0, formality_msgs: 0,
+    feedback: [],
+  };
+}
+
+function clamp01(x) {
+  const n = Number(x);
+  if (!Number.isFinite(n)) return 0;
+  return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+
+/**
+ * Fold one accumulator into the eval session record. Mirrors capture.js
+ * flushSession's field derivation (avg_msg_chars / emoji_rate / code_block_ratio
+ * / formality_markers / turn_cadence_s) then maps to the deriveStyle input shape
+ * (emoji_per_msg, turn_cadence_per_min) — exactly toDeriveMeta's transform — so
+ * the heuristic derive sees production-identical metadata.
+ */
+function accToSession(acc, host) {
+  const n = acc.msg_count;
+  if (n <= 0) return null;
+  const avgChars = acc.total_chars / n;
+  const emojiRate = acc.total_emojis / n;
+  const codeRatio = clamp01(acc.code_msgs / n);
+  const formality = clamp01(acc.formality_msgs / n);
+  let cadenceS = 0;
+  if (n > 1 && Number.isFinite(acc.first_ts) && Number.isFinite(acc.last_ts) && acc.last_ts > acc.first_ts) {
+    cadenceS = ((acc.last_ts - acc.first_ts) / 1000) / (n - 1);
+  }
+  const metadata = {
+    avg_msg_chars: Math.round(avgChars * 100) / 100,
+    emoji_per_msg: Math.round(emojiRate * 1000) / 1000,
+    code_block_ratio: Math.round(codeRatio * 1000) / 1000,
+    formality_markers: Math.round(formality * 1000) / 1000,
+    turn_cadence_per_min: cadenceS > 0 ? Math.round((60 / cadenceS) * 1000) / 1000 : 0,
+  };
+  const tsIso = Number.isFinite(acc.first_ts) ? new Date(acc.first_ts).toISOString() : null;
+  // Stamp session_id/ts onto every feedback row (capture's contract).
+  const feedback = acc.feedback.map((f) => ({
+    session_id: acc.session_id,
+    ts: tsIso,
+    kind: f.kind,
+    phrase: f.phrase,
+    context: f.context,
+  }));
+  return {
+    session_id: acc.session_id,
+    sessionId: acc.session_id,
+    host,
+    ts: tsIso,
+    metadata,
+    feedback,
+    msg_count: n,
+  };
+}
+
+/**
+ * parseTranscript(file) -> Map<sessionId, acc>. One .jsonl may contain a single
+ * session (the common case) but we group by the line's own sessionId to be safe.
+ */
+function parseTranscript(file, accumulators, _host) {
+  let raw;
+  try { raw = readFileSync(file, 'utf8'); } catch { return; }
+  const lines = raw.split('\n');
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    if (!o || o.type !== 'user' || !o.message) continue;
+    if (o.isMeta === true) continue;
+    const content = o.message.content;
+    if (!isAuthoredHumanText(content)) continue; // string-only + non-artifact
+
+    const sid = String(o.sessionId || o.session_id || '').trim();
+    if (!sid) continue;
+    let acc = accumulators.get(sid);
+    if (!acc) { acc = freshAcc(sid); accumulators.set(sid, acc); }
+
+    // METADATA ONLY — extract counts, discard the string.
+    const meta = extractMessageMetadata(content);
+    acc.msg_count += 1;
+    acc.total_chars += meta.chars;
+    acc.total_emojis += meta.emojis;
+    if (meta.hasCode) acc.code_msgs += 1;
+    if (meta.formalityHits > 0) acc.formality_msgs += 1;
+
+    const t = Date.parse(o.timestamp);
+    if (Number.isFinite(t)) {
+      if (acc.first_ts === null || t < acc.first_ts) acc.first_ts = t;
+      if (acc.last_ts === null || t > acc.last_ts) acc.last_ts = t;
+    }
+
+    // REAL feedback detection over the human message (high-precision, low-recall).
+    for (const fb of detectFeedback(content)) {
+      acc.feedback.push(fb);
+    }
+  }
+}
+
+/**
+ * buildCorpus(opts) -> { sessions, stats }.
+ *
+ * @param {object} [opts]
+ *   @param {string} [opts.root]        projects root (default ~/.claude/projects)
+ *   @param {number} [opts.minMessages] keep sessions with >= this many human msgs (default 8)
+ *   @param {number} [opts.cap]         cap total kept sessions (stratified by project) (default 400)
+ *   @param {number} [opts.maxFiles]    safety cap on files scanned (default Infinity)
+ *
+ * Stratified sampling: we keep up to `perDir` sessions from each project dir so a
+ * few huge projects don't dominate the profile. Deterministic (sorted) ordering.
+ */
+export function buildCorpus(opts = {}) {
+  const root = opts.root || defaultProjectsRoot();
+  const minMessages = Number.isFinite(opts.minMessages) ? opts.minMessages : 8;
+  const cap = Number.isFinite(opts.cap) ? opts.cap : 400;
+  const host = 'claude-code';
+
+  let dirs = [];
+  try { dirs = readdirSync(root).filter((d) => !d.startsWith('.')); } catch {
+    return { sessions: [], stats: { error: `cannot read ${root}` } };
+  }
+  dirs.sort();
+
+  let filesScanned = 0;
+  let sessionsSeen = 0;
+  // Collect per-dir kept sessions for stratified capping.
+  const perDirSessions = new Map();
+  for (const d of dirs) {
+    const dirPath = join(root, d);
+    let files = [];
+    try { files = readdirSync(dirPath).filter((f) => f.endsWith('.jsonl')); } catch { continue; }
+    files.sort();
+    const accumulators = new Map();
+    for (const f of files) {
+      if (filesScanned >= (opts.maxFiles ?? Infinity)) break;
+      const full = join(dirPath, f);
+      try { if (!statSync(full).isFile()) continue; } catch { continue; }
+      parseTranscript(full, accumulators, host);
+      filesScanned += 1;
+    }
+    const kept = [];
+    for (const acc of accumulators.values()) {
+      sessionsSeen += 1;
+      if (acc.msg_count < minMessages) continue;
+      const sess = accToSession(acc, host);
+      if (sess && sess.ts) kept.push(sess);
+    }
+    // sort kept by ts so the per-dir slice is chronological + deterministic
+    kept.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+    if (kept.length) perDirSessions.set(d, kept);
+  }
+
+  // Stratified cap: round-robin across dirs until we hit `cap`.
+  const dirKeys = [...perDirSessions.keys()].sort();
+  const sessions = [];
+  let added = true;
+  const cursors = new Map(dirKeys.map((k) => [k, 0]));
+  while (added && sessions.length < cap) {
+    added = false;
+    for (const k of dirKeys) {
+      if (sessions.length >= cap) break;
+      const list = perDirSessions.get(k);
+      const i = cursors.get(k);
+      if (i < list.length) {
+        sessions.push(list[i]);
+        cursors.set(k, i + 1);
+        added = true;
+      }
+    }
+  }
+
+  // Final chronological sort (the eval split is time-based).
+  sessions.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+
+  const withFeedback = sessions.filter((s) => s.feedback.length > 0).length;
+  const totalFeedback = sessions.reduce((n, s) => n + s.feedback.length, 0);
+  return {
+    sessions,
+    stats: {
+      projectDirs: dirs.length,
+      filesScanned,
+      sessionsSeen,
+      sessionsKept: sessions.length,
+      minMessages,
+      cap,
+      sessionsWithFeedback: withFeedback,
+      totalFeedbackRows: totalFeedback,
+      tsMin: sessions.length ? sessions[0].ts : null,
+      tsMax: sessions.length ? sessions[sessions.length - 1].ts : null,
+    },
+  };
+}
+
+export default { buildCorpus, defaultProjectsRoot };