ddduck 0.1.0 → 0.2.0

package/scripts/ddduck.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
+/**
+ * Entry point for the `ddduck` CLI (the package bin). Dispatches the commands
+ * init, check, generate, query, install, and the guarantee lifecycle commands
+ * create/move/split/retire. Mutations run through the locked, staged operation
+ * runner in lib/product-operation.mjs; init publishes a fresh product root via
+ * PID-stamped staging; check delegates to check-model.mjs plus the generated
+ * freshness gates. Errors leave through writeCliError with a Next: action line.
+ */
+
 import {
   existsSync,
   mkdirSync,
@@ -10,6 +19,7 @@ import {
   renameSync,
   rmSync,
   rmdirSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
@@ -20,13 +30,23 @@ import { writeModelOverview } from "./generate-docs.mjs";
 import { writeModelGraph } from "./generate-graph.mjs";
 import { checkGeneratedDocs } from "./check-generated-docs.mjs";
 import { checkGeneratedGraph } from "./check-generated-graph.mjs";
-import { assertProductNotBusy, findLeftoverOperationState, runProductOperation } from "./lib/product-operation.mjs";
+import {
+  assertProductNotBusy,
+  findLeftoverOperationState,
+  generatedPaths,
+  isProcessAlive,
+  runProductOperation,
+  validationFailureError,
+} from "./lib/product-operation.mjs";
 import { resolveContainedOutput } from "./lib/product-paths.mjs";
 import { initStagingPrefix, resolveInitDestination, resolveProductRoot } from "./lib/product-root-resolver.mjs";
-import { defaultConfigIgnore, findRepositoryRoot } from "./lib/ddduck-config.mjs";
+import { defaultConfigIgnore, findRepositoryRoot, loadDdduckConfig } from "./lib/ddduck-config.mjs";
 import { installSkill } from "./lib/skill-installer.mjs";
 import { runQuery } from "./query-model.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
+import { buildAuthoringPlan } from "./lib/product-authoring.mjs";
+import { parseYamlMapping } from "./lib/product-layout.mjs";
+import { compareProductRoots, renderProductDiff } from "./lib/product-diff.mjs";
 
 const frameworkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -38,6 +58,11 @@ try {
   writeCliError(error, { nextAction: nextActionFor(cliArgs) });
 }
 
+/**
+ * Dispatch one parsed CLI invocation to its command handler.
+ * @param {string[]} args - Raw CLI arguments (process.argv minus node and script).
+ * @returns {void}
+ */
 function run(args) {
   if (args.length === 1 && args[0] === "--help") {
     process.stdout.write(renderHelp());
@@ -46,7 +71,7 @@ function run(args) {
   const [command, ...commandArgs] = args;
   if (
     !command ||
-    !["init", "check", "generate", "query", "install", "create", "move", "split", "retire"].includes(command)
+    !["init", "check", "generate", "query", "diff", "install", "create", "move", "split", "retire"].includes(command)
   ) {
     throw new CliUsageError(`Unknown command ${command ?? "(missing)"}`);
   }
@@ -71,16 +96,36 @@ function run(args) {
     runQuery(commandArgs);
     return;
   }
+  if (command === "diff") {
+    const { options } = parseCommandArgs(commandArgs, {
+      options: { base: { value: true }, root: { value: true }, json: { value: false } },
+    });
+    const base = requiredOption(options, "base", "diff requires --base <previous-product-root>");
+    const root = resolveProductRoot({ explicitRoot: options.root });
+    const report = compareProductRoots(path.resolve(base), root);
+    process.stdout.write(`${options.json ? JSON.stringify(report) : renderProductDiff(report)}\n`);
+    return;
+  }
   if (command === "install") {
     install(commandArgs);
     return;
   }
+  if (command === "create" && ["domain", "concept", "use-case"].includes(commandArgs[0])) {
+    createNode(commandArgs);
+    return;
+  }
   if (["create", "move", "split", "retire"].includes(command)) {
     transitionGuarantee(command, commandArgs);
     return;
   }
 }
 
+/**
+ * Implement `ddduck install skill update-ddduck-specs`: install the bundled
+ * host skill bundle and .ddduck/agent-skills.lock.json into --repo.
+ * @param {string[]} args - Arguments after the `install` command word.
+ * @returns {void}
+ */
 function install(args) {
   const { positionals, options } = parseCommandArgs(args, {
     positionals: { min: 2, max: 2 },
@@ -92,6 +137,13 @@ function install(args) {
   }
   const packageVersion = JSON.parse(readFileSync(path.join(frameworkRoot, "package.json"), "utf8")).version;
   const repository = path.resolve(options.repo ?? process.cwd());
+  // A typo'd --repo must fail instead of silently manufacturing a directory
+  // tree (and a lock) at the wrong path while the real repository gets nothing.
+  if (!existsSync(repository) || !statSync(repository).isDirectory()) {
+    throw new CliUsageError(`install requires an existing repository directory: ${repository}`, {
+      nextAction: "Pass --repo <existing-repository-root> and retry.",
+    });
+  }
   const result = installSkill({
     repository,
     skillName,
@@ -104,6 +156,14 @@ function install(args) {
   );
 }
 
+/**
+ * Implement `ddduck init`: build a new product root (canonical directories,
+ * product.yaml, all generated views) in a PID-stamped staging directory beside
+ * the destination, then publish it atomically via rename and write
+ * .ddduck/config.json if absent.
+ * @param {string[]} args - Arguments after the `init` command word.
+ * @returns {{result: object, json: boolean}} The operation result and whether --json was requested.
+ */
 function initialize(args) {
   const { positionals, options } = parseCommandArgs(args, {
     positionals: { min: 0, max: 1 },
@@ -112,7 +172,9 @@ function initialize(args) {
   const destination = resolveInitDestination({ explicitDestination: positionals[0] });
   const productId = requiredOption(options, "id", "init requires --id model:<product-id>");
   if (!/^model:[a-z0-9][a-z0-9-]*$/.test(productId)) {
-    throw new Error(`Invalid product ID ${JSON.stringify(productId)}`);
+    throw new Error(
+      `Invalid product ID ${JSON.stringify(productId)}; expected model:<lowercase-slug> (for example model:library)`,
+    );
   }
 
   mkdirSync(path.dirname(destination), { recursive: true });
@@ -121,14 +183,19 @@ function initialize(args) {
   }
 
   // Stage names embed the destination so concurrent inits to sibling
-  // destinations never sweep each other's live staging directories.
+  // destinations never sweep each other's live staging directories, and the
+  // creating PID so concurrent inits to the SAME destination only sweep stages
+  // whose creator is dead (mirroring the mutation lock's reclaim rule). Stages
+  // without a parseable live PID are interrupted-init debris and get swept.
   const destinationStagePrefix = `${initStagingPrefix}${path.basename(destination)}-`;
   for (const entry of readdirSync(path.dirname(destination))) {
-    if (entry.startsWith(destinationStagePrefix)) {
-      rmSync(path.join(path.dirname(destination), entry), { recursive: true, force: true });
-    }
+    if (!entry.startsWith(destinationStagePrefix)) continue;
+    const stagePid = Number.parseInt(entry.slice(destinationStagePrefix.length).match(/^(\d+)-/)?.[1] ?? "", 10);
+    if (Number.isInteger(stagePid) && stagePid > 0 && isProcessAlive(stagePid)) continue;
+    rmSync(path.join(path.dirname(destination), entry), { recursive: true, force: true });
   }
-  const stagingRoot = mkdtempSync(path.join(path.dirname(destination), destinationStagePrefix));
+  const stagingRoot = mkdtempSync(path.join(path.dirname(destination), `${destinationStagePrefix}${process.pid}-`));
+  let config;
   try {
     for (const directory of ["domains", "concepts", "relationships", "use-cases", "interfaces", "guarantees"]) {
       mkdirSync(resolveContainedOutput(stagingRoot, path.join("model", directory)), { recursive: true });
@@ -145,10 +212,22 @@ function initialize(args) {
       decisions: [],
     });
     refreshDerivedOutput(stagingRoot);
-    if (existsSync(destination)) rmdirSync(destination);
-    renameSync(stagingRoot, destination);
     try {
-      writeConfigIfAbsent(destination);
+      if (existsSync(destination)) rmdirSync(destination);
+      renameSync(stagingRoot, destination);
+    } catch (error) {
+      // A concurrent init to the same destination can publish between the
+      // emptiness check above and this rename; name the collision instead of
+      // surfacing the raw filesystem error.
+      if (error.code === "ENOTEMPTY" || error.code === "EEXIST") {
+        throw new Error(
+          `Refusing to initialize non-empty directory ${destination}; another init published it concurrently`,
+        );
+      }
+      throw error;
+    }
+    try {
+      config = writeConfigIfAbsent(destination);
     } catch (error) {
       // Writing the config is the final publish step. If it fails (for example a
       // regular file already occupies the .ddduck config path), roll back the
@@ -160,6 +239,7 @@ function initialize(args) {
   } finally {
     rmSync(stagingRoot, { recursive: true, force: true });
   }
+  if (!config.created) warnPinnedRepositoryDefault(config, destination);
   return {
     json: options.json,
     result: {
@@ -167,15 +247,46 @@ function initialize(args) {
       root: realpathSync(destination),
       affectedIds: [productId],
       canonicalPaths: ["product.yaml"],
-      generatedPaths: [
-        "generated/docs/model-overview.md",
-        "generated/graph/model-graph.json",
-        "generated/graph/model-graph.ndjson",
-      ],
+      generatedPaths: [...generatedPaths],
+      ...(config.created ? { configPath: config.configPath } : {}),
     },
   };
 }
 
+// A pre-existing repository config keeps selecting its own product root; a
+// second init must say so or every rootless command silently addresses the
+// other product.
+function warnPinnedRepositoryDefault(config, destination) {
+  let configuredRoot;
+  try {
+    const loaded = loadDdduckConfig(config.repositoryRoot);
+    if (!loaded) return;
+    configuredRoot = path.resolve(config.repositoryRoot, loaded.productRoot);
+  } catch {
+    return; // An unreadable config surfaces on the next root resolution.
+  }
+  if (canonicalPath(configuredRoot) === canonicalPath(destination)) return;
+  process.stderr.write(
+    `init: ${config.configPath} still selects ${configuredRoot} as the repository default root; pass --root or update the config to select ${path.resolve(destination)}.\n`,
+  );
+}
+
+function canonicalPath(candidate) {
+  try {
+    return realpathSync(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+/**
+ * Implement `ddduck check`: run check-model.mjs in a child process against the
+ * resolved root, then gate generated-view freshness (docs, graph JSON/NDJSON,
+ * and the SVG via a subprocess because rendering is async WASM) and refuse
+ * leftover interrupted-operation state. Busy roots exit 2 via ProductBusyError.
+ * @param {string[]} args - Arguments after the `check` command word.
+ * @returns {void}
+ */
 function executeChecker(args) {
   const { options } = parseCommandArgs(args, {
     options: {
@@ -186,6 +297,11 @@ function executeChecker(args) {
     },
   });
   const root = resolveProductRoot({ explicitRoot: options.root });
+  // Name the validated root when it was resolved implicitly, so a config-pinned
+  // root can never be validated invisibly. stderr keeps stdout script-safe.
+  if (!options.root) {
+    process.stderr.write(`check: validating ${root} (root resolved automatically; pass --root to override)\n`);
+  }
   assertProductNotBusy(root);
   const checkerArgs = [path.join(frameworkRoot, "scripts", "check-model.mjs"), "--root", root];
   if (options.base) checkerArgs.push("--base", path.resolve(options.base));
@@ -200,7 +316,8 @@ function executeChecker(args) {
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.status !== 0) {
     const diagnostic = result.stderr.trim();
-    throw new CliUsageError(`Validation failed for ${root}${diagnostic ? `:\n${diagnostic}` : ""}`);
+    if (!diagnostic) throw new CliUsageError(`Validation failed for ${root}`);
+    throw validationFailureError(root, diagnostic.split("\n"));
   }
   if (options["source-only"]) return;
   try {
@@ -222,7 +339,11 @@ function executeChecker(args) {
     throw new Error(`Failed to run the model graph SVG check for ${root}: ${svgCheck.error.message}`);
   }
   if (svgCheck.status !== 0) {
-    const diagnostic = (svgCheck.stderr || "").trim() || "generated/graph/model-graph.svg is missing or stale";
+    // The standalone gate prints its own regenerate remedy; strip it here so
+    // the remedy appears exactly once, in the Next: line below.
+    const diagnostic =
+      (svgCheck.stderr || "").trim().replace(/; run ddduck generate --root [^\n]*/g, "") ||
+      "generated/graph/model-graph.svg is missing or stale";
     throw new CliUsageError(`Validation failed for ${root}: ${diagnostic}`, {
       nextAction: `Run ddduck generate --root ${root}, then re-run ddduck check.`,
     });
@@ -238,6 +359,12 @@ function executeChecker(args) {
   }
 }
 
+/**
+ * Implement `ddduck generate`: refresh every generated view through the locked
+ * staged operation runner with an empty (no canonical replacement) plan.
+ * @param {string[]} args - Arguments after the `generate` command word.
+ * @returns {void}
+ */
 function generate(args) {
   const { options } = parseCommandArgs(args, { options: { root: { value: true }, json: { value: false } } });
   const root = resolveProductRoot({ explicitRoot: options.root });
@@ -248,6 +375,46 @@ function generate(args) {
   writeProductOperationResult(result, options.json);
 }
 
+function createNode(args) {
+  const kind = args[0];
+  const shared = { root: { value: true }, json: { value: false } };
+  const fields =
+    kind === "use-case"
+      ? { file: { value: true } }
+      : {
+          id: { value: true },
+          name: { value: true },
+          purpose: { value: true },
+          ...(kind === "concept" ? { owner: { value: true } } : {}),
+        };
+  const { options } = parseCommandArgs(args, {
+    positionals: { min: 1, max: 1 },
+    options: { ...shared, ...fields },
+  });
+  const required = (field) => requiredOption(options, field, `create ${kind} requires --${field} <value>`);
+  const request =
+    kind === "use-case"
+      ? { kind: "UseCase", node: parseYamlMapping(path.resolve(required("file"))) }
+      : {
+          kind: kind === "domain" ? "Domain" : "Concept",
+          id: required("id"),
+          name: required("name"),
+          purpose: required("purpose"),
+          ...(kind === "concept" ? { ownerDomain: required("owner") } : {}),
+        };
+  const root = resolveProductRoot({ explicitRoot: options.root });
+  const result = runProductOperation({ root, transform: (snapshot) => buildAuthoringPlan(snapshot, request) });
+  writeProductOperationResult(result, options.json);
+}
+
+/**
+ * Implement the guarantee lifecycle commands create, move, split, and retire:
+ * parse per-command options, require a registered decision for split/retire,
+ * and run the resulting plan through the staged operation runner.
+ * @param {"create"|"move"|"split"|"retire"} command - Lifecycle command name.
+ * @param {string[]} args - Arguments after the command word.
+ * @returns {void}
+ */
 function transitionGuarantee(command, args) {
   const optionDefinitions = {
     create: {
@@ -307,6 +474,12 @@ function requireRegisteredDecision(root, decision, command) {
   );
 }
 
+/**
+ * Print an operation result as one text line or one JSON object (--json).
+ * @param {{operation: string, root: string, affectedIds: string[], canonicalPaths: string[], generatedPaths: string[], configPath?: string}} result - Result from the operation runner or init.
+ * @param {boolean} json - Emit JSON instead of the text form.
+ * @returns {void}
+ */
 function writeProductOperationResult(result, json) {
   if (json) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -314,11 +487,21 @@ function writeProductOperationResult(result, json) {
   }
   const affected = result.affectedIds.length > 0 ? ` ${result.affectedIds.join(", ")}` : "";
   const canonical = result.canonicalPaths.length > 0 ? result.canonicalPaths.join(", ") : "none";
+  const config = result.configPath ? `; config: ${result.configPath} (created)` : "";
   process.stdout.write(
-    `${result.operation}${affected} in ${result.root}; canonical: ${canonical}; generated: ${result.generatedPaths.join(", ")}\n`,
+    `${result.operation}${affected} in ${result.root}; canonical: ${canonical}; generated: ${result.generatedPaths.join(", ")}${config}\n`,
   );
 }
 
+/**
+ * Build the operation plan for one guarantee lifecycle command from a frozen
+ * product snapshot; move/split/retire require the source guarantee to be active.
+ * @param {"create"|"move"|"split"|"retire"} command - Lifecycle command name.
+ * @param {{nodes: object[], canonicalPaths: Record<string, string>}} snapshot - Frozen staged product snapshot.
+ * @param {string|undefined} id - Target guarantee ID (absent for create).
+ * @param {Record<string, string|boolean>} options - Parsed command options.
+ * @returns {{operation: string, affectedIds: string[], replacements: {path: string, value: object}[]}} Plan for the operation runner.
+ */
 function buildGuaranteePlan(command, snapshot, id, options) {
   if (command === "create") return createGuarantee(snapshot, options);
   const guarantee = requireGuarantee(snapshot, id);
@@ -395,10 +578,14 @@ function moveGuarantee(snapshot, guarantee, destinationDomain) {
   if (guarantee.ownerDomain === destinationDomain)
     throw new Error(`${guarantee.id} is already owned by ${destinationDomain}`);
   const previousOwner = guarantee.ownerDomain;
+  // ownershipHistory lists former owning Domains only (model-reference.md), so
+  // an owner that regains the guarantee leaves the history again.
   const updated = {
     ...guarantee,
     ownerDomain: destinationDomain,
-    ownershipHistory: [...new Set([...(guarantee.ownershipHistory ?? []), previousOwner])],
+    ownershipHistory: [...new Set([...(guarantee.ownershipHistory ?? []), previousOwner])].filter(
+      (domainId) => domainId !== destinationDomain,
+    ),
   };
   return {
     operation: "move guarantee",
@@ -517,10 +704,16 @@ function writeYaml(filePath, value) {
   writeFileSync(filePath, stringify(value));
 }
 
+/**
+ * Write .ddduck/config.json at the repository root selecting the new product
+ * root, unless a config already exists (then it is left untouched).
+ * @param {string} destination - Absolute path of the freshly published product root.
+ * @returns {{configPath: string, repositoryRoot: string, created: boolean}} Where the config lives and whether it was created.
+ */
 function writeConfigIfAbsent(destination) {
   const repositoryRoot = findRepositoryRoot(destination);
   const configPath = path.join(repositoryRoot, ".ddduck", "config.json");
-  if (existsSync(configPath)) return;
+  if (existsSync(configPath)) return { configPath, repositoryRoot, created: false };
   const relativeProductRoot = path.relative(repositoryRoot, destination).split(path.sep).join("/");
   // findRepositoryRoot falls back to the destination itself when no enclosing
   // .git exists, which makes the relative path empty; "." keeps productRoot
@@ -531,6 +724,7 @@ function writeConfigIfAbsent(destination) {
     configPath,
     `${JSON.stringify({ schemaVersion: "1", productRoot, ignore: [...defaultConfigIgnore] }, null, 2)}\n`,
   );
+  return { configPath, repositoryRoot, created: true };
 }
 
 function nextActionFor(args) {

package/scripts/generate-agent-readiness-report.mjs

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 
+/**
+ * CLI wrapper for the agent-readiness report (`--root <product-root>`):
+ * delegates to lib/agent-readiness-report.mjs and prints the JSON report of
+ * missing evidence roles, unresolved references, stale generated views,
+ * orphaned nodes, and ambiguous ownership. Exits 1 when validation failed
+ * (report reduced to unresolvedReferences) or on any error.
+ */
+
 import path from "node:path";
 import { generateAgentReadinessReport } from "./lib/agent-readiness-report.mjs";
 

package/scripts/generate-docs.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
+/**
+ * Renders the generated Markdown view generated/docs/model-overview.md from a
+ * product root's canonical YAML: domains with their concepts, interfaces, and
+ * active guarantees, then use cases, interfaces, relationships, and decisions.
+ * Inactive (split/retired) guarantees are excluded. buildModelOverview feeds
+ * the freshness gate (check-generated-docs.mjs); writeModelOverview is called
+ * by init and the staged operation runner. Also runnable standalone via --root.
+ */
+
 import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,12 +18,22 @@ import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
 const outputPath = path.join("generated", "docs", "model-overview.md");
 
+/**
+ * Build the model overview Markdown for a product root without writing it.
+ * @param {string} rootPath - Product root path.
+ * @returns {string} The full generated Markdown document.
+ */
 export function buildModelOverview(rootPath) {
   const layout = detectProductLayout(rootPath);
   const graph = loadGraph(layout);
   return renderModelOverview(assembleModelView(graph, findModelId(graph)));
 }
 
+/**
+ * Write generated/docs/model-overview.md below the product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {string} The root-relative path that was written.
+ */
 export function writeModelOverview(rootPath) {
   const output = buildModelOverview(rootPath);
   const absoluteOutputPath = resolveContainedOutput(rootPath, outputPath);
@@ -30,6 +49,14 @@ function loadGraph(layout) {
   };
 }
 
+/**
+ * Assemble the sorted, resolved view of the model that the renderer consumes:
+ * domains with their owned nodes resolved, relationships, decisions, use
+ * cases, and every DomainInterface in the product.
+ * @param {{nodes: Map<string, object>}} graph - Loaded product nodes (active guarantees only).
+ * @param {string} modelId - ID of the single Model node.
+ * @returns {{model: object, domains: object[], relationships: object[], decisions: string[], useCases: object[], interfaces: object[]}} The renderable view.
+ */
 function assembleModelView(graph, modelId) {
   const model = resolveNode(graph, modelId);
   const domains = asArray(model.domains)
@@ -62,8 +89,7 @@ function renderModelOverview(view) {
     "",
     `# ${view.model.name} (\`${view.model.id}\`)`,
     "",
-    `Name status: \`${view.model.nameStatus ?? "stable"}\``,
-    "",
+    ...(view.model.nameStatus === undefined ? [] : [`Name status: \`${view.model.nameStatus}\``, ""]),
     view.model.purpose,
     "",
     "## Domains",
@@ -111,7 +137,7 @@ function renderModelOverview(view) {
   lines.push("## Decisions", "");
   for (const decision of view.decisions) lines.push(`- \`${decision}\``);
   lines.push("");
-  return lines.join("\n");
+  return `${lines.join("\n").trimEnd()}\n`;
 }
 
 function renderNodeList(lines, title, nodes) {

package/scripts/generate-graph-svg.mjs

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 
-// Experimental: render generated/graph/model-graph.json to an SVG using the
-// Graphviz WASM engine (@hpcc-js/wasm). Pure JS + WASM, no system binary, so it
-// stays offline and deterministic. A hosted render API (e.g. Kroki) is a
-// possible future fallback but is intentionally not the default.
+/**
+ * Renders generated/graph/model-graph.json to the canonical SVG view
+ * generated/graph/model-graph.svg using the Graphviz WASM engine
+ * (@hpcc-js/wasm): pure JS + WASM, no system binary, so it stays offline and
+ * deterministic. Because rendering is async, init, the operation runner, check,
+ * and query all invoke this script as a child process. Experimental layout
+ * variants (--layout/--all-layouts) land under .ddduck/graph-layouts/, outside
+ * the generated-view contract. A hosted render API (e.g. Kroki) is a possible
+ * future fallback but is intentionally not the default.
+ */
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -15,7 +21,8 @@ export const jsonInputPath = path.join("generated", "graph", "model-graph.json")
 
 // Graphviz layout engines worth comparing for a model graph. `dot` is the
 // hierarchical default; the force-directed and radial engines often read better
-// once the ownership tree gets wide. Output goes to `model-graph.<engine>.svg`.
+// once the ownership tree gets wide. Variant output goes to
+// `.ddduck/graph-layouts/model-graph.<engine>.svg`.
 export const LAYOUT_ENGINES = ["dot", "twopi", "circo", "fdp", "sfdp", "neato"];
 
 // Only `dot` and `fdp` do cluster-aware layout. The other engines still *draw*
@@ -32,8 +39,13 @@ export function engineSupportsClusters(engine) {
 export const svgOutputPath = path.join("generated", "graph", "model-graph.svg");
 export const canonicalEngine = "dot";
 
+// Experimental layout variants (`--layout` / `--all-layouts`) are not part of
+// the generated-view contract: `generated/` holds only the canonical views that
+// `ddduck generate` refreshes and `ddduck check` gates. Variants land in the
+// `.ddduck/` tool-metadata area instead, so they can never rot unswept inside
+// `generated/`.
 export function svgOutputPathFor(engine) {
-  return path.join("generated", "graph", `model-graph.${engine}.svg`);
+  return path.join(".ddduck", "graph-layouts", `model-graph.${engine}.svg`);
 }
 
 // Visual vocabulary keyed by the graph's node/edge `kind`. Shapes and fills are
@@ -214,9 +226,14 @@ function edgeStatements(graphEdge, nodeIds) {
   return [edge(graphEdge.from, graphEdge.to, { ...base, label: graphEdge.label ?? graphEdge.kind })];
 }
 
-// Pure translation from the model graph JSON to a deterministic DOT string.
-// `clusters` groups each domain and its owned nodes into a titled box; disable it
-// for engines that draw but do not lay out clusters (they would overlap).
+/**
+ * Pure translation from the model graph JSON to a deterministic DOT string.
+ * `clusters` groups each domain and its owned nodes into a titled box; disable
+ * it for engines that draw but do not lay out clusters (they would overlap).
+ * @param {{modelId?: string, modelName?: string, nodes?: object[], edges?: object[]}} modelGraph - Parsed model-graph.json.
+ * @param {{clusters?: boolean, legend?: boolean}} [options] - Cluster domains into boxes; emit the legend cluster.
+ * @returns {string} The DOT source.
+ */
 export function graphToDot(modelGraph, { clusters = true, legend = clusters } = {}) {
   const nodes = modelGraph.nodes ?? [];
   const edges = modelGraph.edges ?? [];
@@ -254,9 +271,14 @@ function loadGraphviz() {
   return graphvizInstance;
 }
 
-// Render a DOT string to SVG via the Graphviz WASM engine. `engine` selects the
-// layout algorithm. Isolated so the backend can be swapped without touching the
-// translation above.
+/**
+ * Render a DOT string to SVG via the Graphviz WASM engine. `engine` selects
+ * the layout algorithm. Isolated so the backend can be swapped without
+ * touching the translation above.
+ * @param {string} dot - DOT source from graphToDot.
+ * @param {string} [engine] - One of LAYOUT_ENGINES (default "dot").
+ * @returns {Promise<string>} The rendered SVG.
+ */
 export async function renderDotToSvg(dot, engine = "dot") {
   if (!LAYOUT_ENGINES.includes(engine)) {
     throw new Error(`unknown layout engine ${engine}; expected one of ${LAYOUT_ENGINES.join(", ")}`);
@@ -281,13 +303,22 @@ function writeSvg(rootPath, relativePath, svg) {
   return relativePath;
 }
 
-// Build the canonical diagram bytes (dot, clustered, legend). Shared by the
-// writer and the freshness check so both agree byte-for-byte.
+/**
+ * Build the canonical diagram bytes (dot, clustered, legend). Shared by the
+ * writer and the freshness check so both agree byte-for-byte.
+ * @param {object} modelGraph - Parsed model-graph.json.
+ * @returns {Promise<string>} The canonical SVG bytes.
+ */
 export async function buildModelGraphSvg(modelGraph) {
   const dot = graphToDot(modelGraph, { clusters: true, legend: true });
   return renderDotToSvg(dot, canonicalEngine);
 }
 
+/**
+ * Write the canonical generated/graph/model-graph.svg below the product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {Promise<string>} The root-relative path that was written.
+ */
 export async function writeModelGraphSvgCanonical(rootPath) {
   const svg = await buildModelGraphSvg(readModelGraph(rootPath));
   return writeSvg(rootPath, svgOutputPath, svg);
@@ -298,8 +329,14 @@ export async function writeModelGraphSvg(rootPath, engine = "dot") {
   return writeSvg(rootPath, svgOutputPathFor(engine), await renderDotToSvg(dot, engine));
 }
 
-// Render one SVG per layout engine so the variants can be compared side by side.
-// Clusters are emitted only for the engines that lay them out (dot, fdp).
+/**
+ * Render one SVG per layout engine so the variants can be compared side by
+ * side. Clusters are emitted only for the engines that lay them out (dot,
+ * fdp). Variants go to .ddduck/graph-layouts/, not generated/.
+ * @param {string} rootPath - Product root path.
+ * @param {string[]} [engines] - Layout engines to render (default all LAYOUT_ENGINES).
+ * @returns {Promise<string[]>} The root-relative variant paths written.
+ */
 export async function writeModelGraphSvgVariants(rootPath, engines = LAYOUT_ENGINES) {
   const modelGraph = readModelGraph(rootPath);
   const writtenPaths = [];