rovecode 0.4.0-beta.2 → 0.4.0

package/src/skills/index.ts

@@ -0,0 +1,306 @@
+/** Skills module (hermes pattern): SKILL.md files with frontmatter index,
+ *  mtime+size manifest invalidation, usage sidecars, deterministic staleness.
+ *  No LLM consolidation — lifecycle is a pure function of usage age. */
+
+import {
+  existsSync, readFileSync, readdirSync, renameSync, statSync, utimesSync, writeFileSync,
+} from "node:fs";
+import { rovecodeHome } from "../providers/auth.ts";
+import { join, resolve } from "node:path";
+
+export const SKILL_FILE = "SKILL.md";
+export const MAX_DESCRIPTION_CHARS = 60;
+export const STALE_AFTER_MS = 1000 * 60 * 60 * 24 * 90; // 90 days
+
+export type SkillScope = "project" | "global";
+
+export interface Skill {
+  name: string;
+  /** one line for the system-prompt index: clipped to MAX_DESCRIPTION_CHARS on a word boundary */
+  description: string;
+  /** the description as written, however long — what `skill_view` and the market show */
+  fullDescription: string;
+  version: string;
+  /** absolute path of the SKILL.md */
+  path: string;
+  /** content after the frontmatter block */
+  body: string;
+  scope: SkillScope;
+  mtimeMs: number;
+  size: number;
+}
+
+export interface InvalidSkill { path: string; reason: string }
+
+export interface SkillUsage {
+  viewCount: number;
+  lastViewedAt: number;
+}
+
+export interface ScanChanges {
+  added: string[];
+  removed: string[];
+  changed: string[];
+}
+
+const IGNORED_DIRS: Record<string, true> = { node_modules: true, ".git": true };
+export interface ScanResult {
+  skills: Skill[];
+  invalid: InvalidSkill[];
+  changes: ScanChanges;
+}
+
+export interface SkillStoreOptions {
+  /** project skills dir (default: <cwd>/.rovecode/skills) */
+  projectDir?: string;
+  /** global skills dir; null disables (default: ~/.rovecode/skills) */
+  globalDir?: string | null;
+  /** max directory depth when walking for SKILL.md (default 3) */
+  maxDepth?: number;
+  /** more roots — a plugin's skills folder (src/plugins) — walked like the two above, tagged with the
+   *  scope the plugin itself has (a project plugin's skills win a name clash as the project's own would) */
+  extraDirs?: readonly { dir: string; scope: SkillScope }[];
+}
+
+// ---------- Frontmatter ----------
+
+/** Split `---\nkey: value` frontmatter from body. Returns null when no block.
+ *
+ *  Values may be a plain scalar, or a YAML block scalar — `key: >` / `|` / `>-` / `|-` followed by
+ *  more-indented lines, which real SKILL.md files use for anything longer than a phrase. Measured on
+ *  anthropics/skills (2026-09-05): 3 of 19 skills write their description that way, and reading only
+ *  the header line gave `description: ">"` — not an error, just a skill whose one-line summary is a
+ *  punctuation mark, with its continuation lines mistaken for keys of their own. That is worse than
+ *  rejecting it, because nothing says anything went wrong. Folded (`>`) joins its lines with a space,
+ *  literal (`|`) keeps the newlines, a trailing `-` strips the final newline. The rest of YAML —
+ *  anchors, nested maps, lists — is still out of scope: this is a frontmatter reader, not a parser. */
+export function parseFrontmatter(text: string): { fm: Record<string, string>; body: string } | null {
+  if (!text.startsWith("---")) return null;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return null;
+  const closeEnd = end + 1 + text.slice(end + 1).indexOf("\n") + 1; // past the closing `---` line
+  const block = text.slice(4, end); // skip leading `---\n`
+  const body = text.slice(closeEnd).replace(/^\r?\n/, "");
+  const fm: Record<string, string> = {};
+  const lines = block.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] as string;
+    if (/^\s/.test(line)) continue;                 // an orphan continuation is not a key of its own
+    const c = line.indexOf(":");
+    if (c === -1) continue;
+    const k = line.slice(0, c).trim();
+    if (!k) continue;
+    const rest = line.slice(c + 1).trim();
+    const m = /^([|>])([+-]?)$/.exec(rest);
+    if (m === null) { fm[k] = rest.replace(/^["']|["']$/g, ""); continue; }
+    const folded = m[1] === ">";
+    const owned: string[] = [];
+    while (i + 1 < lines.length) {
+      const next = lines[i + 1] as string;
+      if (next.trim() !== "" && !/^\s/.test(next)) break;   // back to column 0: the block ended
+      owned.push(next.replace(/^\s+/, ""));
+      i++;
+    }
+    while (owned.length > 0 && owned[owned.length - 1] === "") owned.pop();
+    fm[k] = folded ? owned.join(" ").replace(/\s+/g, " ").trim() : owned.join("\n");
+  }
+  return { fm, body };
+}
+
+/** Clip to the index budget on a word boundary, with an ellipsis so a reader can tell it was cut. */
+export function clipDescription(text: string): string {
+  const one = text.replace(/\s+/g, " ").trim();
+  if (one.length <= MAX_DESCRIPTION_CHARS) return one;
+  const cut = one.slice(0, MAX_DESCRIPTION_CHARS - 1);
+  const sp = cut.lastIndexOf(" ");
+  return `${(sp > MAX_DESCRIPTION_CHARS / 2 ? cut.slice(0, sp) : cut).replace(/[,;:.]$/, "")}…`;
+}
+
+function parseSkillFile(path: string, scope: SkillScope): { skill: Skill } | { invalid: InvalidSkill } {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    return { invalid: { path, reason: `unreadable: ${(e as Error).message}` } };
+  }
+  const parsed = parseFrontmatter(text);
+  if (!parsed) return { invalid: { path, reason: "missing frontmatter block" } };
+  const name = parsed.fm["name"] ?? "";
+  const description = parsed.fm["description"] ?? "";
+  if (!name) return { invalid: { path, reason: "frontmatter missing name" } };
+  if (!description) return { invalid: { path, reason: "frontmatter missing description" } };
+  // A long description is CLIPPED for the index, never a reason to reject the skill. The cap exists to
+  // protect the system prompt (50 skills x a 950-char description is 47 KB of prefix), and clipping
+  // protects it just as well while a hard reject throws away a working skill for being wordy. Measured
+  // on anthropics/skills (2026-09-05): 16 of 19 real skills are over the cap, median 319 chars, longest
+  // 950 — the whole public corpus would have been unusable. The two other places rovecode reads a
+  // description already clip (plugins/manifest.ts, tui/commands.ts); this was the outlier.
+  const st = statSync(path);
+  return {
+    skill: {
+      name,
+      description: clipDescription(description),
+      fullDescription: description,
+      version: parsed.fm["version"] ?? "0.0.0",
+      path, body: parsed.body, scope,
+      mtimeMs: st.mtimeMs, size: st.size,
+    },
+  };
+}
+
+// ---------- Usage sidecar ----------
+
+export function usagePath(skillFile: string): string {
+  return skillFile + ".usage.json";
+}
+
+export function readUsage(skillFile: string): SkillUsage | undefined {
+  const p = usagePath(skillFile);
+  if (!existsSync(p)) return undefined;
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf8")) as Partial<SkillUsage>;
+    return {
+      viewCount: typeof raw.viewCount === "number" ? raw.viewCount : 0,
+      lastViewedAt: typeof raw.lastViewedAt === "number" ? raw.lastViewedAt : 0,
+    };
+  } catch {
+    return undefined; // corrupt sidecar → treat as never used
+  }
+}
+
+/** Atomic write: temp file + rename, so a concurrent reader never sees a partial sidecar. */
+export function writeUsageAtomic(skillFile: string, usage: SkillUsage): void {
+  const p = usagePath(skillFile);
+  const tmp = p + ".tmp";
+  writeFileSync(tmp, JSON.stringify(usage, null, 2));
+  renameSync(tmp, p);
+}
+
+// ---------- Lifecycle ----------
+
+/** Deterministic: stale when last view (or, never viewed, file mtime) is older than 90d. */
+export function skillLifecycle(
+  skill: Pick<Skill, "mtimeMs">,
+  usage: SkillUsage | undefined,
+  now: number,
+): "active" | "stale" {
+  const lastActivity = usage && usage.viewCount > 0 ? usage.lastViewedAt : skill.mtimeMs;
+  return now - lastActivity > STALE_AFTER_MS ? "stale" : "active";
+}
+
+// ---------- Store ----------
+
+export class SkillStore {
+  private readonly projectDir: string;
+  private readonly globalDir: string | null;
+  private readonly maxDepth: number;
+  /** path → parsed skill (cache valid while manifest matches) */
+  private cache = new Map<string, Skill>();
+  /** path → `mtimeMs:size` (hermes manifest invalidation) */
+  private manifest = new Map<string, string>();
+
+  constructor(readonly cwd: string, opts: SkillStoreOptions = {}) {
+    this.projectDir = resolve(cwd, opts.projectDir ?? join(".rovecode", "skills"));
+    this.globalDir = opts.globalDir === null
+      ? null
+      // rovecodeHome(), not homedir(): ROVECODE_HOME is how every other part of rovecode finds its
+      // config — hooks, settings, plugins, credentials — and skills were the one that ignored it. So a
+      // user who set it read skills from a directory nothing else used, and every test that isolates
+      // itself with a scratch home silently indexed the DEVELOPER's real skills instead. That is how
+      // this was found: installing one skill into a real home broke a plugin test that never touches
+      // skills, and the failure named a skill the test had never heard of.
+      : resolve(opts.globalDir ?? join(rovecodeHome(), "skills"));
+    this.maxDepth = opts.maxDepth ?? 3;
+    this.extraDirs = (opts.extraDirs ?? []).map(({ dir, scope }) => [resolve(cwd, dir), scope]);
+  }
+  private readonly extraDirs: Array<[string, SkillScope]>;
+
+  private dirs(): Array<[string, SkillScope]> {
+    const d: Array<[string, SkillScope]> = [[this.projectDir, "project"]];
+    if (this.globalDir && existsSync(this.globalDir)) d.push([this.globalDir, "global"]);
+    for (const [dir, scope] of this.extraDirs) if (existsSync(dir)) d.push([dir, scope]);
+    return d;
+  }
+
+  private find(root: string, dir: string = root, depth: number = 0): string[] {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const found: string[] = [];
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isFile() && e.name === SKILL_FILE) found.push(p);
+      else if (e.isDirectory() && depth < this.maxDepth && !IGNORED_DIRS[e.name]) {
+        found.push(...this.find(root, p, depth + 1));
+      }
+    }
+    return found;
+  }
+
+  /** Rescan: stat every SKILL.md, diff the manifest, reparse only added/changed files. */
+  scan(): ScanResult {
+    const next = new Map<string, string>();
+    const scopeOf = new Map<string, SkillScope>(); // by root, not by path prefix: a plugin's project skills live outside <cwd>/.rovecode/skills
+    for (const [dir, scope] of this.dirs()) {
+      for (const p of this.find(dir)) {
+        try {
+          const st = statSync(p);
+          next.set(p, `${st.mtimeMs}:${st.size}`);
+          if (!scopeOf.has(p)) scopeOf.set(p, scope);
+        } catch { /* vanished between readdir and stat */ }
+      }
+    }
+    const changes: ScanChanges = { added: [], removed: [], changed: [] };
+    for (const [p, sig] of next) {
+      if (!this.manifest.has(p)) changes.added.push(p);
+      else if (this.manifest.get(p) !== sig) changes.changed.push(p);
+    }
+    for (const p of this.manifest.keys()) if (!next.has(p)) changes.removed.push(p);
+
+    const invalid: InvalidSkill[] = [];
+    for (const p of [...changes.added, ...changes.changed]) {
+      const scope = scopeOf.get(p) ?? (p.startsWith(this.projectDir) ? "project" : "global");
+      const r = parseSkillFile(p, scope);
+      if ("skill" in r) this.cache.set(p, r.skill);
+      else { this.cache.delete(p); invalid.push(r.invalid); }
+    }
+    for (const p of changes.removed) this.cache.delete(p);
+    this.manifest = next;
+    return { skills: this.list(), invalid, changes };
+  }
+
+  /** Project scope wins on name collisions with the global dir. */
+  list(): Skill[] {
+    const byName = new Map<string, Skill>();
+    for (const s of this.cache.values()) {
+      const prev = byName.get(s.name);
+      if (!prev || (prev.scope === "global" && s.scope === "project")) byName.set(s.name, s);
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  get(name: string): Skill | undefined {
+    return this.list().find((s) => s.name === name);
+  }
+
+  usage(name: string): SkillUsage | undefined {
+    const s = this.get(name);
+    return s ? readUsage(s.path) : undefined;
+  }
+
+  /** Record one view. Returns the updated sidecar contents. */
+  bumpUsage(skill: Skill, now: number = Date.now()): SkillUsage {
+    const prev = readUsage(skill.path);
+    const usage: SkillUsage = { viewCount: (prev?.viewCount ?? 0) + 1, lastViewedAt: now };
+    writeUsageAtomic(skill.path, usage);
+    return usage;
+  }
+}
+
+/** Touch a skill file's mtime (same size) so manifest invalidation is observable in tests. */
+export function touchSkillFile(path: string, at: Date = new Date()): void {
+  utimesSync(path, at, at);
+}

package/src/skills/tools.ts

@@ -0,0 +1,69 @@
+/** Skill tools (hermes pattern): `skill_view` returns a body and bumps the
+ *  usage sidecar; `skills_list` returns the index. Above 50 skills the index
+ *  is too big for the system prompt, so `skills_list` is the only access path
+ *  and `buildSkillsIndex` returns "" (prompt_builder.py:2083 reject rule). */
+
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+import { SkillStore, skillLifecycle, type Skill, type SkillUsage } from "./index.ts";
+
+export const INDEX_PROMPT_LIMIT = 50; // hermes: >50 skills → skills_list tool only
+
+function renderIndexLine(s: Skill, usage: SkillUsage | undefined, now: number): string {
+  const state = skillLifecycle(s, usage, now);
+  return `- ${s.name}${s.version ? ` (v${s.version})` : ""}: ${s.description}${state === "stale" ? " [stale]" : ""}`;
+}
+
+/** System-prompt index. Empty string when the catalogue outgrows the prompt. */
+export function buildSkillsIndex(store: SkillStore, now: number = Date.now()): string {
+  const skills = store.list();
+  if (skills.length === 0 || skills.length > INDEX_PROMPT_LIMIT) return "";
+  return skills.map((s) => renderIndexLine(s, store.usage(s.name), now)).join("\n");
+}
+
+export function createSkillTools(store: SkillStore): Tool[] {
+  const skillView: Tool = {
+    schema: {
+      name: "skill_view",
+      description:
+        "Read one skill's full instructions. Use when a skill in the index matches the task.",
+      args: {
+        type: "object",
+        properties: { name: { type: "string", description: "skill name from the index" } },
+        required: ["name"],
+      },
+    },
+    kind: "read",
+    sequential: true, // sidecar write
+    execute(args): Promise<ToolOutput> {
+      const raw = args as { name?: unknown };
+      const name = typeof raw.name === "string" ? raw.name : "";
+      const skill = store.get(name);
+      if (!skill) return Promise.resolve({ ok: false, output: `no skill named '${name}'` });
+      const usage = store.bumpUsage(skill);
+      // the FULL description, not the index's clipped line: the model opened this skill to read it, so
+      // the sentence saying when to use it belongs here in one piece
+      const header = `# ${skill.name} (v${skill.version})\n\n${skill.fullDescription}\n\n`;
+      return Promise.resolve({ ok: true, output: header + skill.body, data: usage });
+    },
+  };
+
+  const skillsList: Tool = {
+    schema: {
+      name: "skills_list",
+      description:
+        "List available skills (name, version, description, staleness). Use to discover skills when the system prompt has no skill index.",
+      args: { type: "object", properties: {} },
+    },
+    kind: "read",
+    execute(_args: unknown, _ctx: ToolContext): Promise<ToolOutput> {
+      store.scan(); // fresh catalogue even when the caller forgot to rescan
+      const skills = store.list();
+      if (skills.length === 0) return Promise.resolve({ ok: true, output: "no skills installed" });
+      const now = Date.now();
+      const lines = skills.map((s) => renderIndexLine(s, store.usage(s.name), now));
+      return Promise.resolve({ ok: true, output: lines.join("\n"), data: { count: skills.length } });
+    },
+  };
+
+  return [skillView, skillsList];
+}

package/src/skills/versioned.ts

@@ -0,0 +1,227 @@
+/** Versioned edit ledger for skill/memory files (PORT #16, prime-agent MIT).
+ *
+ *  Port of the refinement/versioned-state machinery in prime-agent
+ *  packages/coding-agent/src/core/refinement/refinement.ts:
+ *    - per-edit before/after snapshots + version bump  (AppliedRefinementEdit:85,
+ *      `version = before ? before.version + 1 : 1`:770, record push:788)
+ *    - optimistic-concurrency baseline check → typed reject, no write  (735-749)
+ *    - rollback built from recorded before/after, itself a new history entry
+ *      (rollbackProposal:813-845, rollbackOf:100)
+ *    - append-only JSONL history beside the store; malformed lines skipped so a
+ *      bad append can never break rollback  (refinements.jsonl:25, 374-400)
+ *
+ *  Deliberately NOT ported (BLUEPRINT §5 + prime's reward-hacking findings):
+ *  no auto-refinement loop (prime's reviewAutoRefine LLM gate stays out), no
+ *  LLM proposal pass, and no grader/eval surface anywhere in this API
+ *  (ouroboros rule: graders stay hidden from agent-facing code). Edits happen
+ *  only when a human or an explicit tool call invokes commit()/rollback().
+ *
+ *  Storage: sidecar JSONL beside the target file — `<target>.versions.jsonl`
+ *  (mirrors the house `SKILL.md.usage.json` sidecar). One line per edit:
+ *  {version, baseVersion, before, after, reason, timestamp, rollbackTo?}.
+ *  Every record carries FULL before/after content, so record v restores both
+ *  content@v (`after`) and content@v-1 (`before`). With the newest K records
+ *  retained, rollback covers versions [oldest.baseVersion .. newest.version].
+ *  History is bounded: past `maxEdits` records the oldest are evicted, and
+ *  versions older than the window become unreachable (typed reject).
+ *  Versions are monotonic and never reused after eviction. */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const LEDGER_SUFFIX = ".versions.jsonl";
+export const DEFAULT_MAX_EDITS = 20;
+
+export interface VersionedEdit {
+  /** version this edit produced (monotonic; = baseVersion + 1) */
+  version: number;
+  /** version the editor read before making the change */
+  baseVersion: number;
+  /** full target content before the edit (content at baseVersion) */
+  before: string;
+  /** full target content after the edit (content at version) */
+  after: string;
+  reason: string;
+  /** ms epoch */
+  timestamp: number;
+  /** set when this edit was produced by rollback(): the restored version */
+  rollbackTo?: number;
+}
+
+/** Inclusive range of versions rollback can currently restore. */
+export interface VersionRange { from: number; to: number }
+
+export type CommitResult =
+  | { ok: true; edit: VersionedEdit }
+  | { ok: false; code: "version-conflict"; baseVersion: number; currentVersion: number; message: string };
+
+export type RollbackResult =
+  | { ok: true; edit: VersionedEdit }
+  | { ok: false; code: "unknown-version"; requested: number; available: VersionRange | null; message: string };
+
+// ---------- internals ----------
+
+/** Atomic write (house pattern, skills/index.ts writeUsageAtomic): tmp + rename. */
+function atomicWrite(path: string, text: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, path);
+}
+
+/** Parse one JSONL line into an edit, or null when malformed (prime: skip, never throw). */
+function parseEdit(line: string): VersionedEdit | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+  if (
+    typeof r["version"] !== "number" || typeof r["baseVersion"] !== "number" ||
+    typeof r["before"] !== "string" || typeof r["after"] !== "string" ||
+    typeof r["reason"] !== "string" || typeof r["timestamp"] !== "number"
+  ) return null;
+  const edit: VersionedEdit = {
+    version: r["version"], baseVersion: r["baseVersion"],
+    before: r["before"], after: r["after"],
+    reason: r["reason"], timestamp: r["timestamp"],
+  };
+  if (typeof r["rollbackTo"] === "number") edit.rollbackTo = r["rollbackTo"];
+  return edit;
+}
+
+// ---------- ledger ----------
+
+export interface VersionLedgerOptions {
+  /** sidecar path (default: `<target>${LEDGER_SUFFIX}`) */
+  ledgerPath?: string;
+  /** bounded snapshot count; oldest records evicted past this (default 20, min 1) */
+  maxEdits?: number;
+}
+
+export class VersionLedger {
+  readonly ledgerPath: string;
+  private readonly maxEdits: number;
+
+  constructor(readonly targetPath: string, opts: VersionLedgerOptions = {}) {
+    this.ledgerPath = opts.ledgerPath ?? targetPath + LEDGER_SUFFIX;
+    this.maxEdits = Math.max(1, opts.maxEdits ?? DEFAULT_MAX_EDITS);
+  }
+
+  /** Retained edits, oldest → newest. Malformed lines are skipped; duplicate
+   *  versions keep the last occurrence (append order wins). */
+  history(): VersionedEdit[] {
+    if (!existsSync(this.ledgerPath)) return [];
+    const byVersion = new Map<number, VersionedEdit>();
+    for (const line of readFileSync(this.ledgerPath, "utf8").split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const edit = parseEdit(trimmed);
+      if (edit) byVersion.set(edit.version, edit);
+    }
+    return [...byVersion.values()].sort((a, b) => a.version - b.version);
+  }
+
+  /** Current version: 0 until the first recorded edit; unaffected by eviction. */
+  version(): number {
+    return this.history().at(-1)?.version ?? 0;
+  }
+
+  /** Current on-disk content of the target ("" when the file does not exist). */
+  read(): string {
+    return existsSync(this.targetPath) ? readFileSync(this.targetPath, "utf8") : "";
+  }
+
+  /** Versions rollback can restore right now, or null before the first edit.
+   *  Derived from the CONTIGUOUS suffix of retained records: a corruption hole
+   *  (missing/garbled record) breaks before/after coverage, so a naive
+   *  first..last span would advertise versions rollback cannot restore. */
+  range(): VersionRange | null {
+    const edits = this.history();
+    const last = edits.at(-1);
+    if (!last) return null;
+    let start = edits.length - 1;
+    while (start > 0 && edits[start - 1]!.version === edits[start]!.baseVersion) start--;
+    return { from: edits[start]!.baseVersion, to: last.version };
+  }
+
+  /** Content at a recorded version, or undefined when evicted/unknown. Besides a
+   *  record's own `after`, any record with baseVersion === version restores it via
+   *  `before` — recoverable even when the record that PRODUCED it was corrupted. */
+  contentAt(version: number): string | undefined {
+    const edits = this.history();
+    const direct = edits.find((e) => e.version === version);
+    if (direct) return direct.after;
+    return edits.find((e) => e.baseVersion === version)?.before;
+  }
+
+  /** True when the target was modified outside the ledger since the last edit. */
+  drifted(): boolean {
+    const last = this.history().at(-1);
+    return last !== undefined && this.read() !== last.after;
+  }
+
+  /** Record an edit and write the target. Optimistic concurrency: `baseVersion`
+   *  must equal the current version or the commit is rejected BEFORE any disk
+   *  mutation — no partial write. `before` is read from disk here, so the
+   *  record stays truthful even if the target drifted externally. */
+  commit(after: string, reason: string, baseVersion: number, now: number = Date.now()): CommitResult {
+    const currentVersion = this.version();
+    if (baseVersion !== currentVersion) {
+      return {
+        ok: false, code: "version-conflict", baseVersion, currentVersion,
+        message: `baseVersion ${baseVersion} does not match current version ${currentVersion}; re-read and retry`,
+      };
+    }
+    return { ok: true, edit: this.write(after, reason, currentVersion, now) };
+  }
+
+  /** One-call rollback to any retained version. Recorded as a NEW edit with
+   *  `rollbackTo` (prime `rollbackOf` pattern) — history is append-only, and
+   *  the restored content is byte-exact from the stored snapshot. */
+  rollback(toVersion: number, reason?: string, now: number = Date.now()): RollbackResult {
+    const content = this.contentAt(toVersion);
+    if (content === undefined) {
+      const available = this.range();
+      return {
+        ok: false, code: "unknown-version", requested: toVersion, available,
+        message: available
+          ? `version ${toVersion} is not restorable; available: ${available.from}..${available.to}`
+          : `version ${toVersion} is not restorable; no recorded edits`,
+      };
+    }
+    const edit = this.write(content, reason ?? `rollback to v${toVersion}`, this.version(), now, toVersion);
+    return { ok: true, edit };
+  }
+
+  /** Append the record, evict past the bound, then atomically write the target.
+   *  Ledger-first ordering: a crash between the two leaves an honest record
+   *  (visible via drifted()) rather than an unrecorded content change. */
+  private write(after: string, reason: string, currentVersion: number, now: number, rollbackTo?: number): VersionedEdit {
+    const edit: VersionedEdit = {
+      version: currentVersion + 1, baseVersion: currentVersion,
+      before: this.read(), after, reason, timestamp: now,
+      ...(rollbackTo !== undefined ? { rollbackTo } : {}),
+    };
+    mkdirSync(dirname(this.ledgerPath), { recursive: true });
+    // Heal a torn trailing append: a crash mid-append can leave the last line
+    // without "\n" — appending straight on would concatenate this record into the
+    // torn line, making the NEW commit invisible to history()/version().
+    let record = JSON.stringify(edit) + "\n";
+    if (existsSync(this.ledgerPath)) {
+      const raw = readFileSync(this.ledgerPath);
+      if (raw.length > 0 && raw[raw.length - 1] !== 0x0a) record = "\n" + record;
+    }
+    appendFileSync(this.ledgerPath, record, "utf8");
+    const edits = this.history();
+    if (edits.length > this.maxEdits) {
+      const kept = edits.slice(edits.length - this.maxEdits);
+      atomicWrite(this.ledgerPath, kept.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    }
+    atomicWrite(this.targetPath, after);
+    return edit;
+  }
+}