depa-codument 0.4.1

package/src/cli/index.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+import { listCommand } from './commands/list';
+import { showCommand } from './commands/show';
+import { validateCommand } from './commands/validate';
+import { statusCommand } from './commands/status';
+import { initCommand } from './commands/init';
+import { archiveCommand } from './commands/archive';
+import { upgradeWorkspaceCommand } from './commands/upgrade-workspace';
+import { upgradeTrackCommand } from './commands/upgrade-track';
+import { modelingCommand } from './commands/modeling';
+import { engineeringCommand } from './commands/engineering';
+import { decisionsCommand } from './commands/decisions';
+import { setWorkspaceDir } from './utils';
+import { VERSION } from '../version';
+
+function helpText(): string {
+  return `
+codument v${VERSION} - Spec-driven development tool for AI coding assistants
+
+Usage:
+  codument <command> [options]
+
+Commands:
+  init              Initialize Codument in the current project
+  upgrade-workspace  Upgrade workspace Codument files to latest
+  upgrade-track      Upgrade a track plan.xml to wave-capable format
+  list              List active tracks or specs
+  show [item]       Show details of a track or spec
+  validate [item]   Validate track or spec format
+  archive <id>      Archive a completed track
+  status            Show project status overview
+  modeling lint     Flag oversized modeling XNL files for fractal split
+  modeling validate Validate modeling XNL (syntax + schema + hierarchy)
+  engineering lint  Flag oversized engineering XNL files for fractal split
+  engineering validate Validate engineering XNL (syntax + schema + hierarchy)
+  decisions validate Validate track decisions.md metadata
+
+Options:
+  -h, --help              Show this help message
+  -v, --version           Show version number
+  -w, --workspace-dir     Set workspace directory (default: current directory)
+
+Examples:
+  codument init --agent=codex,claude,eidolon,sparrow            # Install skills into the target skills dir
+  codument init --skills-dir=.claude/skills --force
+  codument upgrade-workspace --agent=codex,claude,eidolon,sparrow  # Refresh std + selected agent skills
+  codument list                          # List active tracks
+  codument show add-user-auth            # Show track details
+  codument validate                      # Validate all tracks (track.xml + behavior deltas)
+  codument validate add-user-auth        # Validate one track
+  codument status                         # Show project status
+`;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse global options first
+  let workspaceDir: string | undefined;
+  const filteredArgs: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-w' || args[i] === '--workspace-dir') {
+      workspaceDir = args[i + 1];
+      i++; // Skip the value
+    } else {
+      filteredArgs.push(args[i]);
+    }
+  }
+
+  // Set workspace directory if provided
+  if (workspaceDir) {
+    setWorkspaceDir(workspaceDir);
+  }
+
+  if (filteredArgs.length === 0 || filteredArgs[0] === '-h' || filteredArgs[0] === '--help') {
+    console.log(helpText());
+    process.exit(0);
+  }
+
+  if (filteredArgs[0] === '-v' || filteredArgs[0] === '--version') {
+    console.log(`codument v${VERSION}`);
+    process.exit(0);
+  }
+
+  const command = filteredArgs[0];
+  const commandArgs = filteredArgs.slice(1);
+
+  try {
+    switch (command) {
+      case 'init':
+        await initCommand(commandArgs);
+        break;
+      case 'list':
+        await listCommand(commandArgs);
+        break;
+      case 'show':
+        await showCommand(commandArgs);
+        break;
+      case 'validate':
+        await validateCommand(commandArgs);
+        break;
+      case 'archive':
+        await archiveCommand(commandArgs);
+        break;
+      case 'status':
+        await statusCommand(commandArgs);
+        break;
+      case 'upgrade-workspace':
+        await upgradeWorkspaceCommand(commandArgs);
+        break;
+      case 'upgrade-track':
+        await upgradeTrackCommand(commandArgs);
+        break;
+      case 'modeling':
+        await modelingCommand(commandArgs);
+        break;
+      case 'engineering':
+        await engineeringCommand(commandArgs);
+        break;
+      case 'decisions':
+        await decisionsCommand(commandArgs);
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.log(helpText());
+        process.exit(1);
+    }
+    process.exit(0);
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/cli/modeling/config.ts

@@ -0,0 +1,68 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { CODUMENT_DIR } from '../utils';
+import { DEFAULT_THRESHOLDS, type LintThresholds } from './lint';
+import { DEFAULT_POLICY, type MergePolicy, type ConflictType, type Resolve } from './merge';
+
+/**
+ * codument/config/modeling.xml gate + settings.
+ *
+ * Default OFF: when the file is absent or `enabled` is not "true", modeling is
+ * disabled and all modeling behavior (track delta, archive merge, lint) is skipped.
+ * Lightweight regex read (the file is small and flat); no XML dependency.
+ */
+
+export interface ModelingConfig {
+  enabled: boolean;
+  registryDir: string;
+  thresholds: LintThresholds;
+  mergePolicy: MergePolicy;
+}
+
+export function modelingConfigPath(workspaceDir = '.'): string {
+  return path.join(workspaceDir, CODUMENT_DIR, 'config', 'modeling.xml');
+}
+
+function matchNum(xml: string, re: RegExp): number | undefined {
+  const m = re.exec(xml);
+  return m ? Number(m[1]) : undefined;
+}
+
+const VALID_RESOLVE = new Set<Resolve>(['human', 'ours', 'theirs', 'base']);
+
+export function loadModelingConfig(configPath = modelingConfigPath()): ModelingConfig {
+  const def: ModelingConfig = {
+    enabled: false,
+    registryDir: path.join(CODUMENT_DIR, 'modeling'),
+    thresholds: { ...DEFAULT_THRESHOLDS },
+    mergePolicy: { ...DEFAULT_POLICY },
+  };
+  if (!fs.existsSync(configPath)) return def;
+
+  const xml = fs.readFileSync(configPath, 'utf-8');
+  const enabled = /<Modeling[^>]*\benabled="true"/.test(xml);
+  const maxLines = matchNum(xml, /<Lint[^>]*\bmaxLines="(\d+)"/);
+  const maxNodes = matchNum(xml, /<Lint[^>]*\bmaxNodes="(\d+)"/);
+
+  const mergePolicy: MergePolicy = { ...DEFAULT_POLICY };
+  for (const m of xml.matchAll(/<Conflict\s+type="([^"]+)"\s+resolve="([^"]+)"/g)) {
+    const type = m[1] as ConflictType;
+    const resolve = m[2] as Resolve;
+    if (type in mergePolicy && VALID_RESOLVE.has(resolve)) mergePolicy[type] = resolve;
+  }
+
+  return {
+    enabled,
+    registryDir: def.registryDir,
+    thresholds: {
+      maxLines: maxLines ?? DEFAULT_THRESHOLDS.maxLines,
+      maxNodes: maxNodes ?? DEFAULT_THRESHOLDS.maxNodes,
+    },
+    mergePolicy,
+  };
+}
+
+/** True when modeling is enabled in this workspace. */
+export function modelingEnabled(workspaceDir = '.'): boolean {
+  return loadModelingConfig(modelingConfigPath(workspaceDir)).enabled;
+}

package/src/cli/modeling/lint.ts

@@ -0,0 +1,58 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadModelingRegistry, isDataElement, readNodeId } from './registry';
+
+/**
+ * Fractal-split lint: flag oversized modeling XNL files as candidates for
+ * same-name-folder split (multi-file). Heuristic, advisory — the actual split is
+ * applied by the model per folder-manifest.md. Thresholds are configurable
+ * (defaults below; overridable via codument/config/modeling.xml in P4).
+ */
+
+export interface LintThresholds {
+  /** Max lines before a file is a split candidate. */
+  maxLines: number;
+  /** Max top-level modeling nodes before a file is a split candidate. */
+  maxNodes: number;
+}
+
+export const DEFAULT_THRESHOLDS: LintThresholds = {
+  maxLines: 400,
+  maxNodes: 8,
+};
+
+export interface LintFinding {
+  file: string;
+  lines: number;
+  nodeCount: number;
+  reasons: string[];
+}
+
+/** Lint a modeling registry directory for fractal-split candidates. */
+export function lintModelingRegistry(
+  dir: string,
+  thresholds: LintThresholds = DEFAULT_THRESHOLDS,
+): LintFinding[] {
+  const findings: LintFinding[] = [];
+  if (!fs.existsSync(dir)) return findings;
+  const registry = loadModelingRegistry(dir);
+
+  for (const [relFile, nodes] of registry.files) {
+    const content = fs.readFileSync(path.join(dir, relFile), 'utf-8');
+    const lines = content.split('\n').length;
+    const nodeCount = nodes.filter((n) => isDataElement(n) && readNodeId(n)).length;
+
+    const reasons: string[] = [];
+    if (lines > thresholds.maxLines) {
+      reasons.push(`${lines} lines > ${thresholds.maxLines}`);
+    }
+    if (nodeCount > thresholds.maxNodes) {
+      reasons.push(`${nodeCount} nodes > ${thresholds.maxNodes}`);
+    }
+    if (reasons.length > 0) {
+      findings.push({ file: relFile, lines, nodeCount, reasons });
+    }
+  }
+
+  return findings.sort((a, b) => a.file.localeCompare(b.file));
+}

package/src/cli/modeling/merge.ts

@@ -0,0 +1,172 @@
+import { diffNodes, applyMutations, parsePath } from 'xnl-core';
+import type { XnlNode, XnlMutation, XnlPath, PathItem } from 'xnl-core';
+import { isDataElement, readNodeId } from './registry';
+
+/**
+ * Node-level three-way merge for modeling deltas (base + ours + theirs), keyed by
+ * namespaced node id. Reuses xnl-core diffNodes/applyMutations. Conservative by
+ * default: disjoint changes auto-merge; true conflicts are reported (not silently
+ * overwritten) unless a per-type policy overrides. See std/spec/modeling-delta.md.
+ */
+
+export type ConflictType = 'same-field' | 'delete-modify' | 'add-add';
+export type Resolve = 'human' | 'ours' | 'theirs' | 'base';
+export type MergePolicy = Record<ConflictType, Resolve>;
+
+export const DEFAULT_POLICY: MergePolicy = {
+  'same-field': 'human',
+  'delete-modify': 'human',
+  'add-add': 'human',
+};
+
+export interface MergeConflict {
+  id: string;
+  type: ConflictType;
+  base?: XnlNode;
+  ours?: XnlNode;
+  theirs?: XnlNode;
+}
+
+export interface MergeResult {
+  /** Merged node set keyed by id (excludes unresolved human conflicts). */
+  merged: Map<string, XnlNode>;
+  conflicts: MergeConflict[];
+}
+
+/** Index top-level DataElement nodes by id. */
+export function indexById(nodes: XnlNode[]): Map<string, XnlNode> {
+  const m = new Map<string, XnlNode>();
+  for (const n of nodes) {
+    const id = readNodeId(n);
+    if (id && isDataElement(n)) m.set(id, n);
+  }
+  return m;
+}
+
+function clone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v)) as T;
+}
+
+function nodeEqual(a: XnlNode | undefined, b: XnlNode | undefined): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function mutationsBetween(from: XnlNode, to: XnlNode): XnlMutation[] {
+  return diffNodes(from, to, [], { metadataIdMode: 'identity' });
+}
+
+function pathItems(p: string | XnlPath): PathItem[] {
+  return Array.isArray(p) ? p : parsePath(p);
+}
+
+/** Two paths overlap if one is a prefix of (or equal to) the other. */
+function overlaps(a: PathItem[], b: PathItem[]): boolean {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    if (a[i].type !== b[i].type || a[i].value !== b[i].value) return false; // diverge -> disjoint
+  }
+  return true; // one is a prefix of the other -> overlap
+}
+
+function changesAreDisjoint(oursMut: XnlMutation[], theirsMut: XnlMutation[]): boolean {
+  for (const o of oursMut) {
+    for (const t of theirsMut) {
+      if (overlaps(pathItems(o.path), pathItems(t.path))) return false;
+    }
+  }
+  return true;
+}
+
+function resolveConflict(
+  conflict: MergeConflict,
+  policy: MergePolicy,
+  merged: Map<string, XnlNode>,
+  conflicts: MergeConflict[],
+): void {
+  const choice = policy[conflict.type] ?? 'human';
+  switch (choice) {
+    case 'ours':
+      if (conflict.ours !== undefined) merged.set(conflict.id, conflict.ours);
+      return;
+    case 'theirs':
+      if (conflict.theirs !== undefined) merged.set(conflict.id, conflict.theirs);
+      return;
+    case 'base':
+      if (conflict.base !== undefined) merged.set(conflict.id, conflict.base);
+      return;
+    case 'human':
+    default:
+      conflicts.push(conflict); // report; leave unresolved
+      return;
+  }
+}
+
+export function mergeModeling(
+  baseNodes: XnlNode[],
+  ourNodes: XnlNode[],
+  theirNodes: XnlNode[],
+  policy: MergePolicy = DEFAULT_POLICY,
+): MergeResult {
+  const base = indexById(baseNodes);
+  const ours = indexById(ourNodes);
+  const theirs = indexById(theirNodes);
+  const merged = new Map<string, XnlNode>();
+  const conflicts: MergeConflict[] = [];
+
+  const ids = new Set<string>([...base.keys(), ...ours.keys(), ...theirs.keys()]);
+
+  for (const id of ids) {
+    const b = base.get(id);
+    const o = ours.get(id);
+    const t = theirs.get(id);
+
+    // Present in all three.
+    if (b && o && t) {
+      const oChanged = !nodeEqual(b, o);
+      const tChanged = !nodeEqual(b, t);
+      if (!oChanged && !tChanged) merged.set(id, o);
+      else if (oChanged && !tChanged) merged.set(id, o);
+      else if (!oChanged && tChanged) merged.set(id, t);
+      else if (nodeEqual(o, t)) merged.set(id, o); // same change both sides
+      else {
+        const oursMut = mutationsBetween(b, o);
+        const theirsMut = mutationsBetween(b, t);
+        if (changesAreDisjoint(oursMut, theirsMut)) {
+          merged.set(id, applyMutations(clone(b), [...oursMut, ...theirsMut], { metadataIdMode: 'identity' }));
+        } else {
+          resolveConflict({ id, type: 'same-field', base: b, ours: o, theirs: t }, policy, merged, conflicts);
+        }
+      }
+      continue;
+    }
+
+    // Added (not in base).
+    if (!b) {
+      if (o && !t) merged.set(id, o);
+      else if (!o && t) merged.set(id, t);
+      else if (o && t) {
+        if (nodeEqual(o, t)) merged.set(id, o);
+        else resolveConflict({ id, type: 'add-add', ours: o, theirs: t }, policy, merged, conflicts);
+      }
+      continue;
+    }
+
+    // In base; deleted on at least one side.
+    const oDeleted = !o;
+    const tDeleted = !t;
+    if (oDeleted && tDeleted) continue; // both deleted -> gone
+    if (oDeleted && t) {
+      // ours deleted; theirs kept/modified
+      if (nodeEqual(b, t)) continue; // theirs unchanged -> honor delete
+      resolveConflict({ id, type: 'delete-modify', base: b, theirs: t }, policy, merged, conflicts);
+      continue;
+    }
+    if (tDeleted && o) {
+      if (nodeEqual(b, o)) continue; // ours unchanged -> honor delete
+      resolveConflict({ id, type: 'delete-modify', base: b, ours: o }, policy, merged, conflicts);
+      continue;
+    }
+  }
+
+  return { merged, conflicts };
+}

package/src/cli/modeling/registry.ts

@@ -0,0 +1,229 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseXnl, stringifyLineBlock, wordToString, XnlParseError } from 'xnl-core';
+import type { XnlNode, DataElementNode, XnlWord } from 'xnl-core';
+
+/**
+ * codument modeling registry adapter.
+ *
+ * The registry is a plain, host-git-versioned working tree of `.xnl` files under
+ * `codument/modeling/<plane>/<context>/...`. We load/save via xnl-core (parse +
+ * lineBlock formatter) and index nodes by their namespaced id. No parallel vcs repo
+ * is persisted; node-level 3-way merge (see merge.ts) uses xnl-vfs ephemerally.
+ */
+
+export interface ModelingNodeRef {
+  /** Namespaced id, e.g. `resource.skill_tool` or `domain.resource.skill_tool`. */
+  id: string;
+  node: DataElementNode;
+  /** Path relative to the modeling dir, e.g. `domain/resource/index.xnl`. */
+  file: string;
+  /** `modeling://<plane>/<context>/<name>` derived from the file path + id. */
+  uri: string;
+}
+
+export interface ModelingRegistry {
+  dir: string;
+  /** relPath -> top-level nodes of that file (preserves order for save). */
+  files: Map<string, XnlNode[]>;
+  /** namespaced id -> ref. */
+  index: Map<string, ModelingNodeRef>;
+}
+
+export function isDataElement(node: XnlNode | undefined): node is DataElementNode {
+  return Boolean(node && typeof node === 'object' && (node as DataElementNode).kind === 'DataElement');
+}
+
+/** Read a node's namespaced id from `#word` or `metadata.id`. */
+export function readNodeId(node: XnlNode): string | undefined {
+  if (!isDataElement(node)) return undefined;
+  const fromWord = wordToString((node as { id?: XnlWord }).id);
+  if (fromWord) return fromWord;
+  const metaId = node.metadata?.id;
+  if (typeof metaId === 'string') return metaId;
+  if (metaId && typeof metaId === 'object' && (metaId as XnlWord).kind === 'Word') {
+    return wordToString(metaId as XnlWord);
+  }
+  return undefined;
+}
+
+/** Last segment of a namespaced id (`a.b.name` -> `name`). */
+export function nodeName(id: string): string {
+  const parts = id.split('.');
+  return parts[parts.length - 1];
+}
+
+/**
+ * Namespace prefix of a namespaced id (`a.b.name` -> `a.b`, `name` -> ``).
+ * The namespace is the id minus its trailing `name` segment; a bare name yields
+ * the empty string. Used by id↔path alignment and modeling-uri derivation.
+ */
+export function idNamespace(id: string): string {
+  const parts = id.split('.');
+  return parts.slice(0, -1).join('.');
+}
+
+/** Build `modeling://<plane>/<context>/<name>` from a file path and node id. */
+export function modelingUri(relFile: string, id: string): string {
+  const segs = relFile.split(path.sep).filter(Boolean);
+  const plane = segs[0] ?? 'domain';
+  const context = segs[1] ?? plane;
+  return `modeling://${plane}/${context}/${nodeName(id)}`;
+}
+
+function isHidden(name: string): boolean {
+  return name.startsWith('.');
+}
+
+function walkXnlFiles(dir: string, base: string, out: string[]): void {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (isHidden(entry.name)) continue; // skip .node-meta, .tmp, .xnl-vcs, etc.
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkXnlFiles(abs, base, out);
+    } else if (entry.isFile() && entry.name.endsWith('.xnl')) {
+      out.push(path.relative(base, abs));
+    }
+  }
+}
+
+/** Load the modeling registry from a working tree directory. */
+export function loadModelingRegistry(dir: string): ModelingRegistry {
+  const files = new Map<string, XnlNode[]>();
+  const index = new Map<string, ModelingNodeRef>();
+  const relFiles: string[] = [];
+  walkXnlFiles(dir, dir, relFiles);
+  relFiles.sort();
+
+  for (const relFile of relFiles) {
+    const content = fs.readFileSync(path.join(dir, relFile), 'utf-8');
+    const nodes = parseXnl(content, { textBlockStyle: true }).nodes;
+    files.set(relFile, nodes);
+    for (const node of nodes) {
+      const id = readNodeId(node);
+      if (!id || !isDataElement(node)) continue;
+      if (index.has(id)) {
+        throw new Error(
+          `Duplicate modeling node id '${id}' in '${relFile}' and '${index.get(id)!.file}'`,
+        );
+      }
+      index.set(id, { id, node, file: relFile, uri: modelingUri(relFile, id) });
+    }
+  }
+
+  return { dir, files, index };
+}
+
+/**
+ * A non-fatal load issue collected by {@link loadModelingRegistrySafe}: an XNL
+ * parse error (`syntax`) or a cross-file duplicate id (`duplicate-id`). The
+ * validate engine maps these onto its own finding shape.
+ */
+export interface LoadIssue {
+  kind: 'syntax' | 'duplicate-id';
+  /** Path relative to the registry dir. */
+  file: string;
+  /** 1-based line, when known (parse errors carry one). */
+  line?: number;
+  message: string;
+  /** For duplicate ids: the other file that already defined the id. */
+  otherFile?: string;
+}
+
+export interface SafeRegistryResult {
+  registry: ModelingRegistry;
+  issues: LoadIssue[];
+}
+
+/**
+ * Load the modeling registry without throwing. Files that fail XNL parsing are
+ * skipped (their error is collected as a `syntax` issue); duplicate ids are
+ * collected as `duplicate-id` issues (first definition wins in the index)
+ * instead of aborting the load. The non-safe {@link loadModelingRegistry}
+ * keeps its throwing contract for existing callers (lint, merge, archive).
+ */
+export function loadModelingRegistrySafe(dir: string): SafeRegistryResult {
+  const files = new Map<string, XnlNode[]>();
+  const index = new Map<string, ModelingNodeRef>();
+  const issues: LoadIssue[] = [];
+  const relFiles: string[] = [];
+  walkXnlFiles(dir, dir, relFiles);
+  relFiles.sort();
+
+  for (const relFile of relFiles) {
+    const content = fs.readFileSync(path.join(dir, relFile), 'utf-8');
+    let nodes: XnlNode[];
+    try {
+      nodes = parseXnl(content, { textBlockStyle: true }).nodes;
+    } catch (err) {
+      if (err instanceof XnlParseError) {
+        issues.push({ kind: 'syntax', file: relFile, line: err.line, message: err.message });
+        continue;
+      }
+      throw err;
+    }
+    files.set(relFile, nodes);
+    for (const node of nodes) {
+      const id = readNodeId(node);
+      if (!id || !isDataElement(node)) continue;
+      const existing = index.get(id);
+      if (existing) {
+        issues.push({
+          kind: 'duplicate-id',
+          file: relFile,
+          otherFile: existing.file,
+          message: `Duplicate modeling node id '${id}' in '${relFile}' and '${existing.file}'`,
+        });
+        continue;
+      }
+      index.set(id, { id, node, file: relFile, uri: modelingUri(relFile, id) });
+    }
+  }
+
+  return { registry: { dir, files, index }, issues };
+}
+
+export interface SerializeOptions {
+  /**
+   * Marker factory for markerless text blocks. Defaults to xnl-core's ULID factory,
+   * which preserves XNL text nodes' escape-free property (a markerless `?>` block
+   * gets a stable unique marker on first write, then round-trips unchanged).
+   * Tests may inject a deterministic factory; production MUST keep the ULID default.
+   */
+  textMarkerFactory?: () => string;
+  /**
+   * Block text style (default true for modeling files): render each text element's
+   * content on its own indented line(s) between `<tag ?m>` and `</?m>`, so registry
+   * files stay readable and diff-friendly. Paired with `parseXnl(.., {textBlockStyle})`.
+   */
+  textBlockStyle?: boolean;
+}
+
+/** Serialize top-level nodes of a file to XNL (lineBlock pretty, block text style). */
+export function serializeModelingFile(nodes: XnlNode[], opts: SerializeOptions = {}): string {
+  return nodes.map((n) => stringifyLineBlock(n, { textBlockStyle: true, ...opts })).join('\n\n') + '\n';
+}
+
+/** Write one modeling file back to the working tree. */
+export function saveModelingFile(
+  dir: string,
+  relFile: string,
+  nodes: XnlNode[],
+  opts: SerializeOptions = {},
+): void {
+  const abs = path.join(dir, relFile);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, serializeModelingFile(nodes, opts), 'utf-8');
+}
+
+/** Save the whole registry back to its working tree. */
+export function saveModelingRegistry(
+  registry: ModelingRegistry,
+  targetDir = registry.dir,
+  opts: SerializeOptions = {},
+): void {
+  for (const [relFile, nodes] of registry.files) {
+    saveModelingFile(targetDir, relFile, nodes, opts);
+  }
+}