@zuzuucodes/cli 1.5.0 → 1.6.0

package/zuzuu/faculties/knowledge/index.mjs

@@ -0,0 +1,185 @@
+// zuzuu/faculties/knowledge/index.mjs — the Knowledge faculty module.
+//
+// Consolidates the faculty's spine surface behind the Faculty Module contract
+// (faculty.json manifest + hook exports): the adapter (ingest/validate/apply/
+// render — wraps the EXISTING Knowledge pipeline: proposals/ER/registry/items/
+// index), the miner (the source-A distill path), and the digest section.
+// Substrate code stays in zuzuu/knowledge/ — this module is the contract face.
+
+import { resolve as erResolve } from '../../knowledge/er.mjs';
+import { loadRegistry, validateItem } from '../../knowledge/registry.mjs';
+import { allItems, slugify } from '../../knowledge/items.mjs';
+import { applyKnowledgeProposal, createProposal } from '../../knowledge/proposals.mjs';
+import { aggregate } from '../../knowledge/distill.mjs';
+
+const name = 'knowledge';
+
+export const manifest = {
+  id: 'knowledge',
+  title: 'Knowledge',
+  tagline: "what's TRUE — facts about this project",
+  version: '1.0.0',
+  contract: 1,
+  kinds: ['fact', 'entity', 'command', 'decision'],
+  itemsDir: 'items',
+  schema: 'schema.json',
+  hooks: { miner: true, digest: true, eval: false, gate: false },
+  ui: { icon: 'book', accent: 'info', teaching: 'Facts zuzuu learns from your sessions land here after your approval.' },
+};
+
+// ---------------------------------------------------------------------------
+// adapter (WS2-T2 — unchanged behaviour)
+// ---------------------------------------------------------------------------
+
+/**
+ * Ingest a raw candidate: run ER against existing items and return the
+ * normalised payload + analysis. Mirrors what createProposal computes today.
+ * @param {string} agentDir
+ * @param {{candidate:object, source?:string, evidence?:object}} raw
+ */
+function ingest(agentDir, raw) {
+  const { items } = allItems(agentDir);
+  const candidate = { ...raw.candidate };
+  candidate.id = candidate.id || slugify(candidate.body);
+  const er = erResolve(candidate, items);
+  return { payload: candidate, analysis: { er }, dedupeKey: candidate.id };
+}
+
+/**
+ * Validate an item against the Knowledge registry.
+ * @returns {{ok:boolean, errors:string[], warnings:string[]}}
+ */
+export function validate(agentDir, payload) {
+  const reg = loadRegistry(agentDir);
+  const v = validateItem(reg, payload);
+  const warnings = [
+    ...v.unknownKeys.attributes.map((k) => `unregistered attribute '${k}'`),
+    ...v.unknownKeys.relations.map((t) => `unregistered relation type '${t}'`),
+  ];
+  return { ok: v.ok, errors: v.errors, warnings };
+}
+
+/**
+ * Apply an approved proposal — delegates to the extracted approve apply body.
+ * @returns {{ok:boolean, action:string, itemIds:string[], warnings:string[]}}
+ */
+function apply(agentDir, proposal) {
+  // Bridge spine-shaped records (payload/analysis.er) onto applyKnowledgeProposal's
+  // legacy shape (candidate/er). Records that still carry candidate/er pass through.
+  const legacy = {
+    ...proposal,
+    candidate: proposal.candidate ?? proposal.payload,
+    er: proposal.er ?? proposal.analysis?.er,
+  };
+  const r = applyKnowledgeProposal(agentDir, legacy);
+  return {
+    ok: r.ok,
+    action: r.action,
+    itemIds: r.item ? [r.item] : [],
+    warnings: r.warnings ?? [],
+  };
+}
+
+export const applyProposal = apply;
+
+/**
+ * Render a proposal for the human gate. `card` mirrors the multi-line summary
+ * `zuzuu review` shows for knowledge proposals (id, type, attrs/relations, ER
+ * verdict); `line` is the one-line list form (`zuzuu proposals list`).
+ * @returns {{line:string, card:string}}
+ */
+function render(proposal) {
+  if (proposal.kind === 'registry') {
+    const what = `register ${String(proposal.registry).slice(0, -1)} '${proposal.key}'`;
+    return {
+      line: `${proposal.id}  [${proposal.kind}]  ${what}`,
+      card: `${what}  (seen ${proposal.evidence?.occurrences}× in candidates)`,
+    };
+  }
+  const c = proposal.candidate ?? {};
+  const er = proposal.er ?? {};
+  const lines = [];
+  lines.push(`${c.id ?? ''} ── ${c.type}: ${c.body?.slice(0, 100).replace(/\n/g, ' ')}`);
+  for (const [k, v] of Object.entries(c.attributes ?? {})) lines.push(`  · ${k} = ${v}`);
+  for (const r of c.relations ?? []) lines.push(`  → ${r.type} ${r.target}`);
+  lines.push(`  er: ${er.verdict}${er.match ? ` → ${er.match}` : ''}  (${(er.confidence ?? 0).toFixed(2)} · ${er.reason ?? ''})`);
+  return {
+    line: `${proposal.id}  [${er.verdict ?? proposal.kind}]  ${c.type}: ${c.body?.slice(0, 60).replace(/\n/g, ' ')}`,
+    card: lines.join('\n'),
+  };
+}
+
+export const adapter = { name, ingest, validate, apply, render };
+
+// ---------------------------------------------------------------------------
+// miner (WS5-T1 — the golden source-A distill path, unchanged)
+// ---------------------------------------------------------------------------
+
+/** File one knowledge proposal per aggregated candidate; return the count of
+ *  actually-filed proposals (archive-resolved ids are skipped, not re-filed). */
+export function propose(agentDir, aggregated) {
+  let count = 0;
+  for (const c of aggregated) {
+    const p = createProposal(agentDir, { candidate: c.candidate, source: 'distill', evidence: c.evidence });
+    if (p && p.status !== 'archived-skip') count++;
+  }
+  return count;
+}
+
+export const miner = { faculty: name, aggregate, propose };
+
+export { aggregate };
+
+// ---------------------------------------------------------------------------
+// digest section (moved from the pre-module digest, byte-identical output)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Knowledge digest section: most-recent items under the shared char budget.
+ * @param {string} agentDir
+ * @param {{limit:number, charBudget:number, priorLines:string[]}} ctx
+ * @returns {{lines: string[], data: object}}
+ */
+export function digestSection(agentDir, { limit, charBudget, priorLines }) {
+  let knowledge;
+  try {
+    const { items } = allItems(agentDir);
+    const ranked = [...items]
+      .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)))
+      .slice(0, limit);
+    knowledge = { count: items.length, shown: ranked.map((i) => ({ id: i.id, type: i.type, body: i.body })) };
+  } catch {
+    knowledge = { count: 0, shown: [] };
+  }
+  const lines = ['## Knowledge'];
+  if (!knowledge.count) {
+    lines.push('(no items yet — propose facts to knowledge/inbox/)');
+    return { lines, data: { ...knowledge, renderedCount: 0 } };
+  }
+  lines.push(`${knowledge.count} item(s); most recent:`);
+  let shown = 0;
+  for (const it of knowledge.shown) {
+    const line = `- ${it.id} · ${it.type} · ${it.body.split('\n')[0].slice(0, 80)}`;
+    // join is O(items²) but trivial: once-per-session, limit default 5
+    if ([...priorLines, ...lines].join('\n').length + line.length > charBudget && shown > 0) break;
+    lines.push(line);
+    shown++;
+  }
+  const dropped = knowledge.count - shown;
+  if (dropped > 0) lines.push(`- … (${dropped} more — \`zuzuu recall\`)`);
+  // `shown` = items actually rendered (after budget); `count` = total available
+  return { lines, data: { ...knowledge, shown: knowledge.shown.slice(0, shown), renderedCount: shown } };
+}
+
+// ---------------------------------------------------------------------------
+// session signals (the observability surface — `zuzuu session inspect`)
+// ---------------------------------------------------------------------------
+
+/** Counts of the mined-signal superset slices this faculty grows from. */
+export function sessionSignals(signals = {}) {
+  return {
+    commands: signals.commands?.length ?? 0,
+    files: signals.files?.length ?? 0,
+    failures: signals.failures?.length ?? 0,
+  };
+}

package/zuzuu/{memory/adapter.mjs → faculties/memory/index.mjs}

@@ -1,7 +1,9 @@
-// zuzuu/memory/adapter.mjs
-// The Memory faculty adapter. Wraps episode proposals behind the
-// faculty-spine adapter contract — { name, ingest, validate, apply, render } —
-// so `zuzuu review` can surface and approve memory entries uniformly.
+// zuzuu/faculties/memory/index.mjs — the Memory faculty module.
+//
+// Consolidates the adapter (episode proposals → envelope entries) and the
+// miner STUB (WS5-T4, deferred — see the WHAT IT WOULD MINE note below) behind
+// the Faculty Module contract. No digest section today (the pre-module digest
+// never rendered one — preserved).
 //
 // A memory proposal payload is an episode record:
 //   { id, date, title, provenance: {sessions, hosts}, tags, body }
@@ -11,13 +13,28 @@
 //        (kind: episode; payload = {sessions, hosts, tags}; body = the
 //        Attempted / Resulted / Remember-next-time sections).
 //
-// Registers itself on import.
+// MINER (when implemented): completed-session episodes — a Run that reached
+// `completed` in .zuzuu/sessions.json distilled into curated entries, emitted
+// as kind-'episode' proposals for `zuzuu review`. Deferred until the Memory
+// substrate decision lands and completed runs carry rich enough trace data.
 
-import * as registry from '../faculty/registry.mjs';
-import { writeFacultyItem } from '../faculty/items.mjs';
+import { writeFacultyItem } from '../../faculty/items.mjs';
 
 const name = 'memory';
 
+export const manifest = {
+  id: 'memory',
+  title: 'Memory',
+  tagline: 'what HAPPENED — curated episodes from past sessions',
+  version: '1.0.0',
+  contract: 1,
+  kinds: ['episode'],
+  itemsDir: 'entries',
+  schema: 'schema.json',
+  hooks: { miner: true, digest: false, eval: false, gate: false },
+  ui: { icon: 'clock', accent: 'neutral', teaching: 'Curated episodes from past sessions — what was attempted, what resulted, what to remember.' },
+};
+
 // mem-<YYYY-MM-DD>-<slug>: the id must START with "mem-"
 const MEM_ID_RE = /^mem-/;
 
@@ -37,7 +54,7 @@ function ingest(_agentDir, raw) {
  * Validate an episode payload.
  * @returns {{ok:boolean, errors:string[], warnings:string[]}}
  */
-function validate(_agentDir, payload) {
+export function validate(_agentDir, payload) {
   const errors = [];
   if (!payload?.id || typeof payload.id !== 'string') {
     errors.push('id is required');
@@ -76,6 +93,8 @@ function apply(agentDir, proposal) {
   return { ok: true, action: `wrote memory ${p.id}`, itemIds: [p.id] };
 }
 
+export const applyProposal = apply;
+
 /**
  * Render an episode proposal for the human gate.
  * @returns {{line:string, card:string}}
@@ -93,4 +112,13 @@ function render(proposal) {
 
 export const adapter = { name, ingest, validate, apply, render };
 
-registry.register(adapter);
+// ---------------------------------------------------------------------------
+// miner (registered no-op stub — deferred)
+// ---------------------------------------------------------------------------
+
+export const miner = {
+  faculty: name,
+  stub: true,
+  aggregate: () => [],
+  propose: () => 0,
+};

package/zuzuu/faculty/generation/read.mjs

@@ -0,0 +1,206 @@
+// zuzuu/faculty/generation/read.mjs — the generation READ side (WS3-T1, split
+// per the 2026-06-13 overhaul): paths, the pinned-set enumerators, snapshot
+// hashing, list/show/diff. Minting + rollback live in write.mjs.
+//
+// A *generation* is an immutable, content-addressed snapshot of the agent's
+// pinned faculties (the lockfile). Minting freezes the current faculty state;
+// rollback restores any past generation by *content* (we copy each pinned item's
+// bytes into generations/snapshots/<id>/ at mint time, so a rollback works even
+// for items that were never committed). Identity: Agent → Generation → Run —
+// rollback = flip the active pointer + restore content; never `git revert`.
+//
+// Layout under .zuzuu/:
+//   generations/active             {active: "gen_NNN"}  — the live pointer
+//   generations/<id>.json          the lockfile (content-addressed manifest)
+//   generations/snapshots/<id>/<faculty>/...  pinned item bytes (rollback source)
+
+import { createHash } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+
+/** Hex sha256 of a string or Buffer. */
+export function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+const read = (p) => readFileSync(p, 'utf8');
+export const readJson = (p) => JSON.parse(read(p));
+
+// --- paths ------------------------------------------------------------------
+
+export const generationsDir = (agentDir) => join(agentDir, 'generations');
+export const snapshotsDir = (agentDir) => join(generationsDir(agentDir), 'snapshots');
+export const activePath = (agentDir) => join(generationsDir(agentDir), 'active');
+export const lockfilePath = (agentDir, id) => join(generationsDir(agentDir), `${id}.json`);
+export const agentJsonPath = (agentDir) => join(agentDir, 'agent.json');
+
+// --- faculty file enumeration (the pinned set) ------------------------------
+// Each entry: { id, faculty, src (absolute live path), rel (path under the
+// faculty snapshot dir), hash }. `rel` is what we mirror into snapshots/<id>/.
+
+function sortDirents(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function knowledgeFiles(agentDir) {
+  const dir = join(agentDir, 'knowledge', 'items');
+  return sortDirents(dir)
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => {
+      const src = join(dir, e.name);
+      return { id: e.name.replace(/\.md$/, ''), faculty: 'knowledge', src, rel: e.name, hash: sha256(readFileSync(src)) };
+    });
+}
+
+export function actionFiles(agentDir) {
+  const dir = join(agentDir, 'actions');
+  return sortDirents(dir)
+    .filter((e) => e.isDirectory() && e.name !== 'inbox' && e.name !== 'proposals' && e.name !== '_rolledback')
+    .map((e) => {
+      const adir = join(dir, e.name);
+      // Hash the dir's defining files concatenated: the ACTION.md envelope
+      // (W24) + sibling scripts (*.mjs — run.mjs and any payload.exec module).
+      const parts = sortDirents(adir)
+        .filter((f) => f.isFile() && (f.name === 'ACTION.md' || f.name.endsWith('.mjs')))
+        .map((f) => join(adir, f.name));
+      const concat = Buffer.concat(parts.map((p) => readFileSync(p)));
+      return {
+        id: e.name, faculty: 'actions', files: parts.map((p) => p.slice(adir.length + 1)),
+        adir, hash: parts.length ? sha256(concat) : null,
+      };
+    });
+}
+
+/** Flat envelope-item faculties share one enumerator. */
+function mdItemFiles(agentDir, faculty, ...segments) {
+  const dir = join(agentDir, ...segments);
+  return sortDirents(dir)
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => {
+      const src = join(dir, e.name);
+      return { id: e.name.replace(/\.md$/, ''), faculty, src, rel: e.name, hash: sha256(readFileSync(src)) };
+    });
+}
+
+export const guardrailFiles = (agentDir) => mdItemFiles(agentDir, 'guardrails', 'guardrails', 'items');
+export const instructionFiles = (agentDir) => mdItemFiles(agentDir, 'instructions', 'instructions', 'items');
+
+export function memoryFiles(agentDir) {
+  const dir = join(agentDir, 'memory', 'entries');
+  return sortDirents(dir)
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => {
+      const src = join(dir, e.name);
+      return { id: e.name.replace(/\.md$/, ''), faculty: 'memory', src, rel: e.name, hash: sha256(readFileSync(src)) };
+    });
+}
+
+export function registryHash(agentDir) {
+  const dir = join(agentDir, 'knowledge', 'registry');
+  const files = sortDirents(dir).filter((e) => e.isFile() && e.name.endsWith('.json'));
+  if (!files.length) return null;
+  return sha256(Buffer.concat(files.map((e) => readFileSync(join(dir, e.name)))));
+}
+
+/**
+ * Snapshot the current faculty state → the `faculties` manifest object.
+ * Tolerates missing files (empty arrays / null hashes).
+ */
+export function snapshotFaculties(agentDir) {
+  return {
+    knowledge: {
+      items: knowledgeFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
+      registryHash: registryHash(agentDir),
+    },
+    actions: {
+      items: actionFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
+    },
+    guardrails: {
+      items: guardrailFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
+    },
+    instructions: {
+      items: instructionFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
+    },
+    memory: {
+      items: memoryFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
+    },
+  };
+}
+
+// --- agent identity ---------------------------------------------------------
+
+/** Stable agent id derived from the repo root: agt_<first12 of sha256(root)>. */
+export function agentId(agentDir) {
+  // agentDir is the .zuzuu/ dir; the repo root is its parent.
+  const root = dirname(agentDir);
+  return 'agt_' + sha256(root).slice(0, 12);
+}
+
+// --- generation read/list ---------------------------------------------------
+
+/** The active generation id, or null. */
+export function activeGeneration(agentDir) {
+  const p = activePath(agentDir);
+  if (!existsSync(p)) return null;
+  try { return readJson(p).active ?? null; } catch { return null; }
+}
+
+/** All generation ids in ascending order. */
+export function listGenerations(agentDir) {
+  const dir = generationsDir(agentDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /^gen_\d+\.json$/.test(f))
+    .map((f) => f.replace(/\.json$/, ''))
+    .sort();
+}
+
+/** Read one lockfile, or null. */
+export function readGeneration(agentDir, id) {
+  const p = lockfilePath(agentDir, id);
+  return existsSync(p) ? readJson(p) : null;
+}
+
+/** Diff two item-manifest arrays → {added, changed, removed} (id lists). */
+function diffItems(parentItems = [], childItems = []) {
+  const p = new Map(parentItems.map((i) => [i.id, i.hash]));
+  const c = new Map(childItems.map((i) => [i.id, i.hash]));
+  const added = [], changed = [], removed = [];
+  for (const [id, hash] of c) {
+    if (!p.has(id)) added.push(id);
+    else if (p.get(id) !== hash) changed.push(id);
+  }
+  for (const id of p.keys()) if (!c.has(id)) removed.push(id);
+  return { added: added.sort(), changed: changed.sort(), removed: removed.sort() };
+}
+
+/**
+ * Per-faculty diff of generation `id` against its forkedFrom parent (pure).
+ * ALL five faculties are item lists under the Faculty Standard (W24) —
+ * added/changed/removed id lists per faculty; knowledge additionally reports
+ * registryChanged. When there is no parent (forkedFrom null), everything
+ * present counts as added. Returns null for an unknown id.
+ */
+export function diffGenerations(agentDir, id) {
+  const child = readGeneration(agentDir, id);
+  if (!child) return null;
+  const parent = child.forkedFrom ? readGeneration(agentDir, child.forkedFrom) : null;
+  const cf = child.faculties || {};
+  const pf = parent?.faculties || {};
+  const faculties = {};
+  for (const f of ['knowledge', 'actions', 'memory', 'guardrails', 'instructions']) {
+    faculties[f] = diffItems(pf[f]?.items, cf[f]?.items);
+    // knowledge also has a registry hash
+    if (f === 'knowledge') {
+      faculties[f].registryChanged = (cf.knowledge?.registryHash ?? null) !== (pf.knowledge?.registryHash ?? null);
+    }
+  }
+  return {
+    id,
+    forkedFrom: child.forkedFrom ?? null,
+    mintedFrom: Array.isArray(child.mintedFrom) ? child.mintedFrom : [],
+    mintedAt: child.mintedAt ?? null,
+    faculties,
+  };
+}

package/zuzuu/faculty/generation/write.mjs

@@ -0,0 +1,207 @@
+// zuzuu/faculty/generation/write.mjs — the generation WRITE side (WS3-T1,
+// split per the 2026-06-13 overhaul): agent identity repair, minting (freeze +
+// snapshot + flip active) and rollback (restore by content). Read-side paths,
+// enumerators and diffing live in read.mjs.
+
+import { join, dirname } from 'node:path';
+import {
+  existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, renameSync,
+} from 'node:fs';
+import { reindex } from '../../knowledge/index.mjs';
+import {
+  snapshotsDir, activePath, lockfilePath, agentJsonPath, readJson,
+  knowledgeFiles, memoryFiles, actionFiles, guardrailFiles, instructionFiles,
+  snapshotFaculties, agentId, listGenerations, readGeneration,
+} from './read.mjs';
+
+const writeJson = (p, obj) => {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+};
+
+/** Add/repair the agent block in agent.json (bump to v2), preserving other fields. */
+export function ensureAgent(agentDir) {
+  const path = agentJsonPath(agentDir);
+  const m = existsSync(path) ? readJson(path) : {};
+  const id = agentId(agentDir);
+  if (!m.agent || !m.agent.id) {
+    m.agent = { id, createdAt: new Date().toISOString() };
+  }
+  m.version = 2;
+  writeJson(path, m);
+  return m.agent;
+}
+
+function nextGenId(agentDir) {
+  const ids = listGenerations(agentDir);
+  const max = ids.reduce((m, id) => Math.max(m, parseInt(id.slice(4), 10) || 0), 0);
+  return 'gen_' + String(max + 1).padStart(3, '0');
+}
+
+// --- mint -------------------------------------------------------------------
+
+function copySnapshot(agentDir, id) {
+  const base = join(snapshotsDir(agentDir), id);
+  for (const it of knowledgeFiles(agentDir)) {
+    const dest = join(base, 'knowledge', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+  for (const it of memoryFiles(agentDir)) {
+    const dest = join(base, 'memory', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+  for (const a of actionFiles(agentDir)) {
+    for (const rel of a.files) {
+      const dest = join(base, 'actions', a.id, rel);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, readFileSync(join(a.adir, rel)));
+    }
+  }
+  for (const it of guardrailFiles(agentDir)) {
+    const dest = join(base, 'guardrails', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+  for (const it of instructionFiles(agentDir)) {
+    const dest = join(base, 'instructions', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+}
+
+/**
+ * Mint a new generation: freeze the current faculty state into a content-addressed
+ * lockfile + a byte-for-byte snapshot, and make it active.
+ */
+export function mintGeneration(agentDir, { forkedFrom = null, mintedFrom = [] } = {}) {
+  const agent = ensureAgent(agentDir).id;
+  const id = nextGenId(agentDir);
+  const lockfile = {
+    id,
+    agent,
+    mintedAt: new Date().toISOString(),
+    forkedFrom,
+    mintedFrom,
+    faculties: snapshotFaculties(agentDir),
+  };
+  copySnapshot(agentDir, id);
+  writeJson(lockfilePath(agentDir, id), lockfile);
+  writeJson(activePath(agentDir), { active: id });
+  return lockfile;
+}
+
+// --- rollback ---------------------------------------------------------------
+
+function archive(agentDir, faculty, src) {
+  // Park (never delete) under <faculty>/_rolledback/<basename> — by basename so
+  // a restore is a simple, flat audit trail of what the rollback displaced.
+  const dest = join(agentDir, faculty, '_rolledback', src.slice(dirname(src).length + 1));
+  mkdirSync(dirname(dest), { recursive: true });
+  renameSync(src, dest);
+}
+
+/**
+ * Restore a past generation by content: write each snapshotted item back to its
+ * live faculty path; MOVE (never delete) active items absent from the target into
+ * <faculty>/_rolledback/; reindex knowledge; flip the active pointer.
+ */
+export function rollback(agentDir, id) {
+  const target = readGeneration(agentDir, id);
+  if (!target) throw new Error(`no generation '${id}'`);
+  const base = join(snapshotsDir(agentDir), id);
+  let restored = 0;
+
+  // 1) restore snapshotted knowledge items
+  const targetKnowledge = new Set((target.faculties.knowledge?.items ?? []).map((i) => i.id));
+  for (const i of target.faculties.knowledge?.items ?? []) {
+    const snap = join(base, 'knowledge', `${i.id}.md`);
+    if (existsSync(snap)) {
+      const dest = join(agentDir, 'knowledge', 'items', `${i.id}.md`);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, readFileSync(snap));
+      restored++;
+    }
+  }
+  // archive live knowledge items not in the target
+  const kdir = join(agentDir, 'knowledge', 'items');
+  if (existsSync(kdir)) {
+    for (const e of readdirSync(kdir, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith('.md') && !targetKnowledge.has(e.name.replace(/\.md$/, ''))) {
+        archive(agentDir, 'knowledge', join(kdir, e.name));
+      }
+    }
+  }
+
+  // 2) restore snapshotted memory items + archive extras
+  const targetMemory = new Set((target.faculties.memory?.items ?? []).map((i) => i.id));
+  for (const i of target.faculties.memory?.items ?? []) {
+    const snap = join(base, 'memory', `${i.id}.md`);
+    if (existsSync(snap)) {
+      const dest = join(agentDir, 'memory', 'entries', `${i.id}.md`);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, readFileSync(snap));
+      restored++;
+    }
+  }
+  const mdir = join(agentDir, 'memory', 'entries');
+  if (existsSync(mdir)) {
+    for (const e of readdirSync(mdir, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith('.md') && !targetMemory.has(e.name.replace(/\.md$/, ''))) {
+        archive(agentDir, 'memory', join(mdir, e.name));
+      }
+    }
+  }
+
+  // 3) restore snapshotted actions + archive extras
+  const targetActions = new Set((target.faculties.actions?.items ?? []).map((i) => i.id));
+  const asnap = join(base, 'actions');
+  if (existsSync(asnap)) {
+    for (const slugEnt of readdirSync(asnap, { withFileTypes: true })) {
+      if (!slugEnt.isDirectory()) continue;
+      const sdir = join(asnap, slugEnt.name);
+      for (const f of readdirSync(sdir)) {
+        const dest = join(agentDir, 'actions', slugEnt.name, f);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, readFileSync(join(sdir, f)));
+      }
+      restored++;
+    }
+  }
+  const adir = join(agentDir, 'actions');
+  if (existsSync(adir)) {
+    for (const e of readdirSync(adir, { withFileTypes: true })) {
+      if (e.isDirectory() && e.name !== 'inbox' && e.name !== 'proposals' && e.name !== '_rolledback' && !targetActions.has(e.name)) {
+        archive(agentDir, 'actions', join(adir, e.name));
+      }
+    }
+  }
+
+  // 4) restore guardrails + instructions items (same item-list contract)
+  for (const [faculty, liveSeg] of [['guardrails', ['guardrails', 'items']], ['instructions', ['instructions', 'items']]]) {
+    const targetIds = new Set((target.faculties[faculty]?.items ?? []).map((i) => i.id));
+    for (const i of target.faculties[faculty]?.items ?? []) {
+      const snap = join(base, faculty, `${i.id}.md`);
+      if (existsSync(snap)) {
+        const dest = join(agentDir, ...liveSeg, `${i.id}.md`);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, readFileSync(snap));
+        restored++;
+      }
+    }
+    const liveDir = join(agentDir, ...liveSeg);
+    if (existsSync(liveDir)) {
+      for (const e of readdirSync(liveDir, { withFileTypes: true })) {
+        if (e.isFile() && e.name.endsWith('.md') && !targetIds.has(e.name.replace(/\.md$/, ''))) {
+          archive(agentDir, faculty, join(liveDir, e.name));
+        }
+      }
+    }
+  }
+
+  // 5) regenerate the derived knowledge index + flip the pointer
+  try { reindex(agentDir); } catch { /* derived index; tolerate absence of node:sqlite features */ }
+  writeJson(activePath(agentDir), { active: id });
+  return { ok: true, restored };
+}