noggin-cli 0.1.3 → 0.4.2

package/noggin-api.mjs

@@ -1,37 +1,41 @@
-// noggin-api — typed, in-process API for the noggin working-memory tree.
+// noggin-api — typed, in-process engine for the noggin working-memory tree.
 //
-// Used by both the CLI wrapper (cli/noggin.mjs) and the VS Code extension.
-// Two layers:
-//   1. Stateless verb functions (`apiPush`, `apiAdd`, …) that take a file
-//      path and an options object, do load → mutate → save, and return a
-//      view of the resulting tree. These power the CLI.
-//   2. `Noggin` class — long-lived handle over one file. Caches the parsed
-//      store, watches the file for external edits, fires onDidChange.
-//      Used by the extension.
+// Three pillars:
+//   1. `NogginDocument` and atomic ops (`AtomicOp`, `applyOps`) — the data
+//      model and the only way to mutate it.
+//   2. `verbs.*` — the user-facing verb behaviors (push, add, done, …)
+//      implemented exactly once. Each verb reads state via a `Noggin`,
+//      composes a list of `AtomicOp`s, and calls `noggin.apply(ops)`.
+//   3. Factories + `openNoggin(location)` — backends register a scheme
+//      prefix and an `open(location)` function. The engine never touches
+//      a file or any other storage; backends do.
 //
-// Every failure throws a `NogginError` with a stable `code` and a CLI-style
-// `exitCode`. Nothing in here writes to process.stderr or calls process.exit;
-// that is the CLI wrapper's job. Error messages preserve the exact wording
-// of the original cli.mjs so user-visible behaviour is unchanged.
+// Backends only implement the `Noggin` interface (a handful of read
+// accessors + `apply(ops)` + lifecycle + events). Verb semantics are
+// not per-backend; they live in `verbs.*` and call the backend through
+// the small `apply` primitive.
+//
+// Every failure throws a `NogginError` with a stable `code` and a
+// CLI-style `exitCode`. Nothing in here writes to process.stderr or
+// calls process.exit.
 
 /// <reference path="./noggin-api.d.mts" />
 
-import yaml from 'js-yaml';
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
 import crypto from 'node:crypto';
 
 export const SCHEMA_VERSION = 1;
-export const DEFAULT_FILE = path.join(os.homedir(), '.noggin.yaml');
 
 /**
- * Version tag stamped onto every JSON envelope this module produces (via
- * `formatSuccess` / `formatError`). Independent of the on-disk store
- * `SCHEMA_VERSION`; bump when the shape of `CurrentTreeView`, the envelope,
- * or any per-verb payload changes in a breaking way.
+ * Version stamped onto every response envelope this module produces
+ * (via `formatSuccess` / `formatError`). Distinct from the on-disk
+ * document `SCHEMA_VERSION`; bump when the envelope shape, the
+ * `CurrentTreeView` shape, or any per-verb payload changes in a
+ * breaking way.
  */
-export const JSON_SCHEMA_VERSION = 2;
+export const RESPONSE_ENVELOPE_VERSION = 3;
+
+/** @deprecated Renamed to `RESPONSE_ENVELOPE_VERSION`. */
+export const JSON_SCHEMA_VERSION = RESPONSE_ENVELOPE_VERSION;
 
 /**
  * Text of the system-generated note appended whenever an item transitions
@@ -67,8 +71,8 @@ function runtime(code, message) {
 
 // ── Low-level helpers ────────────────────────────────────────────────────────
 
-function nowIso() {
-  return new Date().toISOString();
+function nowIso(ctx) {
+  return ((ctx && ctx.now) || new Date()).toISOString();
 }
 
 function newKey() {
@@ -81,21 +85,29 @@ function newKey() {
   return `i-${slug}-${hex}`;
 }
 
-function emptyStore() {
+function emptyDocument() {
   return { schemaVersion: SCHEMA_VERSION, active: null, items: [] };
 }
 
-function normalizeNote(note) {
+/**
+ * Normalize a single note object. Exported for the serializers, which
+ * share this shape contract.
+ */
+export function normalizeNote(note) {
   if (note && typeof note === 'object' && note.text !== undefined) {
     return { timestamp: note.timestamp ? String(note.timestamp) : null, text: String(note.text) };
   }
   usage('invalid-note', 'internal: invalid note object');
 }
 
-function normalizeStore(store) {
-  store.schemaVersion = SCHEMA_VERSION;
-  for (const f of store.items) {
-    if (!Array.isArray(f.notes)) usage('invalid-store', 'invalid contents: item notes must be an array');
+/**
+ * Normalize a parsed document in place: stamp schemaVersion, normalize
+ * notes, strip legacy fields. Used by serializers and by `applyOps`.
+ */
+export function normalizeDocument(doc) {
+  doc.schemaVersion = SCHEMA_VERSION;
+  for (const f of doc.items) {
+    if (!Array.isArray(f.notes)) usage('invalid-document', 'invalid contents: item notes must be an array');
     f.notes = f.notes.map(normalizeNote);
     // closedAt and pushedAt were both dropped before noggin shipped.
     // Strip them on load so a dev's pre-rename test file doesn't carry
@@ -103,71 +115,48 @@ function normalizeStore(store) {
     if ('closedAt' in f) delete f.closedAt;
     if ('pushedAt' in f) delete f.pushedAt;
   }
-  return store;
+  return doc;
 }
 
-function validateStore(store) {
+/**
+ * Validate a document's structural invariants. Throws `NogginError`
+ * with code `'invalid-document'` if anything's wrong:
+ *   - unique keys
+ *   - parentKey references resolve
+ *   - no cycles in the parent chain
+ *   - active references an existing item (or is null)
+ */
+export function validateDocument(doc) {
+  if (!doc || !Array.isArray(doc.items)) {
+    usage('invalid-document', 'invalid contents: expected items array');
+  }
   const keys = new Set();
-  for (const f of store.items) {
-    if (!f.key) usage('invalid-store', 'internal: item missing key');
-    if (keys.has(f.key)) usage('invalid-store', 'internal: duplicate item key detected');
+  for (const f of doc.items) {
+    if (!f.key) usage('invalid-document', 'internal: item missing key');
+    if (keys.has(f.key)) usage('invalid-document', 'internal: duplicate item key detected');
     keys.add(f.key);
   }
-  for (const f of store.items) {
-    if (f.parentKey && !keys.has(f.parentKey)) {
-      usage('invalid-store', 'internal: item has unknown parent reference');
+  for (const f of doc.items) {
+    if (f.parentKey != null && !keys.has(f.parentKey)) {
+      usage('invalid-document', `internal: item '${f.key}' has unknown parent reference '${f.parentKey}'`);
     }
   }
-  if (store.active && !keys.has(store.active)) {
-    usage('invalid-store', 'internal: active points to unknown item');
+  // Cycle check: walk parent chain from each item, bound by item count.
+  const limit = doc.items.length + 1;
+  for (const f of doc.items) {
+    let n = f;
+    let steps = 0;
+    while (n.parentKey != null) {
+      if (++steps > limit) {
+        usage('invalid-document', `internal: parent chain cycle detected at '${f.key}'`);
+      }
+      n = doc.items.find((x) => x.key === n.parentKey);
+      if (!n) break; // already caught above; defensive
+    }
   }
-}
-
-/**
- * Load and validate a YAML store. Returns an empty store if the file does
- * not exist or is empty.
- */
-export function loadStore(filePath) {
-  if (!fs.existsSync(filePath)) return emptyStore();
-  let raw;
-  try { raw = fs.readFileSync(filePath, 'utf8'); }
-  catch (e) { usage('io', `failed to read ${filePath}: ${e.message}`); }
-  if (!raw.trim()) return emptyStore();
-  let data;
-  try { data = yaml.load(raw); }
-  catch (e) { usage('invalid-store', `failed to parse ${filePath}: ${e.message}`); }
-  if (!data || typeof data !== 'object') {
-    usage('invalid-store', `invalid contents in ${filePath}: expected a mapping`);
-  }
-  if (data.schemaVersion !== SCHEMA_VERSION) {
-    usage(
-      'unsupported-schema',
-      `schemaVersion ${data.schemaVersion} in ${filePath} not supported by this CLI ` +
-        `(expected ${SCHEMA_VERSION}).`,
-    );
+  if (doc.active != null && !keys.has(doc.active)) {
+    usage('invalid-document', `internal: active points to unknown item '${doc.active}'`);
   }
-  if (!Array.isArray(data.items)) usage('invalid-store', `invalid contents in ${filePath}: expected items array`);
-  if (data.active === undefined) usage('invalid-store', `invalid contents in ${filePath}: expected active field`);
-  return normalizeStore(data);
-}
-
-function dumpStore(store) {
-  return yaml.dump(store, { noRefs: true, lineWidth: 100, sortKeys: false });
-}
-
-function writeAtomic(filePath, contents) {
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-  fs.writeFileSync(tmp, contents, 'utf8');
-  fs.renameSync(tmp, filePath);
-}
-
-/** Write a YAML store. Atomic where the platform allows. */
-export function saveStore(filePath, store) {
-  normalizeStore(store);
-  validateStore(store);
-  writeAtomic(filePath, dumpStore(store));
 }
 
 // ── Tree helpers ─────────────────────────────────────────────────────────────
@@ -558,111 +547,74 @@ function pruneDefaults(value) {
 }
 
 /**
- * Wrap a successful verb result in the canonical JSON envelope. Used by
- * both the CLI `--json` flag and the VS Code extension's language-model
- * tools so the two surfaces emit byte-identical shapes.
+ * Wrap a successful verb result in the canonical response envelope.
+ * Used by both the CLI `--json` flag and the VS Code extension's
+ * language-model tools so the two surfaces emit byte-identical shapes.
  *
- * The envelope itself (status, schemaVersion, verb, file, data) is
- * always fully present. `data` is run through `pruneDefaults` so
- * whitelisted fields equal to their declared default are omitted.
+ * The envelope itself (status, envelopeVersion, verb, data) is always
+ * fully present. `data` is run through `pruneDefaults` so whitelisted
+ * fields equal to their declared default are omitted.
  *
  * @param {object} opts
  * @param {string} [opts.verb]  Verb name (e.g. 'push', 'show').
- * @param {string|null} [opts.file]  Resolved noggin file path, or null.
- * @param {any} [opts.data]  Verb-specific payload (e.g. CurrentTreeView).
+ * @param {any} [opts.data]     Verb-specific payload (e.g. CurrentTreeView).
  */
-export function formatSuccess({ verb, file, data } = {}) {
+export function formatSuccess({ verb, data } = {}) {
   return {
     status: 'ok',
-    schemaVersion: JSON_SCHEMA_VERSION,
+    envelopeVersion: RESPONSE_ENVELOPE_VERSION,
     verb: verb || null,
-    file: file || null,
     data: data === undefined ? null : pruneDefaults(data),
   };
 }
 
 /**
- * Wrap an error in the canonical JSON envelope. Accepts a `NogginError`
- * (preserves its `code` and `exitCode`) or any other thrown value.
+ * Wrap an error in the canonical response envelope. Accepts a
+ * `NogginError` (preserves its `code` and `exitCode`) or any other
+ * thrown value.
  *
  * @param {object} opts
  * @param {string} [opts.verb]
- * @param {string|null} [opts.file]
  * @param {unknown} [opts.error]
  */
-export function formatError({ verb, file, error } = {}) {
+export function formatError({ verb, error } = {}) {
   const isNoggin = error instanceof NogginError;
   const message = error instanceof Error ? error.message : String(error ?? 'unknown error');
   const code = isNoggin ? error.code : 'noggin-error';
   const exitCode = isNoggin ? error.exitCode : 1;
   return {
     status: 'error',
-    schemaVersion: JSON_SCHEMA_VERSION,
+    envelopeVersion: RESPONSE_ENVELOPE_VERSION,
     verb: verb || null,
-    file: file || null,
     error: { code, message, exitCode },
   };
 }
 
-// ── File resolution ──────────────────────────────────────────────────────────
-
-/**
- * Resolve the noggin file path with the same priority as the CLI:
- *   1. `opts.file`
- *   2. `opts.env.NOGGIN_FILE` (defaults to process.env)
- *   3. `~/.noggin.yaml`
- */
-export function resolveFile(opts = {}) {
-  const env = opts.env || process.env;
-  let file, source;
-  if (opts.file) { file = opts.file; source = 'flag'; }
-  else if (env.NOGGIN_FILE) { file = env.NOGGIN_FILE; source = 'env'; }
-  else { file = DEFAULT_FILE; source = 'default'; }
-  return {
-    file,
-    source,
-    exists: fs.existsSync(file),
-    defaultFile: DEFAULT_FILE,
-    env: env.NOGGIN_FILE || null,
-  };
-}
-
 // ── Internal verb helpers ────────────────────────────────────────────────────
 
-function applyGoto(store, base, goto, commandName) {
+function executeGotoOption(snapshot, base, goto, commandName) {
   if (goto === undefined) return base;
   if (!base) runtime('goto-base-missing', `${commandName}: --goto has no base item`);
   const gotoPath = goto === true ? '.' : goto;
   if (!gotoPath) runtime('goto-path-required', `${commandName}: --goto requires a path`);
-  const scopedStore = { ...store, active: base.key };
-  const resolved = tryResolveDetailed(scopedStore, gotoPath);
+  const scopedDoc = { ...snapshot, active: base.key };
+  const resolved = tryResolveDetailed(scopedDoc, gotoPath);
   if (!resolved.ok) runtime('goto-unresolved', `${commandName}: --goto ${resolved.error}`);
-  store.active = resolved.item.key;
   return resolved.item;
 }
 
-function makeItem({ title, parentKey }) {
+function makeItem({ title, parentKey }, ctx) {
   return {
     key: newKey(),
-    parentKey,
+    parentKey: parentKey ?? null,
     title,
     done: false,
-    createdAt: nowIso(),
+    createdAt: nowIso(ctx),
     notes: [],
   };
 }
 
-/** Append the system-generated close note. */
-function appendCloseNote(item) {
-  if (!Array.isArray(item.notes)) item.notes = [];
-  item.notes.push({ timestamp: nowIso(), text: CLOSE_NOTE_TEXT });
-}
-
-/**
- * Validate a placement option ({ kind, anchor } where anchor is a path).
- * Returns the resolved anchor item and the kind.
- */
-function resolvePlacement(store, placement, commandName) {
+function resolvePlacement(snapshot, placement, commandName) {
   if (!placement) return null;
   const { kind, anchor } = placement;
   if (!kind || !anchor) {
@@ -671,229 +623,352 @@ function resolvePlacement(store, placement, commandName) {
   if (kind !== 'before' && kind !== 'after' && kind !== 'into') {
     usage('placement-invalid', `${commandName}: unknown placement kind '${kind}'`);
   }
-  const anchorItem = resolvePath(store, anchor);
+  const anchorItem = resolvePath(snapshot, anchor);
   return { kind, anchor: anchorItem };
 }
 
-// ── Verb implementations ─────────────────────────────────────────────────────
+/** Compute (parentKey, position) for a placement spec against the current snapshot. */
+function placementToTarget(snapshot, placement) {
+  const { kind, anchor } = placement;
+  if (kind === 'into') {
+    return { parentKey: anchor.key, position: 'end' };
+  }
+  const siblings = _childrenOf(snapshot.items, anchor.parentKey ?? null);
+  const idx = siblings.findIndex((s) => s.key === anchor.key);
+  return {
+    parentKey: anchor.parentKey ?? null,
+    position: kind === 'before' ? idx : idx + 1,
+  };
+}
+
+/** Snapshot the noggin's live state into a doc-shaped {items, active} object. */
+function nogginSnapshot(noggin) {
+  return {
+    items: noggin.items,
+    active: noggin.active ? noggin.active.key : null,
+  };
+}
+
+// ── Atomic ops ───────────────────────────────────────────────────────────────
 
 /**
- * push: create a child of active (or a root if none) and become active.
+ * Apply a list of `AtomicOp`s to a NogginDocument in-place, then
+ * validate the result. Throws `NogginError` if any op references a
+ * missing item or the resulting document violates invariants.
+ *
+ * Op vocabulary:
+ *   { type: 'add',       item, parentKey, position }
+ *   { type: 'remove',    keys }
+ *   { type: 'set',       key, patch: { title?, done? } }
+ *   { type: 'note',      key, note: { timestamp, text } }
+ *   { type: 'move',      key, parentKey, position }
+ *   { type: 'setActive', key }
+ *
+ * `position` is the 0-based index among siblings of `parentKey`, or
+ * the string 'end' for append.
+ *
+ * This is the single mutation primitive every backend's `apply()`
+ * delegates to. Verbs build the op list; backends execute it.
  */
-export function apiPush(file, opts) {
-  const title = (opts && opts.title || '').toString().trim();
-  if (!title) usage('title-required', 'push: title required (--title or positional)');
-  const store = loadStore(file);
-  const activeItem = findByKey(store.items, store.active);
-  const item = makeItem({ title, parentKey: activeItem ? activeItem.key : null });
-  store.items.push(item);
-  store.active = item.key;
-  saveStore(file, store);
-  return buildView(store, item);
+export function applyOps(doc, ops) {
+  if (!Array.isArray(ops)) usage('invalid-op', 'applyOps: ops must be an array');
+  for (const op of ops) applyOp(doc, op);
+  validateDocument(doc);
+  return doc;
+}
+
+function applyOp(doc, op) {
+  if (!op || typeof op !== 'object') usage('invalid-op', 'applyOps: op must be an object');
+  switch (op.type) {
+    case 'add':       return opAdd(doc, op);
+    case 'remove':    return opRemove(doc, op);
+    case 'set':       return opSet(doc, op);
+    case 'note':      return opNote(doc, op);
+    case 'move':      return opMove(doc, op);
+    case 'setActive': return opSetActive(doc, op);
+    default: usage('invalid-op', `applyOps: unknown op type '${op && op.type}'`);
+  }
 }
 
+function insertAtPosition(items, item, parentKey, position) {
+  const pkey = parentKey ?? null;
+  if (position === 'end') {
+    items.push(item);
+    return;
+  }
+  if (typeof position !== 'number' || position < 0) {
+    usage('invalid-op', `add/move: invalid position ${JSON.stringify(position)}`);
+  }
+  const siblings = items.filter((i) => (i.parentKey ?? null) === pkey);
+  if (position >= siblings.length) {
+    if (siblings.length === 0) { items.push(item); return; }
+    const last = siblings[siblings.length - 1];
+    items.splice(items.indexOf(last) + 1, 0, item);
+    return;
+  }
+  const before = siblings[position];
+  items.splice(items.indexOf(before), 0, item);
+}
+
+function opAdd(doc, op) {
+  if (!op.item || !op.item.key) usage('invalid-op', 'add: op.item with key required');
+  if (doc.items.some((i) => i.key === op.item.key)) {
+    usage('invalid-op', `add: item with key '${op.item.key}' already exists`);
+  }
+  const item = {
+    key: op.item.key,
+    parentKey: op.parentKey ?? null,
+    title: op.item.title,
+    done: Boolean(op.item.done),
+    createdAt: op.item.createdAt,
+    notes: Array.isArray(op.item.notes) ? op.item.notes.map(normalizeNote) : [],
+  };
+  insertAtPosition(doc.items, item, op.parentKey, op.position);
+}
+
+function opRemove(doc, op) {
+  if (!Array.isArray(op.keys)) usage('invalid-op', 'remove: op.keys array required');
+  const removeSet = new Set(op.keys);
+  doc.items = doc.items.filter((i) => !removeSet.has(i.key));
+}
+
+function opSet(doc, op) {
+  if (!op.key) usage('invalid-op', 'set: op.key required');
+  const item = doc.items.find((i) => i.key === op.key);
+  if (!item) usage('invalid-op', `set: item with key '${op.key}' not found`);
+  if (!op.patch || typeof op.patch !== 'object') usage('invalid-op', 'set: op.patch object required');
+  if (op.patch.title !== undefined) item.title = op.patch.title;
+  if (op.patch.done !== undefined) item.done = Boolean(op.patch.done);
+}
+
+function opNote(doc, op) {
+  if (!op.key) usage('invalid-op', 'note: op.key required');
+  const item = doc.items.find((i) => i.key === op.key);
+  if (!item) usage('invalid-op', `note: item with key '${op.key}' not found`);
+  if (!op.note || op.note.text === undefined) usage('invalid-op', 'note: op.note.text required');
+  if (!Array.isArray(item.notes)) item.notes = [];
+  item.notes.push(normalizeNote(op.note));
+}
+
+function opMove(doc, op) {
+  if (!op.key) usage('invalid-op', 'move: op.key required');
+  const item = doc.items.find((i) => i.key === op.key);
+  if (!item) usage('invalid-op', `move: item with key '${op.key}' not found`);
+  const idx = doc.items.indexOf(item);
+  doc.items.splice(idx, 1);
+  item.parentKey = op.parentKey ?? null;
+  insertAtPosition(doc.items, item, op.parentKey, op.position);
+}
+
+function opSetActive(doc, op) {
+  doc.active = op.key ?? null;
+}
+
+/**
+ * Apply ops to a clone of the current state without persisting, so a
+ * verb can resolve a `--goto` path against the projected post-apply
+ * state before submitting the real apply.
+ */
+function projectOps(noggin, ops) {
+  const doc = {
+    schemaVersion: SCHEMA_VERSION,
+    active: noggin.active ? noggin.active.key : null,
+    items: noggin.items.map((i) => ({
+      key: i.key,
+      parentKey: i.parentKey ?? null,
+      title: i.title,
+      done: Boolean(i.done),
+      createdAt: i.createdAt,
+      notes: (i.notes || []).map((n) => ({ timestamp: n.timestamp, text: n.text })),
+    })),
+  };
+  for (const op of ops) applyOp(doc, op);
+  return doc;
+}
+
+// ── Verbs ────────────────────────────────────────────────────────────────────
+
 /**
- * add: create an item. With no placement, becomes a child of active (or root).
- * Placement flags (`{ kind: 'before'|'after'|'into', anchor: path }`) override.
- * Active is unchanged unless `goto` is supplied.
+ * The single verb implementation, shared by every backend. Each verb
+ * takes a `Noggin`, reads state via its accessors, composes the
+ * appropriate `AtomicOp[]`, calls `noggin.apply(ops)` once, and returns
+ * a `CurrentTreeView` (or a `DeleteResult` for delete).
+ *
+ * Verb behavior contracts — push moves active; add does not unless
+ * --goto; done appends a close note and surfaces to parent; --force
+ * vs --close-all close semantics; cycle protection on move; etc. —
+ * live here. Backends do not implement verbs.
  */
-export function apiAdd(file, opts = {}) {
+export const verbs = {
+  push: verbPush,
+  add: verbAdd,
+  move: verbMove,
+  goto: verbGoto,
+  done: verbDone,
+  pop: verbPop,
+  edit: verbEdit,
+  show: verbShow,
+  note: verbNote,
+  delete: verbDelete,
+  copy: verbCopy,
+};
+
+/** push: create a child of active (or a root if none) and become active. */
+async function verbPush(noggin, opts, ctx) {
+  const title = (opts && opts.title || '').toString().trim();
+  if (!title) usage('title-required', 'push: title required (--title or positional)');
+  const active = noggin.active;
+  const item = makeItem({ title, parentKey: active ? active.key : null }, ctx);
+  const ops = [
+    { type: 'add', item, parentKey: active ? active.key : null, position: 'end' },
+    { type: 'setActive', key: item.key },
+  ];
+  await noggin.apply(ops);
+  return buildView(nogginSnapshot(noggin), noggin.findByKey(item.key), {});
+}
+
+/** add: capture an item without making it active (unless --goto). */
+async function verbAdd(noggin, opts = {}, ctx) {
   const title = (opts.title || '').toString().trim();
   if (!title) usage('title-required', 'add: title required (--title or positional)');
-  const store = loadStore(file);
-  const activeItem = findByKey(store.items, store.active);
-  const placement = resolvePlacement(store, opts.placement, 'add');
+  const snap = nogginSnapshot(noggin);
+  const active = noggin.active;
+  const placement = resolvePlacement(snap, opts.placement, 'add');
 
-  let parentKey;
-  let insertIndex;
+  let parentKey, position;
   if (placement) {
-    const { kind, anchor } = placement;
-    if (kind === 'into') {
-      parentKey = anchor.key;
-      insertIndex = store.items.length;
-    } else {
-      parentKey = anchor.parentKey;
-      const anchorIdx = store.items.indexOf(anchor);
-      insertIndex = kind === 'before' ? anchorIdx : anchorIdx + 1;
-    }
+    ({ parentKey, position } = placementToTarget(snap, placement));
   } else {
-    parentKey = activeItem ? activeItem.key : null;
-    insertIndex = store.items.length;
+    parentKey = active ? active.key : null;
+    position = 'end';
+  }
+
+  const item = makeItem({ title, parentKey }, ctx);
+  const ops = [{ type: 'add', item, parentKey, position }];
+
+  let viewTargetKey = item.key;
+  if (opts.goto !== undefined) {
+    const projected = projectOps(noggin, ops);
+    const projectedNew = findByKey(projected.items, item.key);
+    const target = executeGotoOption(projected, projectedNew, opts.goto, 'add');
+    ops.push({ type: 'setActive', key: target.key });
+    viewTargetKey = target.key;
   }
 
-  const item = makeItem({ title, parentKey });
-  store.items.splice(insertIndex, 0, item);
-  const outputTarget = opts.goto !== undefined ? applyGoto(store, item, opts.goto, 'add') : item;
-  saveStore(file, store);
-  return buildView(store, outputTarget);
+  await noggin.apply(ops);
+  return buildView(nogginSnapshot(noggin), noggin.findByKey(viewTargetKey), {});
 }
 
-/**
- * move: relocate an item. Default target = active. Placement is required.
- * Active pointer is preserved by key; cycles are rejected.
- */
-export function apiMove(file, opts = {}) {
-  const store = loadStore(file);
-  const placement = resolvePlacement(store, opts.placement, 'move');
+/** move: relocate an item. Required placement; cycle-checked. */
+async function verbMove(noggin, opts = {}) {
+  const snap = nogginSnapshot(noggin);
+  const placement = resolvePlacement(snap, opts.placement, 'move');
   if (!placement) usage('placement-missing', 'move: choose exactly one of --before, --after, or --into');
   const { kind, anchor } = placement;
 
   let target;
-  if (opts.path) target = resolvePath(store, opts.path);
+  if (opts.path) target = noggin.resolvePath(opts.path);
   else {
-    target = findByKey(store.items, store.active);
+    target = noggin.active;
     if (!target) runtime('no-active-item', 'move: no active item; pass a path');
   }
 
+  // Cycle checks.
   if (kind === 'into') {
     if (target.key === anchor.key) {
-      runtime('cycle', `move: cannot move ${_pathOf(store.items, target)} into itself (would create a cycle)`);
+      runtime('cycle', `move: cannot move ${noggin.pathOf(target)} into itself (would create a cycle)`);
     }
-    if (isDescendant(store.items, anchor, target)) {
-      runtime('cycle', `move: cannot move ${_pathOf(store.items, target)} into its own subtree (would create a cycle)`);
+    if (isDescendant(noggin.items, anchor, target)) {
+      runtime('cycle', `move: cannot move ${noggin.pathOf(target)} into its own subtree (would create a cycle)`);
     }
   } else {
-    if (isDescendant(store.items, anchor, target)) {
-      runtime('cycle', `move: cannot move ${_pathOf(store.items, target)} next to its own descendant (would create a cycle)`);
-    }
-    if (anchor.key === target.key) {
-      // before/after self: same place. Silent no-op.
-      const activeItem = findByKey(store.items, store.active);
-      const outputTarget = opts.goto !== undefined ? applyGoto(store, target, opts.goto, 'move') : (activeItem || target);
-      saveStore(file, store);
-      return buildView(store, outputTarget);
+    if (isDescendant(noggin.items, anchor, target)) {
+      runtime('cycle', `move: cannot move ${noggin.pathOf(target)} next to its own descendant (would create a cycle)`);
     }
   }
 
-  const newParentKey = kind === 'into' ? anchor.key : anchor.parentKey;
-  const targetIdx = store.items.indexOf(target);
-  store.items.splice(targetIdx, 1);
-
-  let insertIndex;
+  // Compute new parentKey + position. For before/after we exclude the
+  // target itself from the sibling list so its current position doesn't
+  // shift the anchor index.
+  let parentKey, position;
   if (kind === 'into') {
-    insertIndex = store.items.length;
+    parentKey = anchor.key;
+    position = 'end';
+  } else if (anchor.key === target.key) {
+    // before/after self → silent no-op. Submit a redundant move op
+    // anyway so the verb still goes through the normal apply path
+    // (keeps event semantics consistent).
+    parentKey = target.parentKey ?? null;
+    const siblings = _childrenOf(noggin.items, parentKey);
+    position = siblings.findIndex((s) => s.key === target.key);
   } else {
-    const anchorIdx = store.items.indexOf(anchor);
-    insertIndex = kind === 'before' ? anchorIdx : anchorIdx + 1;
+    parentKey = anchor.parentKey ?? null;
+    const siblings = _childrenOf(noggin.items, parentKey).filter((s) => s.key !== target.key);
+    const anchorIdx = siblings.findIndex((s) => s.key === anchor.key);
+    position = kind === 'before' ? anchorIdx : anchorIdx + 1;
   }
 
-  target.parentKey = newParentKey;
-  store.items.splice(insertIndex, 0, target);
+  const ops = [{ type: 'move', key: target.key, parentKey, position }];
 
-  const activeItem = findByKey(store.items, store.active);
-  const outputTarget = opts.goto !== undefined ? applyGoto(store, target, opts.goto, 'move') : (activeItem || target);
-  saveStore(file, store);
-  return buildView(store, outputTarget);
-}
+  let viewTargetKey;
+  if (opts.goto !== undefined) {
+    const projected = projectOps(noggin, ops);
+    const projectedTarget = findByKey(projected.items, target.key);
+    const gotoTarget = executeGotoOption(projected, projectedTarget, opts.goto, 'move');
+    ops.push({ type: 'setActive', key: gotoTarget.key });
+    viewTargetKey = gotoTarget.key;
+  } else {
+    // Default view target: active (preserved by key) if still exists, else the moved target.
+    viewTargetKey = noggin.active ? noggin.active.key : target.key;
+  }
 
-/** goto: make the item at `path` active. */
-export function apiGoto(file, opts = {}) {
-  if (!opts.path) usage('path-required', 'goto: path required');
-  const store = loadStore(file);
-  const target = resolvePath(store, opts.path);
-  store.active = target.key;
-  saveStore(file, store);
-  return buildView(store, target);
+  await noggin.apply(ops);
+  return buildView(nogginSnapshot(noggin), noggin.findByKey(viewTargetKey), {});
 }
 
-/**
- * Close `target` (and optionally its open descendants), enforcing the
- * open-descendant rule unless `force` or `closeAll` opts it out. Shared
- * by `apiDone`/`apiPop`/`apiEdit`. Mutates `store` in place; idempotent
- * when `target` is already done.
- *
- *   force      skip the open-descendant check; close just the target
- *              even though some kids remain open
- *   closeAll   walk descendants first; close every open one (each
- *              gets its own system "closed" note)
- *
- * Throws a runtime NogginError with code `open-descendants` if there
- * are open descendants and neither flag is set.
- */
-function closeWithRules(store, target, opts, verb) {
-  const force = opts.force === true;
-  const closeAll = opts.closeAll === true;
-  if (closeAll) {
-    for (const d of collectDescendants(store.items, target)) {
-      if (!d.done) {
-        d.done = true;
-        appendCloseNote(d);
-      }
-    }
-  }
-  if (!force && !closeAll) {
-    const open = countOpenDescendants(store.items, target);
-    if (open > 0) {
-      runtime(
-        'open-descendants',
-        `${verb}: ${_pathOf(store.items, target)} has ${open} open descendant(s); ` +
-          `pass --closeall to close them too, or --force to close ${target.title} anyway`,
-      );
-    }
-  }
-  if (!target.done) {
-    target.done = true;
-    appendCloseNote(target);
-  }
+/** goto: make `path` active. */
+async function verbGoto(noggin, opts = {}) {
+  if (!opts.path) usage('path-required', 'goto: path required');
+  const target = noggin.resolvePath(opts.path);
+  const ops = [{ type: 'setActive', key: target.key }];
+  await noggin.apply(ops);
+  return buildView(nogginSnapshot(noggin), noggin.findByKey(target.key), {});
 }
 
-/**
- * done: mark an item done, then move active to the target's parent.
- *
- * Idempotent — if the target is already done, no error and no extra
- * close note; the navigational side-effect (surface to parent) still
- * happens.
- *
- * `--force` skips the open-descendant safety check; `--closeall` first
- * closes every open descendant. Without either flag, an open
- * descendant blocks the call with a runtime error.
- */
-export function apiDone(file, opts = {}) {
+/** done: mark target done, then surface active to parent. Idempotent. */
+async function verbDone(noggin, opts = {}, ctx) {
   if (opts.goto !== undefined) usage('goto-unsupported', 'done: --goto is not supported; done always moves to the target parent');
-  const store = loadStore(file);
+
   let target;
-  if (opts.path) target = resolvePath(store, opts.path);
+  if (opts.path) target = noggin.resolvePath(opts.path);
   else {
-    target = findByKey(store.items, store.active);
+    target = noggin.active;
     if (!target) runtime('no-active-item', 'done: no active item; pass a path');
   }
-  closeWithRules(store, target, opts, 'done');
-  const parent = target.parentKey ? findByKey(store.items, target.parentKey) : null;
-  store.active = parent ? parent.key : null;
-  saveStore(file, store);
-  return buildView(store, parent || target);
+
+  const closeOps = buildCloseOps(noggin, target, opts, 'done', ctx);
+  const parentKey = target.parentKey ?? null;
+  const ops = [...closeOps, { type: 'setActive', key: parentKey }];
+
+  await noggin.apply(ops);
+  const newActive = noggin.active;
+  const viewTarget = newActive || noggin.findByKey(target.key);
+  return buildView(nogginSnapshot(noggin), viewTarget, {});
 }
 
-/** pop: shorthand for done() on the active item. Honors --force / --closeall. */
-export function apiPop(file, opts = {}) {
+/** pop: done on active, no path argument. */
+async function verbPop(noggin, opts = {}, ctx) {
   if (opts && opts.path !== undefined) usage('pop-no-path', 'pop: takes no path; pop always operates on the active item');
-  if (opts && opts.goto !== undefined) usage('goto-unsupported', 'pop: --goto is not supported; pop always moves to the active item\'s parent');
-  const store = loadStore(file);
-  if (!findByKey(store.items, store.active)) runtime('no-active-item', 'pop: no active item');
-  return apiDone(file, {
+  if (opts && opts.goto !== undefined) usage('goto-unsupported', "pop: --goto is not supported; pop always moves to the active item's parent");
+  if (!noggin.active) runtime('no-active-item', 'pop: no active item');
+  return verbDone(noggin, {
     force: opts.force === true,
     closeAll: opts.closeAll === true,
-  });
+  }, ctx);
 }
 
-/**
- * edit: explicitly mutate one item's lifecycle state and/or title. Combines
- * the old `set-state` and `retitle` verbs. At least one of `done`/`title`
- * is required. Each operation is idempotent (no error if the value already
- * matches).
- *
- *   done       true  → close (subject to open-descendant rules below)
- *              false → reopen
- *              undefined → don't touch state
- *   title      new title (trimmed; empty string is ignored, not an error)
- *   force      when closing, skip the open-descendant check
- *   closeAll   when closing, first close every open descendant
- *   goto       standard reposition-after-write option
- *
- * Unlike `done`, `edit --done` does NOT surface active to the parent;
- * active is unchanged unless `--goto` is passed.
- */
-export function apiEdit(file, opts = {}) {
+/** edit: idempotent mutation of state and/or title. */
+async function verbEdit(noggin, opts = {}, ctx) {
   const hasState = typeof opts.done === 'boolean';
   const rawTitle = opts.title;
   const hasTitle = typeof rawTitle === 'string' && rawTitle.trim() !== '';
@@ -908,293 +983,335 @@ export function apiEdit(file, opts = {}) {
     usage('option-misused', 'edit: --close-all only applies when closing (with --done)');
   }
 
-  const store = loadStore(file);
   let target;
-  if (opts.path) target = resolvePath(store, opts.path);
+  if (opts.path) target = noggin.resolvePath(opts.path);
   else {
-    target = findByKey(store.items, store.active);
+    target = noggin.active;
     if (!target) runtime('no-active-item', 'edit: no active item; pass a path');
   }
 
+  const ops = [];
+
   if (hasState) {
     if (opts.done) {
-      closeWithRules(store, target, opts, 'edit');
+      ops.push(...buildCloseOps(noggin, target, opts, 'edit', ctx));
     } else if (target.done) {
-      target.done = false;
+      ops.push({ type: 'set', key: target.key, patch: { done: false } });
     }
   }
 
   if (hasTitle) {
     const next = rawTitle.toString().trim();
-    if (target.title !== next) target.title = next;
+    if (target.title !== next) {
+      ops.push({ type: 'set', key: target.key, patch: { title: next } });
+    }
   }
 
-  const outputTarget = opts.goto !== undefined ? applyGoto(store, target, opts.goto, 'edit') : target;
-  saveStore(file, store);
-  return buildView(store, outputTarget);
+  let viewTargetKey = target.key;
+  if (opts.goto !== undefined) {
+    const projected = projectOps(noggin, ops);
+    const projectedTarget = findByKey(projected.items, target.key);
+    const gotoTarget = executeGotoOption(projected, projectedTarget, opts.goto, 'edit');
+    ops.push({ type: 'setActive', key: gotoTarget.key });
+    viewTargetKey = gotoTarget.key;
+  }
+
+  if (ops.length > 0) await noggin.apply(ops);
+  return buildView(nogginSnapshot(noggin), noggin.findByKey(viewTargetKey), {});
 }
 
-/**
- * show: detail for one item plus first-level children. Default target = active.
- * Returns null if no target can be resolved (no active item, no path given).
- */
-export function apiShow(file, opts = {}) {
-  const store = loadStore(file);
-  const target = opts.path
-    ? resolvePath(store, opts.path)
-    : findByKey(store.items, store.active);
+/** show: read-only view; --goto activates after. */
+async function verbShow(noggin, opts = {}) {
+  const target = opts.path ? noggin.resolvePath(opts.path) : noggin.active;
   if (!target) return null;
-  const outputTarget = opts.goto !== undefined ? applyGoto(store, target, opts.goto, 'show') : target;
-  if (opts.goto !== undefined) saveStore(file, store);
-  return buildView(store, outputTarget, {
+
+  let viewTargetKey = target.key;
+  if (opts.goto !== undefined) {
+    const gotoTarget = executeGotoOption(nogginSnapshot(noggin), target, opts.goto, 'show');
+    if (gotoTarget.key !== (noggin.active ? noggin.active.key : null)) {
+      await noggin.apply([{ type: 'setActive', key: gotoTarget.key }]);
+    }
+    viewTargetKey = gotoTarget.key;
+  }
+
+  return buildView(nogginSnapshot(noggin), noggin.findByKey(viewTargetKey), {
     includeChildren: opts.includeChildren !== false,
     withSiblings: opts.withSiblings === true,
     withDescendants: opts.withDescendants === true,
   });
 }
 
-/** note: append a timestamped note. Path defaults to active. */
-export function apiNote(file, opts = {}) {
+/** note: append a timestamped note. */
+async function verbNote(noggin, opts = {}, ctx) {
   const text = (opts.text || '').toString().trim();
   if (!text) usage('text-required', 'note: text required');
-  const store = loadStore(file);
+
   let target;
-  if (opts.path) target = resolvePath(store, opts.path);
+  if (opts.path) target = noggin.resolvePath(opts.path);
   else {
-    target = findByKey(store.items, store.active);
+    target = noggin.active;
     if (!target) runtime('no-active-item', 'note: no active item and no path given');
   }
-  if (!Array.isArray(target.notes)) target.notes = [];
-  target.notes.push({ timestamp: nowIso(), text });
-  const outputTarget = opts.goto !== undefined ? applyGoto(store, target, opts.goto, 'note') : target;
-  saveStore(file, store);
-  return buildView(store, outputTarget);
+
+  const ops = [{
+    type: 'note',
+    key: target.key,
+    note: { timestamp: nowIso(ctx), text },
+  }];
+
+  let viewTargetKey = target.key;
+  if (opts.goto !== undefined) {
+    const projected = projectOps(noggin, ops);
+    const projectedTarget = findByKey(projected.items, target.key);
+    const gotoTarget = executeGotoOption(projected, projectedTarget, opts.goto, 'note');
+    ops.push({ type: 'setActive', key: gotoTarget.key });
+    viewTargetKey = gotoTarget.key;
+  }
+
+  await noggin.apply(ops);
+  return buildView(nogginSnapshot(noggin), noggin.findByKey(viewTargetKey), {});
 }
 
-/**
- * delete: remove an item. Refuses if it has descendants unless `recursive`.
- * If the deleted subtree contains the active item, active becomes the
- * deleted item's parent (or null if it was a root).
- */
-export function apiDelete(file, opts = {}) {
+/** delete: remove item; --recursive for subtree. */
+async function verbDelete(noggin, opts = {}) {
   if (opts.goto !== undefined) usage('goto-unsupported', 'delete: --goto is not supported');
   if (!opts.path) usage('path-required', 'delete: path required');
-  const store = loadStore(file);
-  const target = resolvePath(store, opts.path);
-  const targetPath = _pathOf(store.items, target);
+  const target = noggin.resolvePath(opts.path);
   const targetKey = target.key;
+  const targetPath = noggin.pathOf(target);
   const targetTitle = target.title;
-  const descendants = collectDescendants(store.items, target);
+  const descendants = collectDescendants(noggin.items, target);
+
   if (descendants.length > 0 && opts.recursive !== true) {
     runtime(
       'has-descendants',
-      `delete: ${targetPath} has ${descendants.length} descendant(s); ` +
-        `pass --recursive to delete the whole subtree`,
+      `delete: ${targetPath} has ${descendants.length} descendant(s); pass --recursive to delete the whole subtree`,
     );
   }
-  const removeKeys = new Set([target.key, ...descendants.map((d) => d.key)]);
-  const activeWasRemoved = store.active != null && removeKeys.has(store.active);
-  store.items = store.items.filter((i) => !removeKeys.has(i.key));
+
+  const removeKeys = [target.key, ...descendants.map((d) => d.key)];
+  const ops = [{ type: 'remove', keys: removeKeys }];
+
+  const activeWasRemoved = noggin.active != null && removeKeys.includes(noggin.active.key);
   if (activeWasRemoved) {
-    store.active = target.parentKey || null;
+    ops.push({ type: 'setActive', key: target.parentKey ?? null });
   }
-  saveStore(file, store);
-  const newActive = findByKey(store.items, store.active);
+
+  await noggin.apply(ops);
+
+  const newActive = noggin.active;
   return {
     deleted: { key: targetKey, path: targetPath, title: targetTitle },
     descendantCount: descendants.length,
-    view: newActive ? buildView(store, newActive) : null,
+    view: newActive ? buildView(nogginSnapshot(noggin), newActive, {}) : null,
   };
 }
 
-/** where: returns the resolved file info for the current options. */
-export function apiWhere(opts = {}) {
-  return resolveFile(opts);
-}
-
-// ── Noggin class ─────────────────────────────────────────────────────────────
-
 /**
- * Long-lived handle over a single noggin file. Caches the parsed store in
- * memory, watches the file for external edits, and fires onDidChange when
- * the store changes (via a verb method or an external edit).
+ * copy: append every item from `source` into `dest`, preserving tree
+ * structure but generating fresh keys.
  *
- * Read accessors are cheap. Verbs reload from disk before mutating so they
- * see any external edits, then write atomically and refresh the cache.
+ * v1 semantics (intentionally narrow; extension points reserved for
+ * future versions):
+ *   - whole-noggin copy: every source item is copied; source paths/keys
+ *     are not selectable
+ *   - append-only: source roots become new roots at the end of dest's
+ *     root list, never overwriting existing dest content
+ *   - active is not transferred: dest's active pointer is unchanged
+ *   - notes (including system "closed" notes), `done`, and `createdAt`
+ *     are preserved verbatim — a copied item looks like the original
+ *     work, just under a different location
+ *   - same-noggin copy (source === dest) is supported: the entire
+ *     tree gets duplicated at the root with fresh keys
+ *
+ * Returns `{ copied, mapping }` where `mapping` is a `{oldKey: newKey}`
+ * dictionary the caller can use to find the dest counterpart of any
+ * source item.
  */
-export class Noggin {
-  /**
-   * @param {string} file Absolute path to the noggin YAML file.
-   * @param {{ watch?: boolean }} [opts]
-   */
-  constructor(file, opts = {}) {
-    if (!file) throw new NogginError('Noggin: file path required', { code: 'no-file', exitCode: 2 });
-    this.file = file;
-    /** @type {any} */
-    this._store = emptyStore();
-    /** @type {Set<() => void>} */
-    this._changeListeners = new Set();
-    /** @type {Set<(err: NogginError) => void>} */
-    this._errorListeners = new Set();
-    this._watcher = null;
-    this._reloadTimer = null;
-    this._disposed = false;
-
-    // Bind so they look like vscode.Event<T>: function-shaped subscribe.
-    this.onDidChange = (handler) => {
-      this._changeListeners.add(handler);
-      return { dispose: () => this._changeListeners.delete(handler) };
-    };
-    this.onDidError = (handler) => {
-      this._errorListeners.add(handler);
-      return { dispose: () => this._errorListeners.delete(handler) };
-    };
+async function verbCopy(source, dest, opts = {}, ctx) {
+  if (!source || typeof source.apply !== 'function') usage('source-required', 'copy: source noggin required');
+  if (!dest || typeof dest.apply !== 'function') usage('dest-required', 'copy: dest noggin required');
+
+  // Snapshot the source up-front. If source === dest, this freezes the
+  // view we're copying from before any add ops mutate dest.
+  const srcItems = source.items.map((it) => ({
+    key: it.key,
+    parentKey: it.parentKey ?? null,
+    title: it.title,
+    done: Boolean(it.done),
+    createdAt: it.createdAt,
+    notes: (it.notes || []).map((n) => ({ timestamp: n.timestamp, text: n.text })),
+  }));
+
+  if (srcItems.length === 0) {
+    return { copied: 0, mapping: {} };
+  }
 
-    // Best-effort initial load. A bad file surfaces as onDidError but the
-    // instance still works (the cache stays empty until reload succeeds).
-    try { this._store = freezeStore(loadStore(file)); }
-    catch (e) {
-      if (e instanceof NogginError) this._fireError(e);
-      else throw e;
+  // Walk source as a tree (roots first, depth-first) so every parent
+  // appears in the op list before its children. The flat items array
+  // isn't guaranteed to be in topo order; the recursive walk is.
+  const childrenByParent = new Map();
+  for (const it of srcItems) {
+    const parent = it.parentKey ?? null;
+    if (!childrenByParent.has(parent)) childrenByParent.set(parent, []);
+    childrenByParent.get(parent).push(it);
+  }
+  const ordered = [];
+  function walk(parentKey) {
+    const kids = childrenByParent.get(parentKey) || [];
+    for (const kid of kids) {
+      ordered.push(kid);
+      walk(kid.key);
     }
-
-    if (opts.watch) this._startWatch();
   }
+  walk(null);
+
+  // Allocate new keys for every source item.
+  const mapping = Object.create(null);
+  for (const it of ordered) mapping[it.key] = newKey();
+
+  // Build add ops in topo order. Source roots (parentKey === null)
+  // become new roots in dest at position 'end' — appended after any
+  // existing dest content. Every other item lands under its (already
+  // added) parent.
+  const ops = ordered.map((it) => {
+    const newParentKey = it.parentKey ? mapping[it.parentKey] : null;
+    return {
+      type: 'add',
+      item: {
+        key: mapping[it.key],
+        parentKey: newParentKey,
+        title: it.title,
+        done: it.done,
+        createdAt: it.createdAt,
+        notes: it.notes,
+      },
+      parentKey: newParentKey,
+      position: 'end',
+    };
+  });
 
-  // ── Read accessors ──────────────────────────────────────────────────
-  get store() { return this._store; }
-  get active() { return this._store.active ? findByKey(this._store.items, this._store.active) : null; }
-  get roots() { return _childrenOf(this._store.items, null); }
+  await dest.apply(ops);
 
-  findByKey(key) { return findByKey(this._store.items, key); }
-  childrenOf(parentKey) { return _childrenOf(this._store.items, parentKey || null); }
-  pathOf(item) { return _pathOf(this._store.items, item); }
-  resolvePath(p) { return resolvePath(this._store, p); }
-  tryResolvePath(p) { return tryResolvePath(this._store, p); }
+  return { copied: ordered.length, mapping };
+}
 
-  /**
-   * Build a CurrentTreeView. Target may be an item, a path string, or null
-   * (defaults to the active item). Returns null if no target is found.
-   */
-  view(target, opts = {}) {
-    let item = null;
-    if (target == null) item = this.active;
-    else if (typeof target === 'string') item = this.tryResolvePath(target);
-    else item = target;
-    if (!item) return null;
-    return buildView(this._store, item, opts);
-  }
-
-  // ── Lifecycle ───────────────────────────────────────────────────────
-
-  /** Reload from disk. Returns true if the cached store actually changed. */
-  reload() {
-    const prev = this._store;
-    let next;
-    try { next = loadStore(this.file); }
-    catch (e) {
-      if (e instanceof NogginError) { this._fireError(e); return false; }
-      throw e;
-    }
-    if (storesEqual(prev, next)) return false;
-    this._store = freezeStore(next);
-    this._fireChange();
-    return true;
-  }
-
-  dispose() {
-    if (this._disposed) return;
-    this._disposed = true;
-    if (this._reloadTimer) { clearTimeout(this._reloadTimer); this._reloadTimer = null; }
-    if (this._watcher) { try { this._watcher.close(); } catch { /* ignore */ } this._watcher = null; }
-    this._changeListeners.clear();
-    this._errorListeners.clear();
-  }
-
-  // ── Verbs ───────────────────────────────────────────────────────────
-  push(opts) { return this._run(apiPush, opts); }
-  add(opts) { return this._run(apiAdd, opts); }
-  move(opts) { return this._run(apiMove, opts); }
-  goto(p) { return this._run(apiGoto, { path: p }); }
-  done(opts) { return this._run(apiDone, opts); }
-  pop(opts) { return this._run(apiPop, opts || {}); }
-  edit(opts) { return this._run(apiEdit, opts); }
-  show(opts) { return this._runRead(apiShow, opts); }
-  note(opts) { return this._run(apiNote, opts); }
-  delete(opts) { return this._run(apiDelete, opts); }
-  where() { return resolveFile({ file: this.file }); }
-
-  // ── Internals ───────────────────────────────────────────────────────
-
-  _run(fn, opts) {
-    const result = fn(this.file, opts || {});
-    // Refresh cache and notify listeners.
-    try {
-      const next = loadStore(this.file);
-      this._store = freezeStore(next);
-      this._fireChange();
-    } catch (e) {
-      if (e instanceof NogginError) this._fireError(e);
-      else throw e;
-    }
-    return result;
-  }
-
-  _runRead(fn, opts) {
-    const result = fn(this.file, opts || {});
-    // show with --goto mutates; refresh cache in that case.
-    if (opts && opts.goto !== undefined) {
-      try {
-        this._store = freezeStore(loadStore(this.file));
-        this._fireChange();
-      } catch (e) {
-        if (e instanceof NogginError) this._fireError(e);
+/**
+ * Build the op list for closing `target`, enforcing the open-descendant
+ * rule unless `force` or `closeAll` opts it out. Shared by `done`,
+ * `pop` (via done), and `edit --done`. Does NOT include the setActive
+ * op — callers add that if their verb surfaces active.
+ */
+function buildCloseOps(noggin, target, opts, verb, ctx) {
+  const force = opts.force === true;
+  const closeAll = opts.closeAll === true;
+  const ops = [];
+  const ts = nowIso(ctx);
+
+  if (closeAll) {
+    for (const d of collectDescendants(noggin.items, target)) {
+      if (!d.done) {
+        ops.push({ type: 'set', key: d.key, patch: { done: true } });
+        ops.push({ type: 'note', key: d.key, note: { timestamp: ts, text: CLOSE_NOTE_TEXT } });
       }
     }
-    return result;
   }
-
-  _fireChange() {
-    for (const h of this._changeListeners) {
-      try { h(); } catch { /* listener errors don't propagate */ }
+  if (!force && !closeAll) {
+    const open = countOpenDescendants(noggin.items, target);
+    if (open > 0) {
+      runtime(
+        'open-descendants',
+        `${verb}: ${noggin.pathOf(target)} has ${open} open descendant(s); ` +
+          `pass --closeall to close them too, or --force to close ${target.title} anyway`,
+      );
     }
   }
-
-  _fireError(err) {
-    for (const h of this._errorListeners) {
-      try { h(err); } catch { /* swallow */ }
-    }
+  if (!target.done) {
+    ops.push({ type: 'set', key: target.key, patch: { done: true } });
+    ops.push({ type: 'note', key: target.key, note: { timestamp: ts, text: CLOSE_NOTE_TEXT } });
   }
+  return ops;
+}
 
-  _startWatch() {
-    const dir = path.dirname(this.file);
-    if (!fs.existsSync(dir)) return; // can't watch a nonexistent dir; bail
-    try {
-      this._watcher = fs.watch(dir, { persistent: false }, (_event, name) => {
-        if (!name) { this._scheduleReload(); return; }
-        if (path.basename(this.file) === name) this._scheduleReload();
-      });
-    } catch { /* watching is best-effort */ }
-  }
+// ── Factory registry ─────────────────────────────────────────────────────────
 
-  _scheduleReload() {
-    if (this._reloadTimer) clearTimeout(this._reloadTimer);
-    this._reloadTimer = setTimeout(() => {
-      this._reloadTimer = null;
-      if (this._disposed) return;
-      this.reload();
-    }, 50);
-  }
+function createRegistry() {
+  /** @type {Map<string, any>} */
+  const byScheme = new Map();
+  /** @type {string|null} */
+  let defaultScheme = null;
+  return {
+    register(factory, opts = {}) {
+      if (!factory || typeof factory.scheme !== 'string' || !factory.scheme) {
+        throw new TypeError('factories.register: factory.scheme (non-empty string) required');
+      }
+      if (typeof factory.open !== 'function') {
+        throw new TypeError('factories.register: factory.open function required');
+      }
+      byScheme.set(factory.scheme, factory);
+      if (opts.default) defaultScheme = factory.scheme;
+    },
+    unregister(scheme) {
+      const had = byScheme.delete(scheme);
+      if (defaultScheme === scheme) defaultScheme = null;
+      return had;
+    },
+    get(scheme) { return byScheme.get(scheme) || null; },
+    getDefault() {
+      return defaultScheme ? byScheme.get(defaultScheme) || null : null;
+    },
+    list() {
+      return Array.from(byScheme.values()).map((f) => ({
+        scheme: f.scheme,
+        default: f.scheme === defaultScheme,
+      }));
+    },
+  };
 }
 
-/** Convenience constructor: opens a watched Noggin. */
-export function openNoggin(file) {
-  return new Noggin(file, { watch: true });
+/**
+ * The process-wide noggin factory registry. Backends call
+ * `factories.register({scheme, open})` (typically on import side-effect).
+ * `openNoggin(location)` consults this registry to pick a factory by
+ * scheme prefix; bare locations go to whichever factory was registered
+ * with `{default: true}`.
+ */
+export const factories = createRegistry();
+
+function parseLocation(s) {
+  const m = String(s == null ? '' : s).match(/^([a-z][a-z0-9+.-]*):\/\/(.*)$/i);
+  return m ? { scheme: m[1].toLowerCase(), rest: m[2] } : { scheme: null, rest: String(s == null ? '' : s) };
 }
 
-// ── Snapshot helpers ─────────────────────────────────────────────────────────
+/**
+ * Open a noggin by location. The scheme prefix (e.g. `file://`,
+ * `localstorage://`) selects the factory; a bare location goes to
+ * the default factory.
+ *
+ * @param {string} location
+ * @param {object} [opts]  Forwarded to the factory.
+ * @returns {Promise<any>}
+ */
+export async function openNoggin(location, opts) {
+  if (!location) {
+    throw new NogginError('openNoggin: location required', { code: 'no-location', exitCode: 2 });
+  }
+  const { scheme, rest } = parseLocation(location);
+  const factory = scheme ? factories.get(scheme) : factories.getDefault();
+  if (!factory) {
+    if (scheme) usage('no-factory', `no factory registered for scheme '${scheme}://'`);
+    usage('no-factory', `no default factory registered; cannot open '${location}'`);
+  }
+  // Forward the original location so backends can preserve it for
+  // round-trippable `where` output. Backends still receive `rest` (the
+  // post-scheme portion) as the resolution input.
+  return factory.open(rest, { ...opts, location });
+}
 
-function storesEqual(a, b) {
+// ── Snapshot helpers (used by backends) ──────────────────────────────────────
+
+/** Structural equality between two NogginDocuments. */
+export function documentsEqual(a, b) {
   if (a === b) return true;
   if (!a || !b) return false;
   if (a.active !== b.active) return false;
@@ -1222,15 +1339,18 @@ function itemsEqual(a, b) {
   return true;
 }
 
-function freezeStore(store) {
-  // Deep-freeze prevents consumers from mutating cached state. Items and
-  // their notes arrays are frozen; the top-level object is the snapshot.
-  for (const item of store.items) {
+/**
+ * Deep-freeze a noggin document. Backends call this on the in-memory
+ * cache that's exposed via accessors so consumers can't accidentally
+ * mutate it.
+ */
+export function freezeDocument(doc) {
+  for (const item of doc.items) {
     for (const note of item.notes || []) Object.freeze(note);
     Object.freeze(item.notes);
     Object.freeze(item);
   }
-  Object.freeze(store.items);
-  Object.freeze(store);
-  return store;
+  Object.freeze(doc.items);
+  Object.freeze(doc);
+  return doc;
 }