@jjh32456/dsh-longlive 1.6.7 → 1.8.0

package/src/memory/review.js

@@ -0,0 +1,124 @@
+// src/memory/review.js — M2-D：间隔重复（spaced repetition）调度
+//
+// 设计依据 §4.2/§4.5（review 调度 + promote 后可复习；不引第三方算法库，自研轻量版）：
+//   * 固定阶梯 1/3/7/15/30/60/120 天（成功升一档、失败回到 1 天并降 strength）；
+//   * dueAt = lastReviewedAt + intervalDays；dueRecords 只读；
+//   * recordReview 写 `.longlive/review/events.jsonl`（append-only）+ 1 行统一审计；
+//     不改原文/卡文件，复习结果由上层按需 promote（decay.js）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { appendAuditRecord } from './audit-records.js';
+import { ensureDir } from './state.js';
+
+export const REVIEW_SCHEMA = 'review/v1';
+export const REVIEW_INTERVALS_DAYS = Object.freeze([1, 3, 7, 15, 30, 60, 120]);
+export const REVIEW_PASS_GRADE = 3;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function iso(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+export function reviewStateOf(record = {}) {
+  const review = record.review && typeof record.review === 'object' ? record.review : {};
+  const streak = Number.isInteger(review.streak) && review.streak >= 0 ? review.streak : 0;
+  const intervalDays = Number.isInteger(review.intervalDays) && review.intervalDays > 0
+    ? review.intervalDays
+    : REVIEW_INTERVALS_DAYS[0];
+  return {
+    streak,
+    intervalDays,
+    lastGrade: Number.isInteger(review.lastGrade) ? review.lastGrade : null,
+    lastReviewedAt: typeof review.lastReviewedAt === 'string' ? review.lastReviewedAt : null,
+    dueAt: typeof review.dueAt === 'string' ? review.dueAt : null,
+  };
+}
+
+/** Pure scheduling: next review time for a record, from its current review state. */
+export function nextReviewAt(record = {}, now = new Date()) {
+  const state = reviewStateOf(record);
+  const base = state.lastReviewedAt ?? iso(now);
+  const time = Date.parse(base);
+  if (Number.isNaN(time)) return null;
+  const interval = REVIEW_INTERVALS_DAYS[Math.min(state.streak, REVIEW_INTERVALS_DAYS.length - 1)];
+  return new Date(time + interval * DAY_MS).toISOString();
+}
+
+export function isDue(record = {}, now = new Date()) {
+  const state = reviewStateOf(record);
+  if (state.dueAt === null) return true; // 未排期 => 到期（首次复习）
+  const due = Date.parse(state.dueAt);
+  return !Number.isNaN(due) && due <= now.getTime();
+}
+
+/** Due records, most overdue first (pure; skips superseded/archived). */
+export function dueRecords(records = [], now = new Date()) {
+  return records
+    .filter((record) => record && record.state !== 'superseded' && record.state !== 'archived')
+    .filter((record) => isDue(record, now))
+    .map((record) => ({ id: record.id ?? null, state: reviewStateOf(record), dueAt: reviewStateOf(record).dueAt }))
+    .sort((left, right) => String(left.dueAt ?? '').localeCompare(String(right.dueAt ?? '')));
+}
+
+/**
+ * Pure grade: 0..5 (0 完全遗忘 … 5 完美). Success (>=3) raises streak/interval and
+ * strength; failure resets the ladder and lowers strength. Never below 0.
+ */
+export function gradeReview(record = {}, grade, now = new Date()) {
+  const value = Math.max(0, Math.min(5, Number.isInteger(grade) ? grade : 0));
+  const state = reviewStateOf(record);
+  const success = value >= REVIEW_PASS_GRADE;
+  const streak = success ? state.streak + 1 : 0;
+  const intervalDays = REVIEW_INTERVALS_DAYS[Math.min(streak, REVIEW_INTERVALS_DAYS.length - 1)];
+  const lastReviewedAt = iso(now);
+  const dueAt = new Date(Date.parse(lastReviewedAt) + intervalDays * DAY_MS).toISOString();
+  const strength = Math.max(0, Math.min(9, (Number.isInteger(record?.strength) ? record.strength : 0) + (success ? 1 : -1)));
+  return {
+    grade: value,
+    success,
+    strength,
+    lastUsed: lastReviewedAt.slice(0, 10),
+    useCount: (Number.isInteger(record?.useCount) ? record.useCount : 0) + 1,
+    review: { streak, intervalDays, lastGrade: value, lastReviewedAt, dueAt },
+  };
+}
+
+/** Append one review event (append-only, never rewrites the source card/record). */
+export function recordReview({ root, record, grade, now = new Date(), by = 'admin' } = {}) {
+  const memoryRoot = String(root ?? '');
+  if (memoryRoot === '') throw new Error('E_MEMORY_ROOT: recordReview requires root');
+  const id = String(record?.id ?? record?.rel ?? 'unknown');
+  const result = gradeReview(record, grade, now);
+  const dir = path.join(path.resolve(memoryRoot), '.longlive', 'review');
+  ensureDir(memoryRoot, dir);
+  const file = path.join(dir, 'events.jsonl');
+  const row = {
+    schema: REVIEW_SCHEMA,
+    id,
+    at: iso(now),
+    by,
+    grade: result.grade,
+    success: result.success,
+    review: result.review,
+    strength: result.strength,
+    useCount: result.useCount,
+  };
+  fs.appendFileSync(file, `${JSON.stringify(row)}\n`, 'utf8');
+  try {
+    appendAuditRecord({
+      memoryRoot,
+      action: 'review',
+      recordId: id,
+      readerTier: 'host',
+      questionId: 'unknown',
+      expectedTurns: null,
+      answerText: null,
+      at: iso(now),
+      extra: { grade: result.grade, streak: result.review.streak, dueAt: result.review.dueAt },
+    });
+  } catch { /* audit best-effort */ }
+  return { ok: true, schema: REVIEW_SCHEMA, id, file, result };
+}

package/src/memory/trust.js

@@ -0,0 +1,88 @@
+// src/memory/trust.js — 1.8.0 / v2.8 §15.1-A3：trustScore（规则写死，时间可注入）
+//
+// 公式（写死）：
+//   w_tier = { user: 1.0, host: 0.9, agent: 0.6, plugin: 0.4 }
+//   trustScore = clamp(0, 1, w_tier * (1 + 0.1 * min(verifyCount, 5)) * decay)
+//   decay = 0.5 ^ (ageDays / 30)          （ageDays 由注入的 now/createdAt 计算，不用真实等待）
+//
+// 时间注入 API（GOV-04：禁止 sleep 造假）：
+//   - computeTrustScore({ sourceTier, verifyCount, ageDays })
+//   - trustScoreAt({ sourceTier, verifyCount, createdAt, now })
+//   - createGovTrustClock({ now })  → { at(createdAt), score(claim) }  测试显式传 now
+// 低信任阈值 < 0.35 的 claim 只能进候选区、不得作为结论注入。
+// legacy 迁移记录不做时间衰减（legacy:true → ageDays=0），避免把旧卡误判为低信任。
+
+export const TRUST_TIERS = Object.freeze(['user', 'host', 'agent', 'plugin']);
+export const TIER_WEIGHTS = Object.freeze({ user: 1.0, host: 0.9, agent: 0.6, plugin: 0.4 });
+export const VERIFY_COUNT_CAP = 5;
+export const LOW_TRUST_THRESHOLD = 0.35;
+export const TRUST_SCHEMA = 'trust/v1';
+
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+function toDateMs(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value !== '') {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+/** Pure formula (no clock): used directly by tests and by trustScoreAt. */
+export function computeTrustScore({ sourceTier = 'agent', verifyCount = 0, ageDays = 0 } = {}) {
+  const tier = TRUST_TIERS.includes(sourceTier) ? sourceTier : 'agent';
+  const weight = TIER_WEIGHTS[tier];
+  const verified = Math.max(0, Math.min(VERIFY_COUNT_CAP, Number.isInteger(verifyCount) ? verifyCount : 0));
+  const days = Number.isFinite(ageDays) && ageDays > 0 ? ageDays : 0;
+  const decay = Math.pow(0.5, days / 30);
+  const score = weight * (1 + 0.1 * verified) * decay;
+  return {
+    schema: TRUST_SCHEMA,
+    sourceTier: tier,
+    verifyCount: verified,
+    ageDays: days,
+    decay,
+    trustScore: clamp01(score),
+  };
+}
+
+/** Time-injected score: age is computed from createdAt → now (both injectable). */
+export function trustScoreAt({ sourceTier = 'agent', verifyCount = 0, createdAt = null, now = new Date(), legacy = false } = {}) {
+  const nowMs = toDateMs(now) ?? Date.now();
+  const createdMs = toDateMs(createdAt);
+  // A backwards clock must not inflate trust: negative age clamps to 0 (CLOCK_ROLLBACK-safe).
+  const rawAgeDays = createdMs === null ? 0 : (nowMs - createdMs) / (24 * 60 * 60 * 1000);
+  const ageDays = legacy === true ? 0 : (Number.isFinite(rawAgeDays) && rawAgeDays > 0 ? rawAgeDays : 0);
+  return computeTrustScore({ sourceTier, verifyCount, ageDays });
+}
+
+/** Time-injection seam for GOV-04 probes/tests (no sleep, no wall-clock dependency). */
+export function createGovTrustClock({ now } = {}) {
+  const clockNow = () => (typeof now === 'function' ? now() : now ?? new Date());
+  return {
+    at: (createdAt) => trustScoreAt({ sourceTier: 'host', verifyCount: 0, createdAt, now: clockNow() }),
+    score: ({ sourceTier, verifyCount = 0, createdAt = null, legacy = false } = {}) => trustScoreAt({ sourceTier, verifyCount, createdAt, now: clockNow(), legacy }),
+    now: clockNow,
+  };
+}
+
+export function isLowTrust(trustScore) {
+  return !(typeof trustScore === 'number' && trustScore >= LOW_TRUST_THRESHOLD);
+}
+
+/** 低信任不进结论注入；候选区仍可见（标 unverified）。 */
+export function injectionEligibility(claim = {}) {
+  const score = typeof claim.trustScore === 'number' ? claim.trustScore : 0;
+  return {
+    eligible: !isLowTrust(score),
+    unverified: isLowTrust(score),
+    trustScore: score,
+  };
+}

package/src/memory/version-chain.js

@@ -0,0 +1,264 @@
+// src/memory/version-chain.js — M2-D：蒸馏版本链 / active 指针 / 回滚 / 审计
+//
+// 设计依据 MEMORY-RECALL-V2-PROPOSAL §4.3/§4.4：
+//   * 每个蒸馏 id 一个 append-only JSONL（`.longlive/distill/<topic>-<period>.jsonl`），
+//     一行一个版本，旧版本永久保留、绝不覆盖/删除；
+//   * `.longlive/distill/index.json` 只存 activeVersion 指针，回滚=切指针（ms 级）；
+//   * 每次 append / rollback 写 1 行 `.longlive/distill.log`（JSON，可审计）+
+//     1 行 `.longlive/audit/records.jsonl`（统一审计，A5 口径）；
+//   * 本模块只做“链/指针/审计”原语，不做抽取、不做保护判定（见 distill.js / l2-gate.js）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { appendAuditRecord } from './audit-records.js';
+import { memoryError } from './paths.js';
+import { appendAudit, ensureDir, sha256Text, writeFileAtomic } from './state.js';
+
+export const VERSION_CHAIN_SCHEMA = 'version-chain/v1';
+export const DISTILL_DIR = '.longlive/distill';
+export const DISTILL_INDEX_FILE = '.longlive/distill/index.json';
+export const DISTILL_LOG_FILE = '.longlive/distill.log';
+export const DISTILL_INDEX_SCHEMA = 'distill-index/v1';
+
+export function distillDirOf(root) {
+  return path.join(path.resolve(String(root)), DISTILL_DIR);
+}
+
+export function chainIndexPathOf(root) {
+  return path.join(path.resolve(String(root)), DISTILL_INDEX_FILE);
+}
+
+export function chainLogPathOf(root) {
+  return path.join(path.resolve(String(root)), DISTILL_LOG_FILE);
+}
+
+/** File name for one chain: only [A-Za-z0-9._-] survives (path traversal impossible). */
+export function chainFileName({ topic, period }) {
+  const slug = (value) => String(value ?? 'unknown')
+    .normalize('NFKC')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'unknown';
+  return `${slug(topic)}-${slug(period)}.jsonl`;
+}
+
+export function chainFilePathOf(root, id, file = null) {
+  const name = typeof file === 'string' && file !== '' ? file : chainFileName({ topic: id, period: 'chain' });
+  return path.join(distillDirOf(root), path.basename(name));
+}
+
+/** Deterministic JSON: object keys sorted recursively (idempotency hashes). */
+export function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}
+
+export function contentHashOf(value) {
+  return sha256Text(stableStringify(value));
+}
+
+export function isEmptyIndex() {
+  return { schema: DISTILL_INDEX_SCHEMA, version: 1, entries: {} };
+}
+
+/** Read the active-pointer index; missing file => empty index, corrupt file => refuse (fail-safe). */
+export function readChainIndex(root) {
+  const file = chainIndexPathOf(root);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { ...isEmptyIndex(), file };
+    throw memoryError('E_CHAIN_INDEX_READ', `读不到 ${file}`, error);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw memoryError('E_CHAIN_INDEX_CORRUPT', `版本索引损坏（拒绝覆盖，先人工核对）：${file}`, error);
+  }
+  const entries = parsed && typeof parsed === 'object' && parsed.entries && typeof parsed.entries === 'object'
+    ? parsed.entries
+    : {};
+  return { schema: parsed?.schema ?? DISTILL_INDEX_SCHEMA, version: parsed?.version ?? 1, entries, file };
+}
+
+export function readIndexEntry(root, id) {
+  const index = readChainIndex(root);
+  const entry = index.entries[String(id)];
+  if (!entry || typeof entry !== 'object') return null;
+  return {
+    id: String(id),
+    file: typeof entry.file === 'string' ? entry.file : null,
+    activeVersion: Number.isInteger(entry.activeVersion) ? entry.activeVersion : null,
+    versionCount: Number.isInteger(entry.versionCount) ? entry.versionCount : null,
+    contentHash: typeof entry.contentHash === 'string' ? entry.contentHash : null,
+    updatedAt: typeof entry.updatedAt === 'string' ? entry.updatedAt : null,
+  };
+}
+
+export function listChains(root) {
+  const index = readChainIndex(root);
+  return Object.keys(index.entries).sort().map((id) => ({
+    id,
+    ...readIndexEntry(root, id),
+  }));
+}
+
+/** Parse one chain file into versions (append-only order). Corrupt line => refuse. */
+export function readVersions(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw memoryError('E_CHAIN_READ', `读不到版本链：${file}`, error);
+  }
+  const versions = [];
+  raw.split(/\r?\n/).forEach((line, index) => {
+    if (line.trim() === '') return;
+    try {
+      const row = JSON.parse(line);
+      if (!row || typeof row !== 'object' || !Number.isInteger(row.version)) {
+        throw new Error('version is not an integer');
+      }
+      versions.push(row);
+    } catch (error) {
+      throw memoryError('E_CHAIN_CORRUPT', `版本链第 ${index + 1} 行损坏：${file}`, error);
+    }
+  });
+  return versions;
+}
+
+/** Append one version line (fsync; never rewrites existing bytes). */
+export function appendVersionLine({ file, record }) {
+  if (!record || !Number.isInteger(record.version) || record.version < 1) {
+    throw memoryError('E_CHAIN_VERSION', 'appendVersionLine requires record.version >= 1');
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const fd = fs.openSync(file, 'a');
+  try {
+    fs.writeSync(fd, `${JSON.stringify(record)}\n`, null, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return { file, version: record.version, line: JSON.stringify(record) };
+}
+
+/** Atomically set the active version pointer for one chain. */
+export function setActiveVersion({ root, id, file, version, versionCount, contentHash = null, now = new Date() }) {
+  const index = readChainIndex(root);
+  index.entries[String(id)] = {
+    file: path.basename(String(file)),
+    activeVersion: version,
+    versionCount,
+    contentHash,
+    updatedAt: now.toISOString(),
+  };
+  const next = { schema: DISTILL_INDEX_SCHEMA, version: 1, entries: index.entries, updatedAt: now.toISOString() };
+  writeFileAtomic(root, chainIndexPathOf(root), `${JSON.stringify(next, null, 2)}\n`, { backup: false, now });
+  return { file: chainIndexPathOf(root), entry: index.entries[String(id)] };
+}
+
+/** Append one structured audit line to `.longlive/distill.log` (JSONL). */
+export function appendChainLog({ root, op, id = null, file = null, fromVersion = null, toVersion = null, by = 'admin', reason = '', contentHash = null, now = new Date() }) {
+  const row = {
+    schema: 'distill-log/v1',
+    at: now.toISOString(),
+    op,
+    id,
+    file: file === null ? null : path.basename(String(file)),
+    fromVersion,
+    toVersion,
+    by,
+    reason,
+    contentHash,
+  };
+  const target = chainLogPathOf(root);
+  ensureDir(root, path.dirname(target));
+  fs.appendFileSync(target, `${JSON.stringify(row)}\n`, 'utf8');
+  return { file: target, row };
+}
+
+function appendUnifiedAudit({ root, action, recordId, extra, now }) {
+  try {
+    appendAuditRecord({
+      memoryRoot: root,
+      action,
+      recordId,
+      readerTier: 'host',
+      questionId: 'unknown',
+      expectedTurns: null,
+      answerText: null,
+      at: now.toISOString(),
+      extra,
+    });
+  } catch {
+    /* 统一审计是 best-effort：链日志已写，不能让审计写失败吞掉回滚结果 */
+  }
+}
+
+/**
+ * Roll one chain back to a concrete version: only the active pointer moves;
+ * every version row stays on disk. Writes 1 distill.log row + 1 unified audit row.
+ */
+export function rollbackVersion({ root, id, toVersion, by = 'admin', reason = '', now = new Date() }) {
+  const entry = readIndexEntry(root, id);
+  if (!entry || !entry.file || entry.activeVersion === null) {
+    throw memoryError('E_CHAIN_NOT_FOUND', `没有这个蒸馏 id（或尚未建链）：${id}`);
+  }
+  const file = chainFilePathOf(root, id, entry.file);
+  const versions = readVersions(file);
+  const target = versions.find((row) => row.version === toVersion);
+  if (!target) {
+    throw memoryError('E_CHAIN_NO_VERSION', `链 ${id} 没有 v${toVersion}（现有 v${versions[0]?.version}..v${versions.at(-1)?.version}）`);
+  }
+  if (entry.activeVersion === toVersion) {
+    return { ok: true, changed: false, id, file, fromVersion: entry.activeVersion, toVersion, versions: versions.length };
+  }
+  const fromVersion = entry.activeVersion;
+  setActiveVersion({
+    root,
+    id,
+    file,
+    version: toVersion,
+    versionCount: versions.length,
+    contentHash: target.contentHash ?? null,
+    now,
+  });
+  appendChainLog({ root, op: 'rollback', id, file, fromVersion, toVersion, by, reason, contentHash: target.contentHash ?? null, now });
+  appendAudit(root, { action: 'memory_distill_rollback', object: `${id}@v${fromVersion}->v${toVersion}`, result: `by=${by} reason=${reason || '-'}`, now });
+  appendUnifiedAudit({
+    root,
+    action: 'distill_rollback',
+    recordId: id,
+    extra: { fromVersion, toVersion, by, reason, file: path.basename(file) },
+    now,
+  });
+  return { ok: true, changed: true, id, file, fromVersion, toVersion, versions: versions.length };
+}
+
+/** Field-level diff between two version rows (audit/createdAt excluded). */
+export function diffVersions(from, to) {
+  const changed = [];
+  const keys = new Set([...Object.keys(from ?? {}), ...Object.keys(to ?? {})]);
+  for (const key of [...keys].sort()) {
+    if (key === 'audit' || key === 'contentHash') continue;
+    const left = stableStringify(from?.[key] ?? null);
+    const right = stableStringify(to?.[key] ?? null);
+    if (left !== right) changed.push({ field: key, from: from?.[key] ?? null, to: to?.[key] ?? null });
+  }
+  return {
+    changed,
+    fromVersion: from?.version ?? null,
+    toVersion: to?.version ?? null,
+    fromGist: from?.gist ?? null,
+    toGist: to?.gist ?? null,
+  };
+}

package/src/memory/wal.js

@@ -0,0 +1,137 @@
+// src/memory/wal.js — M2-B / §2.3：索引写入的 WAL（崩溃安全 + 可重放）
+//
+// 写路径：先 append 一条 pending intent → 执行真正的写入（DB 事务）→ append done。
+// 进程中途崩溃时，下次启动 `replay()` 把 pending 条目重新执行（写入本身幂等），
+// 所以不会出现「半行索引」。`compact()` 只保留未完成条目，控制文件体积。
+//
+// 文件：<memoryRoot>/.longlive/index/wal.jsonl
+// 行：{schema:'wal/v1', walId, op, at, status:'pending'|'done'|'failed', payload, error?}
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { stableStringify } from '../codec.js';
+
+export const WAL_SCHEMA = 'wal/v1';
+export const WAL_MAX_BYTES = 2 * 1024 * 1024;
+
+export function walPathOf(memoryRoot) {
+  return path.join(path.resolve(String(memoryRoot)), '.longlive', 'index', 'wal.jsonl');
+}
+
+export function walIdOf(entry) {
+  return crypto.createHash('sha1').update(stableStringify(entry)).digest('hex').slice(0, 16);
+}
+
+function nowMs(now) {
+  const value = typeof now === 'function' ? now() : new Date();
+  return value instanceof Date ? value.getTime() : Number(value);
+}
+
+export function createWal(options = {}) {
+  const memoryRoot = path.resolve(String(options.memoryRoot ?? ''));
+  const file = options.walPath ? path.resolve(options.walPath) : walPathOf(memoryRoot);
+  const now = options.now;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  function append(line) {
+    fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+    return line;
+  }
+
+  /** Record an intent; returns the walId used to mark completion. */
+  function begin(op, payload, extra = {}) {
+    const entry = { op, payload };
+    const walId = options.walId?.(entry) ?? walIdOf(entry);
+    append({ schema: WAL_SCHEMA, walId, op, at: nowMs(now), status: 'pending', payload, ...extra });
+    return walId;
+  }
+
+  function markDone(walId, extra = {}) {
+    append({ schema: WAL_SCHEMA, walId, at: nowMs(now), status: 'done', ...extra });
+    return { ok: true, walId };
+  }
+
+  function markFailed(walId, error, extra = {}) {
+    append({ schema: WAL_SCHEMA, walId, at: nowMs(now), status: 'failed', error: String(error ?? 'unknown'), ...extra });
+    return { ok: true, walId };
+  }
+
+  /** Fold the log: last status wins. */
+  function fold() {
+    const entries = new Map();
+    let text = '';
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch {
+      return entries;
+    }
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue;
+      let row = null;
+      try {
+        row = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (typeof row?.walId !== 'string') continue;
+      const previous = entries.get(row.walId) ?? {};
+      entries.set(row.walId, { ...previous, ...row, status: row.status ?? previous.status ?? 'pending' });
+    }
+    return entries;
+  }
+
+  function pending() {
+    return [...fold().values()].filter((entry) => entry.status === 'pending');
+  }
+
+  function all() {
+    return [...fold().values()];
+  }
+
+  function failed() {
+    return [...fold().values()].filter((entry) => entry.status === 'failed');
+  }
+
+  /**
+   * Replay every pending intent through `handler(entry)`. Handler must be idempotent.
+   * Returns {ok, replayed, failed}.
+   */
+  function replay(handler) {
+    if (typeof handler !== 'function') throw new Error('wal.replay requires handler(entry)');
+    const results = { ok: true, replayed: 0, failed: 0, errors: [] };
+    for (const entry of pending()) {
+      try {
+        handler(entry);
+        markDone(entry.walId, { replayed: true });
+        results.replayed += 1;
+      } catch (error) {
+        markFailed(entry.walId, error?.message ?? error);
+        results.failed += 1;
+        results.errors.push({ walId: entry.walId, op: entry.op, message: String(error?.message ?? error) });
+      }
+    }
+    results.ok = results.failed === 0;
+    return results;
+  }
+
+  /** Rewrite only pending lines (atomic tmp→rename); completed/failed rows dropped. */
+  function compact() {
+    const keep = pending();
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, keep.map((entry) => JSON.stringify(entry)).join('\n') + (keep.length > 0 ? '\n' : ''), 'utf8');
+    fs.renameSync(tmp, file);
+    return { ok: true, kept: keep.length };
+  }
+
+  function size() {
+    try {
+      return fs.statSync(file).size;
+    } catch {
+      return 0;
+    }
+  }
+
+  return { file, begin, markDone, markFailed, pending, failed, all, replay, compact, size, fold };
+}