dreamteamer 0.6.4 → 0.7.0

package/src/schema-ops.js

@@ -10,6 +10,12 @@ import { execFileSync } from 'node:child_process';
 import { load, dump } from './yaml.js';
 import { compile, kindDir, titleCase } from './compile.js';
 import { readManifest, runtimeKindDir } from './runtime.js';
+import { normalizeNamespaces, namespaceOf, baseNameOf, qualify, defaultStoragePath } from './namespace.js';
+
+// Same rule as store.js: a git failure we CATCH must not also print git's own error on top of the
+// clean message we throw. stdout stays piped because some callers read it.
+const GIT_QUIET = ['ignore', 'pipe', 'ignore'];
+import { walk, EXT } from './records.js';
 
 // ---- the gate -------------------------------------------------------------------
 
@@ -39,10 +45,10 @@ function writeGated(ws, store, files, subject, mutate) {
 		// to record directories, so a deferred source edit would be publishable by nothing.
 		// Extending `dt commit` to module sources is the natural follow-on; it is not this wave.
 		try {
-			execFileSync('git', ['add', '--', ...rels], { cwd: ws.root });
-			execFileSync('git', ['commit', '--quiet', '-m', subject, '--', ...rels], { cwd: ws.root });
+			execFileSync('git', ['add', '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET });
+			execFileSync('git', ['commit', '--quiet', '-m', subject, '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET });
 		} catch (e) {
-			try { execFileSync('git', ['reset', '--quiet', '--', ...rels], { cwd: ws.root }); } catch { /* nothing staged */ }
+			try { execFileSync('git', ['reset', '--quiet', '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET }); } catch { /* nothing staged */ }
 			restore();
 			try { compile(ws); } catch { /* pre-op sources were compilable */ }
 			throw new Error(`git commit failed — the schema change was rolled back, nothing was changed. (${e.message.split('\n')[0]})`);
@@ -60,29 +66,46 @@ export function workspaceSystemDir(ws, kind) {
 
 // ---- ops ------------------------------------------------------------------------
 
-export function createCollection(ws, store, { name, template }) {
+export function createCollection(ws, store, { name, template, namespace }) {
 	if (!name) throw new Error('missing collection name');
-	if (store.descriptors.has(name)) throw new Error(`collection "${name}" already exists`);
-	const dest = path.join(workspaceSystemDir(ws, 'collections'), `${name}.collection.yaml`);
+	// `--namespace health --name doctors` and `--name health/doctors` are the SAME collection, because
+	// the qualified name IS the identity everywhere else in the engine. Accepting both keeps the CLI
+	// honest about that rather than making the operator learn which spelling a verb wants.
+	const declared = normalizeNamespaces(ws.pkg.dreamteamer?.namespaces);
+	const qualified = namespace ? qualify(namespace, name) : name;
+	const ns = namespaceOf(qualified, declared);
+	if (qualified.includes('/') && !ns) {
+		throw new Error(`namespace "${qualified.slice(0, qualified.lastIndexOf('/'))}" is not declared — add it to dreamteamer.namespaces in package.json first, or the collection will not compile.`);
+	}
+	if (store.descriptors.has(qualified)) throw new Error(`collection "${qualified}" already exists`);
+	// NESTED, mirroring where compile puts it in the runtime: `collections/health/doctors.collection.yaml`.
+	// compile enumerates this kind recursively for exactly this reason — and `upsertField` derives the
+	// same path from the same name, which is what keeps a later `add-field` editing the base descriptor
+	// instead of quietly creating an overlay beside it.
+	const dest = path.join(workspaceSystemDir(ws, 'collections'), `${qualified}.collection.yaml`);
 	if (fs.existsSync(dest)) throw new Error(`${path.relative(ws.root, dest)} already exists`);
 
-	let descriptor = { name };
+	let descriptor = { name: qualified };
 	if (template) {
 		const tplFile = path.join(runtimeKindDir(ws.root, 'collection-templates'), `${template}.collection-template.yaml`);
 		if (!fs.existsSync(tplFile)) throw new Error(`unknown collection-template "${template}"`);
-		descriptor = { name, ...structuredClone(load(fs.readFileSync(tplFile, 'utf8')).template) };
+		descriptor = { name: qualified, ...structuredClone(load(fs.readFileSync(tplFile, 'utf8')).template) };
 	} else {
 		// templateless: MINIMAL but compilable — grow it with add-field
 		descriptor.id = { generate: '{{ name | slug }}' };
 		descriptor.schema = { type: 'object', required: ['name'], properties: { name: { type: 'string' } } };
 	}
 	descriptor.storage = {
-		path: `${ws.pkg.dreamteamer?.['data-path'] ?? 'data'}/${name}`,
+		// AUTHORED even though compile would derive the same value, because a descriptor a human opens
+		// should say where its records live without them having to know the derivation rule.
+		path: defaultStoragePath(qualified, declared, ws.pkg.dreamteamer?.['data-path'] ?? 'data'),
 		codec: 'md', shape: 'file',
 		...descriptor.storage,
-		suffix: descriptor.storage?.suffix ?? singular(name),
+		// the SUFFIX comes off the bare name — `health/doctors` records are `<id>.doctor.md`, not
+		// `<id>.health/doctor.md`
+		suffix: descriptor.storage?.suffix ?? singular(baseNameOf(qualified, declared)),
 	};
-	writeGated(ws, store, [dest], `dreamteamer: collections add ${name}`, () => {
+	writeGated(ws, store, [dest], `dreamteamer: collections add ${qualified}`, () => {
 		fs.mkdirSync(path.dirname(dest), { recursive: true });
 		fs.writeFileSync(dest, dump(descriptor));
 	});
@@ -100,6 +123,232 @@ export function removeCollection(ws, store, name, { force = false } = {}) {
 	return { removed: name };
 }
 
+/**
+ * Rename a collection — descriptor, records, and every inbound reference, in ONE commit.
+ *
+ * This exists because namespacing EXISTING data was otherwise a hand migration: `git mv` the
+ * descriptor, edit `name` and `storage.path`, `git mv` the record folder, re-suffix every file, then
+ * find and rewrite every reference — six steps with no gate, where forgetting the last one dangles
+ * every link silently. `dt collections rename doctors health/doctors` is the whole thing.
+ *
+ * DERIVED-VS-AUTHORED is the rule for both moving parts, the same rule `createCollection` uses:
+ *  - `storage.path` moves only if it was DERIVED (equal to the default for the old name). An authored
+ *    path is a deliberate choice about where records live and a rename must not overrule it.
+ *  - `storage.suffix` is re-derived only if it was DERIVED (the singular of the old base name), because
+ *    otherwise the filenames would start lying about what they hold. `doctors` → `health/doctors` keeps
+ *    the base name, so nothing is re-suffixed — which is the common case and the cheap one.
+ *
+ * References are rewritten by asking the STORE to do it, once per record id, rather than by matching
+ * the collection prefix with a new regex. `store.rewriteRefs` already knows the boundary rules and
+ * already scopes prose to `[[wikilinks]]` (decision 7) — a fresh `oldName/` pattern would have to
+ * relearn both, and would corrupt `data/tasks/` in a path or a URL on its first outing. N passes over
+ * the record files is the price, and at human scale it is worth paying for reusing the correct code.
+ */
+export function renameCollection(ws, store, oldName, newName) {
+	const d = store.descriptor(oldName); // throws with the known-collection list if absent
+	if (!newName) throw new Error('missing new collection name');
+	if (oldName === newName) return { renamed: false, name: newName };
+
+	const declared = normalizeNamespaces(ws.pkg.dreamteamer?.namespaces);
+	if (newName.includes('/') && !namespaceOf(newName, declared)) {
+		throw new Error(`namespace "${newName.slice(0, newName.lastIndexOf('/'))}" is not declared — add it to dreamteamer.namespaces in package.json first.`);
+	}
+	if (store.descriptors.has(newName)) throw new Error(`collection "${newName}" already exists`);
+	if (d.storage.base === 'runtime') throw new Error(`"${oldName}" is a compiled source, not a data collection — it cannot be renamed`);
+
+	const src = path.join(workspaceSystemDir(ws, 'collections'), `${oldName}.collection.yaml`);
+	const dest = path.join(workspaceSystemDir(ws, 'collections'), `${newName}.collection.yaml`);
+	if (!fs.existsSync(src)) {
+		throw new Error(`"${oldName}" is not workspace-owned — it ships with a module, so rename it there (or overlay it with \`extends\`)`);
+	}
+
+	const doc = load(fs.readFileSync(src, 'utf8'));
+	const dataPath = ws.pkg.dreamteamer?.['data-path'] ?? 'data';
+	// `d` is the COMPILED descriptor, so its storage.path already carries any module prefix; the
+	// authored source is what we compare against, and what we rewrite.
+	const authoredPath = String(doc.storage?.path ?? '');
+	const pathWasDerived = authoredPath === '' || authoredPath === defaultStoragePath(oldName, declared, dataPath);
+	const newPath = pathWasDerived ? defaultStoragePath(newName, declared, dataPath) : authoredPath;
+
+	const oldBase = baseNameOf(oldName, declared);
+	const newBase = baseNameOf(newName, declared);
+	const oldSuffix = d.storage.suffix;
+	const suffixWasDerived = oldSuffix === singular(oldBase);
+	const newSuffix = suffixWasDerived ? singular(newBase) : oldSuffix;
+
+	// Every id BEFORE anything moves — the store's index is keyed on the old collection.
+	const ids = [...store.ids(oldName).keys()];
+	const oldDir = store.dir(d);
+	const newDir = path.join(ws.root, newPath);
+	if (newDir !== oldDir && fs.existsSync(newDir)) {
+		throw new Error(`${newPath} already exists on disk — move or remove it first; nothing was renamed`);
+	}
+
+	// ---- rollback state, captured before the first mutation --------------------------------------
+	const srcBytes = fs.readFileSync(src);
+	let movedData = false;
+	let resuffixed = [];
+	const undo = () => {
+		for (const [from, to] of resuffixed) { if (fs.existsSync(to)) fs.renameSync(to, from); }
+		if (movedData && fs.existsSync(newDir)) {
+			fs.mkdirSync(path.dirname(oldDir), { recursive: true });
+			fs.renameSync(newDir, oldDir);
+			pruneEmpty(path.dirname(newDir), path.join(ws.root, dataPath));
+		}
+		fs.mkdirSync(path.dirname(src), { recursive: true });
+		fs.writeFileSync(src, srcBytes);
+		if (dest !== src) fs.rmSync(dest, { force: true });
+	};
+
+	return store.withWriteLock(() => {
+		// referencing files are snapshotted by the store's own helper via rewriteRefs' touched list, so
+		// they are captured here the same way `store.rename` does it: read before, restore on failure.
+		const refFiles = new Map();
+		const captureRefs = (ref) => {
+			for (const f of store.findInboundRefs(ref)) {
+				const abs = path.join(ws.root, f);
+				if (!refFiles.has(abs)) refFiles.set(abs, fs.readFileSync(abs));
+			}
+		};
+		for (const id of ids) captureRefs(`${oldName}/${id}`);
+		captureRefs(`collections/${oldName}`);
+		const restoreRefs = () => { for (const [f, bytes] of refFiles) fs.writeFileSync(f, bytes); };
+
+		const touched = new Set();
+		let rewrites = 0;
+		try {
+			// 1. the descriptor source, at its new path
+			doc.name = newName;
+			doc.storage = { ...doc.storage, path: newPath, suffix: newSuffix };
+			fs.mkdirSync(path.dirname(dest), { recursive: true });
+			fs.writeFileSync(dest, dump(doc));
+			if (dest !== src) fs.rmSync(src);
+			touched.add(src);
+			touched.add(dest);
+
+			// 2. the record folder, then the per-file suffix if it was derived
+			if (newDir !== oldDir && fs.existsSync(oldDir)) {
+				fs.mkdirSync(path.dirname(newDir), { recursive: true });
+				fs.renameSync(oldDir, newDir);
+				movedData = true;
+				pruneEmpty(path.dirname(oldDir), path.join(ws.root, dataPath));
+			}
+			if (newSuffix !== oldSuffix && fs.existsSync(newDir)) {
+				const ext = EXT[d.storage.codec ?? 'md'];
+				for (const file of walk(newDir)) {
+					if (!file.endsWith(`.${oldSuffix}${ext}`)) continue;
+					const to = file.slice(0, -(oldSuffix.length + ext.length + 1)) + `.${newSuffix}${ext}`;
+					fs.renameSync(file, to);
+					resuffixed.push([file, to]);
+				}
+			}
+			if (movedData) { touched.add(oldDir); touched.add(newDir); }
+
+			// 3. inbound references: per record id, plus the collection's own id in `collections`
+			//    (which is what ui-views and command-bindings point at).
+			for (const id of ids) {
+				const out = store.rewriteRefs(`${oldName}/${id}`, `${newName}/${id}`);
+				rewrites += out.rewrites;
+				for (const f of out.touched) touched.add(f);
+			}
+			const collOut = store.rewriteRefs(`collections/${oldName}`, `collections/${newName}`);
+			rewrites += collOut.rewrites;
+			for (const f of collOut.touched) touched.add(f);
+
+			// 4. bare `x-reference: <oldName>` in every descriptor SOURCE. Not a `<collection>/<id>`
+			//    ref, so step 3 cannot see it — and leaving it makes compile fail on an unknown target.
+			for (const f of descriptorSources(ws, store)) {
+				const before = fs.readFileSync(f, 'utf8');
+				const doc2 = load(before);
+				if (!doc2 || !retargetRefs(doc2.schema, oldName, newName)) continue;
+				if (!refFiles.has(f)) refFiles.set(f, Buffer.from(before));
+				fs.writeFileSync(f, dump(doc2));
+				touched.add(f);
+				rewrites++;
+			}
+
+			compile(ws); // the gate: an uncompilable rename never reaches history
+		} catch (e) {
+			restoreRefs();
+			undo();
+			try { compile(ws); } catch { /* pre-rename sources were compilable */ }
+			throw e;
+		}
+
+		// `git add -- <path>` FAILS OUTRIGHT on a pathspec that is neither on disk nor in the index —
+		// which is exactly what the old descriptor becomes when it was never committed in the first
+		// place (a collection added but not yet published). One bad entry aborts the whole `add`, so
+		// the rename rolled back over a file git simply did not care about. Filter, don't assume.
+		const rels = [...touched]
+			.map((f) => path.relative(ws.root, f))
+			.filter((rel) => fs.existsSync(path.join(ws.root, rel)) || isTracked(ws.root, rel));
+		try {
+			execFileSync('git', ['add', '--all', '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET });
+			execFileSync('git', ['commit', '--quiet', '-m', `dreamteamer: collections rename ${oldName} → ${newName}`, '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET });
+		} catch (e) {
+			try { execFileSync('git', ['reset', '--quiet', '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET }); } catch { /* nothing staged */ }
+			restoreRefs();
+			undo();
+			try { compile(ws); } catch { /* pre-rename sources were compilable */ }
+			throw new Error(`git commit failed — the rename was rolled back, nothing was changed. (${e.message.split('\n')[0]})`);
+		}
+
+		return {
+			renamed: true, name: newName, records: ids.length, rewrites,
+			from: path.relative(ws.root, oldDir), to: path.relative(ws.root, newDir),
+			suffix: newSuffix !== oldSuffix ? { from: oldSuffix, to: newSuffix } : null,
+			pathKept: pathWasDerived ? null : authoredPath,
+		};
+	});
+}
+
+/** Does git know this path? A deleted-and-never-committed file must be dropped from a pathspec. */
+function isTracked(root, rel) {
+	try {
+		execFileSync('git', ['ls-files', '--error-unmatch', '--', rel], { cwd: root, stdio: ['ignore', 'ignore', 'ignore'] });
+		return true;
+	} catch { return false; }
+}
+
+/** Every workspace-owned descriptor source, recursively (namespaced descriptors are nested). */
+function descriptorSources(ws, store) {
+	const out = [];
+	for (const root of store.sourceRoots()) {
+		const dir = kindDir(root, 'collections');
+		// ⚠ SPREAD FIRST. `walk` is a GENERATOR, and `Iterator.prototype.filter` is a Node 22 iterator
+		// helper — so `walk(dir).filter(...)` works on 22 and throws "filter is not a function" on 20,
+		// which package.json still supports (`"node": ">=20"`). Caught by the CI matrix, not by local runs.
+		if (fs.existsSync(dir)) out.push(...[...walk(dir)].filter((f) => f.endsWith('.collection.yaml')));
+	}
+	return out;
+}
+
+/** Rewrite `x-reference: old` → new anywhere in a schema. Returns true if anything changed. */
+function retargetRefs(schema, oldName, newName) {
+	let changed = false;
+	for (const prop of Object.values(schema?.properties ?? {})) {
+		if (!prop || typeof prop !== 'object') continue;
+		for (const holder of [prop, prop.items]) {
+			if (holder && typeof holder === 'object' && holder['x-reference'] === oldName) {
+				holder['x-reference'] = newName;
+				changed = true;
+			}
+		}
+		if (prop.properties && retargetRefs(prop, oldName, newName)) changed = true;
+		if (prop.items?.properties && retargetRefs(prop.items, oldName, newName)) changed = true;
+	}
+	return changed;
+}
+
+/** Remove now-empty parents up to (not including) the data root — a moved collection leaves its
+ *  namespace folder behind otherwise. */
+function pruneEmpty(dir, stopAt) {
+	while (dir !== stopAt && dir.startsWith(stopAt) && fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+		fs.rmdirSync(dir);
+		dir = path.dirname(dir);
+	}
+}
+
 export function addField(ws, store, collection, { name: fieldName, prop, required }) {
 	store.descriptor(collection); // must exist in the compiled runtime
 	if (!fieldName) throw new Error('missing field name');

package/src/server.js

@@ -70,6 +70,15 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 		res.json([...store.descriptors.values()].sort((a, b) => (a.order ?? 999) - (b.order ?? 999)));
 	});
 
+	// ⚠ A NAMESPACED COLLECTION NAME CONTAINS A SLASH (`health/doctors`), and `:name` is one path
+	// segment — so a client MUST percent-encode it: `/collections/health%2Fdoctors/records`. Express
+	// matches on the still-encoded path and decodes params afterwards, so `req.params.name` arrives as
+	// `health/doctors` and every route below works unchanged.
+	//
+	// The alternative was `*name`, and it is wrong: `/collections/*name/records/*id` puts a greedy
+	// wildcard, a literal and a second wildcard in one pattern, so `/collections/a/b/records/c` has
+	// several readings and the router picks one. Encoding keeps the boundary explicit at the caller,
+	// which is the same reason references declare their namespace instead of having it inferred.
 	api.get('/collections/:name/records', (req, res) => {
 		const d = store.descriptor(req.params.name);
 		const bf = bodyField(d);

package/src/store.js

@@ -11,7 +11,8 @@ import { dump } from './yaml.js';
 import { generateId } from './template.js';
 import { parseRecord, parseRecordText, patternRe, fmtAjvError, unknownFields, walk, EXT, assertSafeId } from './records.js';
 import { normalizeRecord } from './temporal.js';
-import { NO_RUNTIME, sourceHint, loadDescriptors, runtimeDir, sourceRoots as compiledSourceRoots } from './runtime.js';
+import { NO_RUNTIME, sourceHint, loadDescriptors, runtimeDir, namespaces as compiledNamespaces, sourceRoots as compiledSourceRoots } from './runtime.js';
+import { parseRef } from './namespace.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -33,6 +34,9 @@ export class Store {
 		const descriptors = loadDescriptors(root);
 		if (!descriptors) throw new Error(NO_RUNTIME);
 		this.descriptors = descriptors;
+		// The closed set every reference is split against (see src/namespace.js). Read once per Store:
+		// it is compile output, and a Store is already rebuilt whenever the runtime changes.
+		this.namespaces = compiledNamespaces(root);
 	}
 
 	descriptor(collection) {
@@ -186,10 +190,12 @@ export class Store {
 			if (raw == null) continue;
 			for (const value of Array.isArray(raw) ? raw : [raw]) {
 				if (typeof value !== 'string' || value.startsWith('@')) continue;
-				const slash = value.indexOf('/');
-				if (slash < 1) throw new Error(`${key}: reference "${value}" is not <collection>/<id> — nothing was written.`);
-				const coll = value.slice(0, slash);
-				const id = value.slice(slash + 1);
+				// ONE parser for the collection/id boundary, shared with `check` and the extension —
+				// a namespace that meant one thing on write and another on read would be worse than
+				// no namespaces at all.
+				const parsed = parseRef(value, this.namespaces);
+				if (!parsed) throw new Error(`${key}: reference "${value}" is not <collection>/<id> — nothing was written.`);
+				const { collection: coll, id } = parsed;
 				if (target !== '*' && coll !== target) throw new Error(`${key}: reference "${value}" must target collection "${target}" — nothing was written.`);
 				if (!this.descriptors.has(coll)) throw new Error(`${key}: reference "${value}" targets unknown collection "${coll}" — nothing was written.`);
 				if (!this.ids(coll).has(id)) throw new Error(`${key}: dangling reference "${value}" — no such record. nothing was written.`);
@@ -243,9 +249,6 @@ export class Store {
 			throw new Error(`${collection}/${id} is referenced by:\n${inbound.map((f) => `  ${f}`).join('\n')}\nfix the references or pass --force. nothing was removed.`);
 		}
 		const unit = this.recordRoot(d, id); // folder-shape: the whole folder goes, not just the entry file
-		// Folder-shape records would need a recursive snapshot; the only folder-shape collection
-		// is `skills`, which is system-stored and so never reaches rm (writableDescriptor refuses
-		// first). Not built for a case that cannot occur.
 		// snapshot BEFORE the delete, or there is nothing left to read
 		const restore = snapshot([unit]);
 		return this.withWriteLock(() => {
@@ -389,10 +392,14 @@ export class Store {
 		const cwd = path.resolve(this.root, repo);
 		const rel = files.map((f) => path.relative(cwd, f));
 		try {
-			execFileSync('git', ['add', '--all', '--', ...rel], { cwd });
-			execFileSync('git', ['commit', '--quiet', '-m', subject, '--', ...rel], { cwd });
+			// QUIET, per the rule at the top of this file: a failure we CATCH must not also print git's
+			// own error. These three were the exception — a caught `git add` failure dumped git's raw
+			// multi-line advice ("Another git process seems to be running…") on top of the clean message
+			// this function throws, so the user read the scary one and not the accurate one.
+			execFileSync('git', ['add', '--all', '--', ...rel], { cwd, stdio: QUIET });
+			execFileSync('git', ['commit', '--quiet', '-m', subject, '--', ...rel], { cwd, stdio: QUIET });
 		} catch (e) {
-			try { execFileSync('git', ['reset', '--quiet', '--', ...rel], { cwd }); } catch { /* nothing staged */ }
+			try { execFileSync('git', ['reset', '--quiet', '--', ...rel], { cwd, stdio: QUIET }); } catch { /* nothing staged */ }
 			if (undo) {
 				try { undo(); } catch (u) {
 					throw new Error(`git commit failed AND rollback failed (${u.message}) — inspect the working tree. original: ${e.message.split('\n')[0]}`);
@@ -442,21 +449,50 @@ function readPkg(root) {
 	try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { return {}; }
 }
 
-/** Byte snapshot of a set of files, and a restore closure. The undo mechanism schema-ops has
- *  used for source writes since it was written (schema-ops.js:20). Record writes used
+/** Byte snapshot of a set of files OR DIRECTORIES, and a restore closure. The undo mechanism
+ *  schema-ops has used for source writes since it was written (schema-ops.js:20). Record writes used
  *  `git checkout HEAD -- <paths>` instead, which is only correct while HEAD is guaranteed to be
  *  the last good state — it is not, once writes stop committing, and it silently discarded
- *  uncommitted hand-edits even before that. */
+ *  uncommitted hand-edits even before that.
+ *
+ *  A DIRECTORY unit is snapshotted recursively. It used to be skipped with a comment arguing the case
+ *  could not occur — the only folder-shape collection was `skills`, which is system-stored, so
+ *  `writableDescriptor` refused before `rm` was reached. That reasoning was true and is the wrong kind
+ *  of true: it depended on a fact about the CURRENT set of collections rather than on anything the code
+ *  enforces, and `shape: folder` is an ordinary descriptor option any workspace can choose. The failure
+ *  it left behind was silent and total — `rm` would delete the folder and the "restore" closure would
+ *  do nothing, so a failed commit meant the record was simply gone. Twelve lines, no such hole. */
 function snapshot(units) {
-	const snaps = units.map((u) => ({
-		u,
-		prev: fs.existsSync(u) && fs.statSync(u).isFile() ? fs.readFileSync(u) : null,
-		existed: fs.existsSync(u),
-	}));
+	const snaps = units.map((u) => {
+		const existed = fs.existsSync(u);
+		const isDir = existed && fs.statSync(u).isDirectory();
+		return {
+			u, existed, isDir,
+			prev: existed && !isDir ? fs.readFileSync(u) : null,
+			tree: isDir ? snapshotTree(u) : null,
+		};
+	});
 	return () => {
-		for (const { u, prev, existed } of snaps) {
+		for (const { u, prev, tree, existed, isDir } of snaps) {
 			if (!existed) { fs.rmSync(u, { force: true, recursive: true }); continue; }
+			if (isDir) {
+				fs.rmSync(u, { force: true, recursive: true }); // partial state from a failed op
+				fs.mkdirSync(u, { recursive: true });
+				for (const [rel, bytes] of tree) {
+					const dest = path.join(u, rel);
+					fs.mkdirSync(path.dirname(dest), { recursive: true });
+					fs.writeFileSync(dest, bytes);
+				}
+				continue;
+			}
 			if (prev !== null) { fs.mkdirSync(path.dirname(u), { recursive: true }); fs.writeFileSync(u, prev); }
 		}
 	};
 }
+
+/** Every file under `dir` as [relative path, bytes] — the whole of a folder-shape record. */
+function snapshotTree(dir) {
+	const out = [];
+	for (const file of walk(dir)) out.push([path.relative(dir, file), fs.readFileSync(file)]);
+	return out;
+}