@ijfw/memory-server 1.5.5 → 1.6.0

package/src/profile/exemplar-capture.js

@@ -0,0 +1,232 @@
+/**
+ * profile/exemplar-capture.js — Voice exemplar capture (V1).
+ *
+ * Turns a raw piece of the USER's OWN natural-language writing (their prompt
+ * text, or a git commit message subject+body) into a bounded, PII-scrubbed
+ * Exemplar and appends it to the transient exemplar store. This is the capture
+ * side of the "draft in your voice" FEATURE — it is NOT a stylometry/authorship
+ * detector. No statistical ruler, no corpus, no LLM, no network.
+ *
+ * What we DELIBERATELY skip (don't pollute the voice set):
+ *   - empties / whitespace-only;
+ *   - slash-commands, IJFW control prompts (`*`, `/`, `#` leading, "ijfw off");
+ *   - pasted MACHINE OUTPUT — fenced code blocks, stack traces, diffs, JSON/log
+ *     dumps. We want the user's natural-language writing, not code they pasted;
+ *   - near-duplicates already in the store (dedup-by-id covers exact repeats;
+ *     we also normalize trivially so "Fix it." and "fix it" collapse).
+ *
+ * Best-effort + fully isolated: every entrypoint is wrapped so a malformed
+ * payload or a store write error NEVER throws into the caller (the hook must
+ * never crash Claude Code). Zero deps, Node built-ins only. NO LLM calls.
+ */
+
+import { appendExemplar, exemplarId, EXEMPLAR_TEXT_MAX } from './exemplar-store.js';
+
+// Direct-identifier patterns scrubbed before persist. Mirrors capture.js
+// EDIT_PII_PATTERNS in spirit (kept LOCAL on purpose so this module's import
+// graph stays zero-LLM/zero-network and independent of capture.js internals).
+// Keep deliberately in sync if either list grows.
+const PII_PATTERNS = [
+  /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi,            // email
+  /\b\d{3}-\d{2}-\d{4}\b/g,                              // US SSN shape
+  // eslint-disable-next-line security/detect-unsafe-regex -- linear-time PII redactor: each repetition consumes a mandatory digit, no ambiguous/overlapping quantifier; not ReDoS-exploitable.
+  /\b(?:\d[ -]?){13,19}\b/g,                             // card-ish long digit run
+  // eslint-disable-next-line security/detect-unsafe-regex -- linear-time PII redactor: each repetition consumes a mandatory digit, no ambiguous/overlapping quantifier; not ReDoS-exploitable.
+  /(?:\+?\d[\s().-]?){7,}\d/g,                           // phone-ish run of digits
+  /\b[A-Za-z0-9_-]*(?:secret|token|api[_-]?key|password|passwd|bearer)[A-Za-z0-9_-]*\s*[:=]\s*\S+/gi, // assigned secret
+  // Absolute homedir paths leak the OS username (/Users/<name>/, /home/<name>/,
+  // C:\Users\<name>\). Replace the user segment, keep the tail shape.
+  /(?:\/Users\/|\/home\/)[^/\s]+/g,                      // unix homedir
+  /[A-Za-z]:\\Users\\[^\\\s]+/g,                         // windows homedir
+];
+
+/** PII-scrub: replace direct identifiers with a placeholder token. */
+function scrub(text) {
+  let s = String(text == null ? '' : text);
+  for (const re of PII_PATTERNS) s = s.replace(re, ' ');
+  return s;
+}
+
+/**
+ * Looks like pasted machine output rather than natural-language writing.
+ * Heuristic — conservative (better to skip a borderline snippet than capture a
+ * log dump as "voice"). Triggers on: a fenced code block, a unified diff, a
+ * stack-trace frame, a shell-prompt dump, or a body that is mostly non-prose
+ * (high ratio of braces/semicolons/symbols to words).
+ */
+function looksMachine(text) {
+  const s = String(text || '');
+  if (!s.trim()) return false;
+  if (/```/.test(s)) return true;                         // fenced code block
+  if (/^\s*(?:diff --git|@@ -\d|index [0-9a-f]{7})/m.test(s)) return true; // diff
+  if (/^\s*(?:at\s+\S+\s+\(.*:\d+:\d+\)|Traceback \(most recent call last\))/m.test(s)) return true; // stack trace
+  if (/^\s*[$#>]\s+\S+/m.test(s) && /\n/.test(s)) return true; // shell session dump
+  // JSON / structured dump: starts like an object/array and is bracket-heavy.
+  const trimmed = s.trim();
+  if (/^[[{]/.test(trimmed) && /[}\]]\s*$/.test(trimmed)) {
+    try { JSON.parse(trimmed); return true; } catch { /* not strict JSON */ }
+  }
+  // Symbol density: count "code-ish" chars vs alphabetic word chars. A natural
+  // sentence is mostly letters/spaces; a code paste is dense with {};()=<>/.
+  // A short single-line paste like `const x = {a:1, b:()=>{...}};` has few
+  // multi-letter words but many symbols, so the floor is low (>=2 words) and the
+  // trigger is symbols >= words (a natural sentence has far more words).
+  const words = (s.match(/[A-Za-z]{2,}/g) || []).length;
+  const symbols = (s.match(/[{}();=<>/\\|&]/g) || []).length;
+  if (words >= 2 && symbols >= words) return true;
+  // Many lines that each look like code (end in ; or { or }) and few sentences.
+  const lines = s.split('\n').filter((l) => l.trim());
+  if (lines.length >= 3) {
+    const codeish = lines.filter((l) => /[;{}]\s*$/.test(l.trim())).length;
+    if (codeish / lines.length > 0.5) return true;
+  }
+  return false;
+}
+
+/** IJFW control / non-voice prompt prefixes we never capture as writing. */
+function isControlPrompt(text) {
+  const s = String(text || '').trim();
+  if (!s) return true;
+  if (/^[*/#]/.test(s)) return true;            // slash-command / skip / comment
+  if (/\bijfw\s+off\b/i.test(s)) return true;   // disable phrase
+  return false;
+}
+
+/** Collapse whitespace; used for length/heuristic measurement (not stored raw). */
+function collapse(text) {
+  return String(text || '').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * register(text, source) -> one of 'terse' | 'casual' | 'formal' | 'commit' | 'doc'.
+ *
+ * SIMPLE heuristic (no ML):
+ *   - source === 'commit-msg'                       → 'commit'
+ *   - markdown headers / list-y prose / multi-para  → 'doc'
+ *   - short + lowercase + light punctuation          → 'terse'
+ *   - long, multi-sentence, properly capitalized     → 'formal'
+ *   - everything else                                → 'casual'
+ */
+export function classifyRegister(text, source) {
+  if (source === 'commit-msg') return 'commit';
+  const raw = String(text || '');
+  const flat = collapse(raw);
+
+  // doc: markdown structure or genuine multi-paragraph prose.
+  const hasMarkdown = /(^|\n)\s{0,3}#{1,6}\s+\S/.test(raw) ||
+    /(^|\n)\s*[-*+]\s+\S/.test(raw) ||
+    /(^|\n)\s*\d+\.\s+\S/.test(raw) ||
+    /\n\s*\n/.test(raw.trim());
+  if (hasMarkdown && flat.length > 80) return 'doc';
+
+  const len = flat.length;
+  const sentences = (flat.match(/[.!?](?:\s|$)/g) || []).length;
+  const isLowercaseStart = /^[a-z]/.test(flat);
+  const punctRuns = (flat.match(/[.,;:!?]/g) || []).length;
+
+  // terse: short AND informal — either a lowercase start ("fix the typo") or no
+  // sentence-ending punctuation at all. A short but properly-capitalized,
+  // properly-punctuated question/request reads as casual, not terse.
+  const hasSentenceEnd = /[.!?]/.test(flat);
+  if (len <= 60 && (isLowercaseStart || !hasSentenceEnd) && punctRuns <= 1) return 'terse';
+
+  // formal: longish, multiple full sentences, capitalized opening. The length
+  // floor (110) separates a single capitalized request ("casual") from genuine
+  // multi-sentence prose with structure.
+  if (len >= 110 && sentences >= 2 && /^[A-Z]/.test(flat)) return 'formal';
+
+  return 'casual';
+}
+
+/**
+ * buildExemplar({ text, source, ts }) -> Exemplar | null.
+ *
+ * Pure. Returns a fully-formed Exemplar record, or null when the input should
+ * be skipped (empty, control prompt, machine output, or scrubs to nothing).
+ * The text is PII-scrubbed and bounded to EXEMPLAR_TEXT_MAX before the id is
+ * computed (so the id is stable over the FINAL stored text).
+ */
+export function buildExemplar({ text, source = 'prompt', ts } = {}) {
+  const original = String(text == null ? '' : text);
+  if (!original.trim()) return null;
+  if (source !== 'commit-msg' && isControlPrompt(original)) return null;
+  if (looksMachine(original)) return null;
+
+  // Scrub, then bound. We keep original line structure (don't collapse) so the
+  // stored snippet still reads like the user's writing, but cap the length.
+  let finalText = scrub(original).replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+  if (!finalText) return null;
+  if (finalText.length > EXEMPLAR_TEXT_MAX) {
+    finalText = finalText.slice(0, EXEMPLAR_TEXT_MAX).trim();
+  }
+  // After scrub+bound the snippet must still carry SOME natural-language signal
+  // (at least a couple of word characters). A snippet that scrubbed down to
+  // punctuation/placeholders is not worth keeping as voice.
+  if ((finalText.match(/[A-Za-z]{2,}/g) || []).length < 2) return null;
+
+  const src = source === 'commit-msg' ? 'commit-msg' : 'prompt';
+  return {
+    id: exemplarId(finalText),
+    text: finalText,
+    register: classifyRegister(finalText, src),
+    source: src,
+    ts: ts ? new Date(ts).toISOString() : new Date().toISOString(),
+  };
+}
+
+/**
+ * captureMessage({ text, ts, opts }) -> { ok, skipped?, id? } | { ok:false }.
+ *
+ * Best-effort capture of the user's OWN prompt text as a 'prompt'-source
+ * exemplar. Fully isolated: never throws. A skipped input (empty/control/
+ * machine) returns { ok:true, skipped:true }. Mirrors the call shape the
+ * pre-prompt hook already uses for capture.js's captureMessage.
+ */
+export function captureMessage({ text, ts, opts } = {}) {
+  try {
+    const ex = buildExemplar({ text, source: 'prompt', ts });
+    if (!ex) return { ok: true, skipped: true };
+    const r = appendExemplar(ex, opts || {});
+    if (!r.ok) return { ok: false, code: r.code, message: r.message };
+    return { ok: true, id: ex.id, removed: r.removed };
+  } catch (err) {
+    // Never surface into the hook caller.
+    return { ok: false, code: 'ECAPTURE', message: err && err.message };
+  }
+}
+
+/**
+ * captureCommitMessage(msg, opts?) -> { ok, skipped?, id? } | { ok:false }.
+ *
+ * Best-effort capture of a git commit message (subject + body) as a 'commit-msg'
+ * exemplar. `msg` may be the raw `git log -1 --format=%B` style string. We strip
+ * trailers (Co-Authored-By, Signed-off-by, the IJFW 🤖 line) and comment lines
+ * so the captured voice is the user's actual prose, not boilerplate. Wiring this
+ * into a real git hook is OUT OF SCOPE for V1 — this function is the seam.
+ * Fully isolated: never throws.
+ */
+export function captureCommitMessage(msg, opts = {}) {
+  try {
+    const raw = String(msg == null ? '' : msg);
+    if (!raw.trim()) return { ok: true, skipped: true };
+    // Drop comment lines (git's `#`-prefixed scissor lines) and known trailers.
+    const cleaned = raw
+      .split('\n')
+      .filter((line) => {
+        const t = line.trim();
+        if (t.startsWith('#')) return false;
+        if (/^(?:Co-Authored-By|Signed-off-by|Co-authored-by):/i.test(t)) return false;
+        if (/Generated with \[Claude Code\]/i.test(t)) return false;
+        if (t.startsWith('🤖')) return false;
+        return true;
+      })
+      .join('\n');
+    const ex = buildExemplar({ text: cleaned, source: 'commit-msg', ts: opts.ts });
+    if (!ex) return { ok: true, skipped: true };
+    const r = appendExemplar(ex, opts || {});
+    if (!r.ok) return { ok: false, code: r.code, message: r.message };
+    return { ok: true, id: ex.id, removed: r.removed };
+  } catch (err) {
+    return { ok: false, code: 'ECAPTURE', message: err && err.message };
+  }
+}

package/src/profile/exemplar-retrieve.js

@@ -0,0 +1,138 @@
+// V2 — exemplar retrieval (voice exemplars feature).
+//
+// ZERO-LLM serve path ("the moat"). This module ranks the user's OWN real
+// writing samples (exemplars) so the agent can few-shot draft in their voice.
+// It MUST NOT import any LLM / network / embedder module. Pure ranking only:
+//   register-match boost  +  lexical similarity (BM25)  +  recency tiebreak.
+//
+// Exemplar record contract (shared with the store, V1):
+//   { id, text, register: 'terse'|'casual'|'formal'|'commit'|'doc',
+//     source: 'prompt'|'commit-msg', ts: ISO-string }
+
+import { createRequire } from 'node:module';
+import { searchCorpus } from '../search-bm25.js';
+
+// V1's store (exemplar-store.js → listExemplars) is built in parallel and is
+// only needed when the caller does NOT inject a candidate set. We therefore
+// load it LAZILY (synchronous require-of-ESM, stable in Node ≥22): a static
+// import would couple this module's load-time to V1's build order, and would
+// crash the zero-LLM serve path before V1 lands. The injected-exemplars path
+// (and every test that uses it) stays fully decoupled from the store.
+const require = createRequire(import.meta.url);
+function loadFromStore() {
+  try {
+    const mod = require('./exemplar-store.js');
+    if (mod && typeof mod.listExemplars === 'function') return mod.listExemplars();
+  } catch {
+    /* store not available yet — treat as cold-start (empty set). */
+  }
+  return [];
+}
+
+// Blend weights. Register match dominates (we want same-register voice first),
+// lexical relevance is the primary tiebreak among same-register candidates,
+// recency is a gentle final nudge so newer writing wins on equal footing.
+const W_REGISTER = 1.0;
+const W_LEXICAL = 0.6;
+const W_RECENCY = 0.1;
+
+// Parse an ISO timestamp to epoch millis; non-parseable → 0 (treated oldest).
+function tsMillis(ts) {
+  if (typeof ts !== 'string' || !ts) return 0;
+  const t = Date.parse(ts);
+  return Number.isNaN(t) ? 0 : t;
+}
+
+// Map each candidate's ts into a [0,1] recency factor relative to the set.
+// Newest → 1, oldest → 0. A single distinct ts (or none) → 0 for all, so
+// recency never perturbs an otherwise-tied ordering arbitrarily.
+function recencyFactors(exemplars) {
+  const millis = exemplars.map((e) => tsMillis(e.ts));
+  let min = Infinity;
+  let max = -Infinity;
+  for (const m of millis) {
+    if (m < min) min = m;
+    if (m > max) max = m;
+  }
+  const span = max - min;
+  const out = new Map();
+  for (let i = 0; i < exemplars.length; i++) {
+    out.set(exemplars[i].id, span > 0 ? (millis[i] - min) / span : 0);
+  }
+  return out;
+}
+
+/**
+ * Return up to `k` exemplars most relevant to the current drafting task,
+ * best-first. Deterministic: equal inputs → identical ordering.
+ *
+ * @param {object}   args
+ * @param {string}  [args.register]   Target register to prefer (strong boost).
+ * @param {string}  [args.taskText]   Current drafting task text (lexical signal).
+ * @param {number}  [args.k=3]        Max exemplars to return.
+ * @param {Array}   [args.exemplars]  Candidate set (DI); if null, loads via store.
+ * @param {object}  [args.env]        Env (unused here; kept for interface parity).
+ * @returns {Array} ranked exemplars (the original records), best-first.
+ */
+export function retrieveExemplars({
+  register,
+  taskText,
+  k = 3,
+  exemplars = null,
+  env = process.env, // eslint-disable-line no-unused-vars -- interface parity
+} = {}) {
+  // Load candidates if not injected. listExemplars returns NEWEST-first.
+  let candidates = Array.isArray(exemplars) ? exemplars : loadFromStore();
+  if (!Array.isArray(candidates) || candidates.length === 0) return [];
+
+  // Defensive copy so we never mutate the caller's / store's array.
+  candidates = candidates.filter((e) => e && typeof e === 'object');
+  if (candidates.length === 0) return [];
+
+  const limit = Number.isFinite(k) && k > 0 ? Math.floor(k) : 0;
+  if (limit === 0) return [];
+
+  const query = typeof taskText === 'string' ? taskText.trim() : '';
+
+  // Lexical scores via the repo's pure BM25 primitive over in-memory docs.
+  // Normalize to [0,1] within this candidate set so the lexical contribution
+  // is bounded and comparable to the register boost regardless of corpus size.
+  const lexical = new Map();
+  if (query) {
+    const docs = candidates.map((e) => ({
+      id: e.id,
+      text: typeof e.text === 'string' ? e.text : '',
+      meta: null,
+    }));
+    // limit = full set so every candidate that scores > 0 is captured.
+    const hits = searchCorpus(query, docs, { limit: docs.length });
+    let maxScore = 0;
+    for (const h of hits) if (h.score > maxScore) maxScore = h.score;
+    if (maxScore > 0) {
+      for (const h of hits) lexical.set(h.id, h.score / maxScore);
+    }
+  }
+
+  const recency = recencyFactors(candidates);
+
+  const scored = candidates.map((e) => {
+    const registerMatch = register && e.register === register ? 1 : 0;
+    const lex = lexical.get(e.id) ?? 0;
+    const rec = recency.get(e.id) ?? 0;
+    const score = W_REGISTER * registerMatch + W_LEXICAL * lex + W_RECENCY * rec;
+    return { e, score };
+  });
+
+  // Deterministic ordering: composite score desc, then newer ts, then id asc.
+  scored.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const tb = tsMillis(b.e.ts);
+    const ta = tsMillis(a.e.ts);
+    if (tb !== ta) return tb - ta;
+    const ia = String(a.e.id);
+    const ib = String(b.e.id);
+    return ia < ib ? -1 : ia > ib ? 1 : 0;
+  });
+
+  return scored.slice(0, limit).map((s) => s.e);
+}

package/src/profile/exemplar-store.js

@@ -0,0 +1,314 @@
+/**
+ * profile/exemplar-store.js — Voice exemplars (V1: capture + transient store).
+ *
+ * An "exemplar" is a short raw snippet of the USER's OWN natural-language
+ * writing — their prompt text, or a git commit message subject+body. Holding a
+ * handful of these lets a downstream drafter few-shot the user's real voice
+ * (NOT a stylometry/authorship ruler — this is a FEATURE, not a research proof).
+ *
+ * TIER (deliberately narrow): this is a LOCAL-ONLY, TRANSIENT tier. It is
+ *   - bounded (MAX_EXEMPLARS records; oldest-by-ts evicted when over cap),
+ *   - dedup-by-id,
+ *   - one-shot wipeable (clearExemplars),
+ * and it is NEVER promoted to the durable/global/cross-project user profile.
+ * It lives beside the profile in the SAME directory so it inherits the profile
+ * path policy for free — including the test-context auto-tmpdir guarantee
+ * (path-policy.js homedirProfileDefault), so a forgetful test can NEVER write
+ * into the user's real ~/.ijfw/profile.
+ *
+ * Storage: a single JSONL file under profileDir(). One Exemplar record per line.
+ * Reads are symlink-guarded and size-capped; writes are atomic (temp in the same
+ * dir → fsync → rename), mirroring store.js. Zero deps, Node built-ins only.
+ * NO LLM calls.
+ *
+ * Exemplar record (the SHARED contract — V2/V4 code against this):
+ *   {
+ *     id: string,        // stable: `exemplar::${sha8(text)}`
+ *     text: string,      // raw snippet, bounded (~600 chars), PII-scrubbed
+ *     register: string,  // 'terse' | 'casual' | 'formal' | 'commit' | 'doc'
+ *     source: string,    // 'prompt' | 'commit-msg'
+ *     ts: string         // ISO-8601
+ *   }
+ */
+
+import {
+  openSync,
+  writeFileSync,
+  fsyncSync,
+  closeSync,
+  renameSync,
+  unlinkSync,
+  readFileSync,
+  existsSync,
+  mkdirSync,
+  lstatSync,
+  constants as fsConstants,
+} from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes, createHash } from 'node:crypto';
+
+import { resolveOverrideDir, homedirProfileDefault } from './path-policy.js';
+
+const EXEMPLAR_FILE = 'exemplars.jsonl';
+
+/** Max exemplars retained. Over cap → evict oldest by `ts` (transient tier). */
+export const MAX_EXEMPLARS = 200;
+
+/** Hard cap on a single exemplar's text length (chars). Mirrors the capture bound. */
+export const EXEMPLAR_TEXT_MAX = 600;
+
+/**
+ * Max bytes we will read from the on-disk JSONL. The store is bounded by
+ * MAX_EXEMPLARS short records, so a file larger than this is a corrupt/hand-
+ * edited artifact; refusing to slurp it whole avoids an OOM. ~2 MiB is orders
+ * of magnitude above any legitimate exemplar set (200 × 600 chars ≈ 120 KiB).
+ */
+const MAX_STORE_BYTES = 2 * 1024 * 1024;
+
+/** Short stable content hash → the dedupe key inside the exemplar id. */
+export function sha8(text) {
+  return createHash('sha256').update(String(text == null ? '' : text)).digest('hex').slice(0, 8);
+}
+
+/** The stable exemplar id for a given (already-final) text. */
+export function exemplarId(text) {
+  return `exemplar::${sha8(text)}`;
+}
+
+/**
+ * The JSONL store path. Routed through profileDir() so it inherits the profile
+ * path policy — in a test context profileDir() resolves under os.tmpdir(), so
+ * this path is NEVER under the real ~/.ijfw. See store.js / path-policy.js.
+ */
+export function exemplarStorePath(env = process.env) {
+  // Mirror profileDir()'s resolution exactly, but thread `env` explicitly so a
+  // caller-supplied env override is honored WITHOUT mutating the process-global
+  // process.env (that round-trip was a concurrency footgun). When env === the
+  // process default this is byte-identical to profileDir(). The policy's own
+  // resolveOverrideDir() applies the safety gate (homedir-scoping, symlink
+  // refusal); homedirProfileDefault() applies the test-context auto-tmpdir.
+  const safe = resolveOverrideDir(env.IJFW_PROFILE_DIR, env);
+  const dir = safe || homedirProfileDefault(['.ijfw', 'profile'], env);
+  return join(dir, EXEMPLAR_FILE);
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/** True iff `p` exists AND is a symlink (refuse to read/write through it). */
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** Validate a record loosely against the contract; drop anything malformed. */
+function isValidRecord(r) {
+  return (
+    r &&
+    typeof r === 'object' &&
+    typeof r.id === 'string' &&
+    r.id &&
+    typeof r.text === 'string' &&
+    typeof r.register === 'string' &&
+    typeof r.source === 'string' &&
+    typeof r.ts === 'string'
+  );
+}
+
+/**
+ * Read the raw record set from disk (insertion order = file order). Best-effort:
+ * a missing file → []; a symlinked/oversized/garbage file → [] (fail-soft, the
+ * transient tier is reconstructable). Malformed lines are skipped individually.
+ */
+function readRaw(opts = {}) {
+  const path = opts.path || exemplarStorePath(opts.env || process.env);
+  if (isSymlink(path)) return [];
+  if (!existsSync(path)) return [];
+  try {
+    const st = lstatSync(path);
+    if (st.isFile() && st.size > MAX_STORE_BYTES) return [];
+  } catch {
+    return [];
+  }
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    let rec;
+    try {
+      rec = JSON.parse(t);
+    } catch {
+      continue;
+    }
+    if (isValidRecord(rec)) out.push(rec);
+  }
+  return out;
+}
+
+/**
+ * Atomic full-file rewrite of the JSONL store (records in file order). Symlink-
+ * guarded both before and right before rename (TOCTOU narrowing). Returns
+ * { ok } | { ok:false, code, message }; never throws.
+ */
+function writeRaw(records, opts = {}) {
+  const target = opts.path || exemplarStorePath(opts.env || process.env);
+  if (isSymlink(target)) {
+    return { ok: false, code: 'EEXEMPLAR_SYMLINK', message: `refusing symlinked target: ${target}` };
+  }
+  const dir = join(target, '..');
+  try {
+    ensureDir(dir);
+  } catch (err) {
+    return { ok: false, code: err.code || 'EMKDIR', message: err.message };
+  }
+  const body = records.map((r) => JSON.stringify(r)).join('\n') + (records.length ? '\n' : '');
+  const tmp = `${target}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+  let fd;
+  try {
+    fd = openSync(
+      tmp,
+      fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(fd, body, 'utf8');
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    if (isSymlink(target)) {
+      try { unlinkSync(tmp); } catch {}
+      return { ok: false, code: 'EEXEMPLAR_SYMLINK', message: `target became a symlink: ${target}` };
+    }
+    renameSync(tmp, target);
+    return { ok: true };
+  } catch (err) {
+    if (fd != null) { try { closeSync(fd); } catch {} }
+    try { unlinkSync(tmp); } catch {}
+    return { ok: false, code: err.code || 'EWRITE', message: err.message };
+  }
+}
+
+/** Chronological sort key — ISO-8601 sorts lexicographically; fall back to id. */
+function tsKey(r) {
+  return `${r.ts || ''}::${r.id || ''}`;
+}
+
+/**
+ * appendExemplar(rec, opts?) -> { ok, removed?, code?, message? }.
+ *
+ * Adds one Exemplar to the transient store. Behavior:
+ *   - dedup by `id`: a record whose id already exists is treated as a refresh —
+ *     the existing copy is replaced (kept once), no growth. removed counts any
+ *     records evicted to honor the cap (NOT the dedup replacement).
+ *   - bound: after insert, if over MAX_EXEMPLARS, evict the OLDEST by `ts`.
+ *   - the file is rewritten atomically newest-by-insertion last.
+ * Fail-soft: a bad record → { ok:false, code:'EINVALID' }; a write error →
+ * { ok:false, code, message }. Never throws.
+ */
+export function appendExemplar(rec, opts = {}) {
+  if (!isValidRecord(rec)) {
+    return { ok: false, code: 'EINVALID', message: 'record does not satisfy the exemplar contract' };
+  }
+  const cap = Number.isInteger(opts.max) && opts.max > 0 ? opts.max : MAX_EXEMPLARS;
+  const existing = readRaw(opts);
+
+  // Dedup by id: drop any prior copy, then append the fresh one at the end.
+  const filtered = existing.filter((r) => r.id !== rec.id);
+  filtered.push(rec);
+
+  // Bound: evict oldest by ts until within cap. We sort a COPY by ts to find the
+  // oldest, but preserve file order otherwise. Simplest correct approach: while
+  // over cap, find the min-ts record and remove it.
+  let removed = 0;
+  while (filtered.length > cap) {
+    let minIdx = 0;
+    for (let i = 1; i < filtered.length; i += 1) {
+      if (tsKey(filtered[i]) < tsKey(filtered[minIdx])) minIdx = i;
+    }
+    filtered.splice(minIdx, 1);
+    removed += 1;
+  }
+
+  const w = writeRaw(filtered, opts);
+  if (!w.ok) return w;
+  return { ok: true, removed };
+}
+
+/**
+ * listExemplars(opts?) -> Exemplar[], NEWEST-first (by ts, then id for ties).
+ * A read-only view of the current set. Missing/corrupt store → [].
+ */
+export function listExemplars(opts = {}) {
+  const recs = readRaw(opts);
+  return recs.sort((a, b) => {
+    const ka = tsKey(a);
+    const kb = tsKey(b);
+    if (ka < kb) return 1;
+    if (ka > kb) return -1;
+    return 0;
+  });
+}
+
+/**
+ * forgetExemplars(idOrPattern, opts?) -> { ok, removed }.
+ *   - a string equal to an existing id → removes that one record;
+ *   - any other string → treated as a case-insensitive substring/regex match
+ *     against id + text (a "pattern"): every matching record is removed;
+ *   - a RegExp → matched against id + text.
+ * Removing nothing is still { ok:true, removed:0 }. Fail-soft on write error.
+ */
+export function forgetExemplars(idOrPattern, opts = {}) {
+  const existing = readRaw(opts);
+  if (!existing.length) return { ok: true, removed: 0 };
+
+  let predicate;
+  if (idOrPattern instanceof RegExp) {
+    predicate = (r) => idOrPattern.test(r.id) || idOrPattern.test(r.text);
+  } else {
+    const s = String(idOrPattern == null ? '' : idOrPattern);
+    if (!s) return { ok: true, removed: 0 };
+    // Exact id match first (precise forget), else substring (case-insensitive).
+    const lower = s.toLowerCase();
+    predicate = (r) =>
+      r.id === s ||
+      r.id.toLowerCase().includes(lower) ||
+      r.text.toLowerCase().includes(lower);
+  }
+
+  const kept = existing.filter((r) => !predicate(r));
+  const removed = existing.length - kept.length;
+  if (removed === 0) return { ok: true, removed: 0 };
+
+  const w = writeRaw(kept, opts);
+  if (!w.ok) return { ok: false, removed: 0, code: w.code, message: w.message };
+  return { ok: true, removed };
+}
+
+/**
+ * clearExemplars(opts?) -> { ok, removed }. One-shot wipe of the whole transient
+ * store. Returns the count removed. Fail-soft.
+ */
+export function clearExemplars(opts = {}) {
+  const existing = readRaw(opts);
+  const removed = existing.length;
+  if (removed === 0) {
+    // Nothing to clear; ensure no stale file lingers but don't error if absent.
+    const path = opts.path || exemplarStorePath(opts.env || process.env);
+    if (existsSync(path) && !isSymlink(path)) {
+      try { unlinkSync(path); } catch {}
+    }
+    return { ok: true, removed: 0 };
+  }
+  const w = writeRaw([], opts);
+  if (!w.ok) return { ok: false, removed: 0, code: w.code, message: w.message };
+  return { ok: true, removed };
+}