@field/cascade 0.10.0 → 0.12.0

package/dist/cli/commands-PHYFYA3F.js

@@ -0,0 +1,1374 @@
+import {
+  sceneDocument
+} from "./chunk-73S4JZXK.js";
+import {
+  setEmbeddedCompiler,
+  setProjectModuleCompiler
+} from "./chunk-2KXB47FP.js";
+import {
+  installHeadlessCanvas
+} from "./chunk-EZRWJ4G2.js";
+import "./chunk-3RXL5GHB.js";
+import "./chunk-OM6BEME6.js";
+import {
+  composeContactSheet
+} from "./chunk-53LGFPWX.js";
+import {
+  RunTrace,
+  cookProjectGraph,
+  installProjectIo,
+  installProjectStages,
+  moduleId,
+  projectModuleFile
+} from "./chunk-MP653A5O.js";
+import "./chunk-MI5JLQYA.js";
+import "./chunk-GRIN2DDP.js";
+import "./chunk-X4WKAOQP.js";
+import "./chunk-DEQSEFFH.js";
+import "./chunk-RXDIMXN5.js";
+import "./chunk-QQPA2ZHH.js";
+import "./chunk-KH4MUBKF.js";
+import "./chunk-HSNOBIVT.js";
+import {
+  graphSeed
+} from "./chunk-L6B6FUQP.js";
+import "./chunk-HFHWYL55.js";
+import "./chunk-KBGUO27Q.js";
+import {
+  imagePath
+} from "./chunk-ICH7N5PN.js";
+import "./chunk-CO22XHNG.js";
+import "./chunk-LTXWBXOM.js";
+import "./chunk-BZ63XQ3I.js";
+import {
+  compileEmbedded,
+  compileProjectModule
+} from "./chunk-EU4ZFZ7Y.js";
+import "./chunk-YH637PDL.js";
+import "./chunk-X566FWBV.js";
+import "./chunk-WD62JIP6.js";
+import {
+  cascadeVersion
+} from "./chunk-5ORUQ6ES.js";
+import {
+  ProjectRoot
+} from "./chunk-2JEU3MGB.js";
+import "./chunk-NJFMDXHR.js";
+import "./chunk-J7VK7MNF.js";
+import "./chunk-FWMSGKEH.js";
+import "./chunk-JVOCK5W4.js";
+
+// src/cli/locks/commands.ts
+import path8 from "node:path";
+
+// src/cli/locks/lock.ts
+import { execFile as execFile2 } from "node:child_process";
+import fssync3 from "node:fs";
+import fs4 from "node:fs/promises";
+import os from "node:os";
+import path5 from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify as promisify2 } from "node:util";
+
+// src/cli/locks/cook.ts
+import path from "node:path";
+async function cookNode(graphFile, document, nodeId, options = {}) {
+  const project = new ProjectRoot(path.dirname(path.resolve(graphFile)));
+  const trace = new RunTrace(options.traceGraph ?? path.resolve(graphFile), cascadeVersion(), graphSeed(document));
+  setProjectModuleCompiler(async (folder) => (await compileProjectModule(project, folder)).code);
+  setEmbeddedCompiler(async (code) => (await compileEmbedded(project, code)).code);
+  const removeStages = installProjectStages(project, { verbose: options.verbose, onTrace: (stage) => trace.recordStage(stage) });
+  const removeIo = installProjectIo(project);
+  const canvas = await installHeadlessCanvas().catch(() => void 0);
+  const started = performance.now();
+  try {
+    const { outputs } = await cookProjectGraph(graphFile, document, nodeId, (graph) => trace.attach(graph));
+    const node = outputs.get(nodeId);
+    if (!node) throw new Error(`No node "${nodeId}" in the graph`);
+    let written;
+    try {
+      written = trace.write(options.traceRoot ?? project.root);
+    } catch (error) {
+      console.warn(`Could not write the run trace: ${error instanceof Error ? error.message : error}`);
+    }
+    return { outputs: node, durationMs: Math.round(performance.now() - started), ...written ? { trace: written } : {} };
+  } finally {
+    removeStages();
+    removeIo();
+    canvas?.dispose();
+    setProjectModuleCompiler(null);
+    setEmbeddedCompiler(null);
+  }
+}
+
+// src/cli/locks/fingerprint.ts
+import fssync from "node:fs";
+import fs2 from "node:fs/promises";
+import path3 from "node:path";
+
+// src/cli/locks/store.ts
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path2 from "node:path";
+var OBJECTS_DIR = path2.join(".cascade", "objects");
+function digest(bytes) {
+  return `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+}
+async function digestFile(file) {
+  return digest(await fs.readFile(file));
+}
+function objectPath(projectRoot, id) {
+  const hex = id.slice("sha256:".length);
+  if (!/^[0-9a-f]{64}$/.test(hex)) throw new Error(`Not an object id: ${id}`);
+  return path2.join(projectRoot, OBJECTS_DIR, hex.slice(0, 2), hex.slice(2));
+}
+async function putObject(projectRoot, bytes) {
+  const id = digest(bytes);
+  const file = objectPath(projectRoot, id);
+  try {
+    await fs.access(file);
+    return id;
+  } catch {
+  }
+  await fs.mkdir(path2.dirname(file), { recursive: true });
+  const partial = `${file}.${process.pid}.partial`;
+  await fs.writeFile(partial, bytes);
+  await fs.rename(partial, file);
+  return id;
+}
+async function getObject(projectRoot, id) {
+  let bytes;
+  try {
+    bytes = await fs.readFile(objectPath(projectRoot, id));
+  } catch {
+    throw new Error(`Object ${short(id)} is missing from ${OBJECTS_DIR}/ \u2014 was .cascade/objects committed with the lock?`);
+  }
+  if (digest(bytes) !== id) throw new Error(`Object ${short(id)} is corrupt: its bytes no longer hash to its name`);
+  return bytes;
+}
+function short(id) {
+  return id.replace(/^sha256:/, "").slice(0, 12);
+}
+function stableJson(value, leading = []) {
+  const sorted = sortKeys(value);
+  if (!leading.length || !sorted || typeof sorted !== "object" || Array.isArray(sorted)) {
+    return `${JSON.stringify(sorted, null, 2)}
+`;
+  }
+  const ordered = {};
+  for (const key of leading) if (key in sorted) ordered[key] = sorted[key];
+  for (const [key, entry] of Object.entries(sorted)) if (!(key in ordered)) ordered[key] = entry;
+  return `${JSON.stringify(ordered, null, 2)}
+`;
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object" && !ArrayBuffer.isView(value)) {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry !== void 0) sorted[key] = sortKeys(entry);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+// src/cli/locks/fingerprint.ts
+var RASTER = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".webp", ".tif", ".tiff"]);
+var TEXT = /* @__PURE__ */ new Set([".svg", ".json", ".txt", ".csv", ".xml"]);
+async function fingerprintOutputs(context, outputs, ports) {
+  const result = {};
+  const names = ports?.length ? ports : [...outputs.keys()].sort();
+  for (const port of names) {
+    if (!outputs.has(port)) throw new Error(`The node has no output named "${port}" (it has: ${[...outputs.keys()].join(", ")})`);
+    result[port] = await fingerprintValue(context, outputs.get(port));
+  }
+  return result;
+}
+async function fingerprintValue(context, value) {
+  const file = await existingFile(context, value);
+  if (file) return fingerprintFile(context, file.absolute, file.relative);
+  const json = normalize(context.projectRoot, JSON.stringify(plain(value)) ?? "undefined");
+  return { kind: "value", sha256: digest(json), ...json.length <= 200 ? { value: JSON.parse(json === "undefined" ? "null" : json) } : {} };
+}
+async function existingFile(context, value) {
+  const named = imagePath(value);
+  if (!named || named.length > 1024 || /^[a-z]+:/i.test(named) || named.includes("\n")) return null;
+  const relative = named.replace(/^\.?\//, "");
+  try {
+    const absolute = path3.isAbsolute(named) ? named : context.resolve(relative);
+    if ((await fs2.stat(absolute)).isFile()) return { absolute, relative };
+  } catch {
+  }
+  return null;
+}
+async function fingerprintFile(context, absolute, relative) {
+  const extension = path3.extname(absolute).toLowerCase();
+  let bytes = await fs2.readFile(absolute);
+  if (TEXT.has(extension)) bytes = Buffer.from(normalize(context.projectRoot, bytes.toString("utf8")));
+  const base = { kind: "file", path: relative, sha256: digest(bytes), bytes: bytes.length };
+  if (!RASTER.has(extension)) return base;
+  const { default: sharp } = await import("sharp");
+  const { data, info } = await sharp(absolute, { limitInputPixels: false }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return { ...base, pixels: digest(data), width: info.width, height: info.height };
+}
+function plain(value) {
+  if (ArrayBuffer.isView(value)) return Array.from(value);
+  if (value instanceof Map) return Object.fromEntries([...value].map(([key, entry]) => [String(key), plain(entry)]));
+  if (Array.isArray(value)) return value.map(plain);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, plain(entry)]));
+  }
+  return value;
+}
+function normalize(projectRoot, text) {
+  let out = text;
+  for (const root of /* @__PURE__ */ new Set([projectRoot, safeRealpath(projectRoot)])) out = out.split(root).join("<project>");
+  return out;
+}
+function safeRealpath(file) {
+  try {
+    return fssync.realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+function compareFingerprints(expected, actual) {
+  const differences = [];
+  for (const port of Object.keys(expected).sort()) {
+    const want = expected[port];
+    const got = actual[port];
+    if (!got) {
+      differences.push({ port, expected: describe(want), actual: "nothing" });
+      continue;
+    }
+    const same = want.kind === "file" && got.kind === "file" && want.pixels && got.pixels ? want.pixels === got.pixels : want.sha256 === got.sha256;
+    if (!same) differences.push({ port, expected: describe(want), actual: describe(got) });
+  }
+  return differences;
+}
+function describe(fingerprint) {
+  if (fingerprint.kind === "value") {
+    return fingerprint.value !== void 0 ? `${JSON.stringify(fingerprint.value)} (${short(fingerprint.sha256)})` : `value ${short(fingerprint.sha256)}`;
+  }
+  const size = fingerprint.width ? ` ${fingerprint.width}x${fingerprint.height}` : "";
+  const pixels = fingerprint.pixels ? `, pixels ${short(fingerprint.pixels)}` : "";
+  return `file ${short(fingerprint.sha256)}${size}${pixels}, ${fingerprint.bytes} bytes`;
+}
+
+// src/cli/locks/snapshot.ts
+import { execFile } from "node:child_process";
+import fssync2 from "node:fs";
+import fs3 from "node:fs/promises";
+import path4 from "node:path";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".svelte",
+  ".py",
+  ".wgsl",
+  ".glsl",
+  ".vert",
+  ".frag",
+  ".json"
+]);
+var MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+var NEVER = /* @__PURE__ */ new Set([".git", ".cascade", ".cascade-cache", "locks", "ladders", "node_modules", "__pycache__"]);
+async function collectSources(projectRoot) {
+  const files = /* @__PURE__ */ new Map();
+  const skipped = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = async (directory, prefix) => {
+    const real = await fs3.realpath(directory);
+    if (visited.has(real)) return;
+    visited.add(real);
+    for (const relative of await listCandidates(real)) {
+      const name = path4.posix.join(prefix, relative);
+      if (name.split("/").some((part) => NEVER.has(part))) continue;
+      const absolute = path4.join(real, relative);
+      let stat;
+      try {
+        stat = await fs3.stat(absolute);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        await visit(absolute, name);
+        continue;
+      }
+      if (!stat.isFile() || !isSource(name)) continue;
+      if (stat.size > MAX_SOURCE_BYTES) skipped.push(name);
+      else files.set(name, absolute);
+    }
+  };
+  await visit(projectRoot, "");
+  return { files, skipped: skipped.sort() };
+}
+function isSource(name) {
+  if (name.endsWith(".cascade")) return false;
+  return SOURCE_EXTENSIONS.has(path4.posix.extname(name).toLowerCase());
+}
+async function listCandidates(directory) {
+  try {
+    const { stdout } = await run("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+      cwd: directory,
+      maxBuffer: 64 * 1024 * 1024
+    });
+    return [...new Set(stdout.split("\0").filter(Boolean))];
+  } catch {
+    const found = [];
+    const walk = async (relative) => {
+      for (const entry of await fs3.readdir(path4.join(directory, relative), { withFileTypes: true })) {
+        if (entry.name.startsWith(".") || NEVER.has(entry.name) || entry.name === "venv") continue;
+        const name = relative ? `${relative}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) await walk(name);
+        else found.push(name);
+      }
+    };
+    await walk("");
+    return found;
+  }
+}
+async function hashSources(sources) {
+  const tree = {};
+  for (const name of [...sources.files.keys()].sort()) tree[name] = await digestFile(sources.files.get(name));
+  return tree;
+}
+async function storeSources(projectRoot, sources) {
+  const tree = {};
+  for (const name of [...sources.files.keys()].sort()) {
+    tree[name] = await putObject(projectRoot, await fs3.readFile(sources.files.get(name)));
+  }
+  const id = await putObject(projectRoot, stableJson({ format: "cascade.tree", version: 1, files: tree }, ["format", "version"]));
+  return { id, tree };
+}
+async function readTree(projectRoot, id) {
+  const parsed = JSON.parse((await getObject(projectRoot, id)).toString("utf8"));
+  if (parsed?.format !== "cascade.tree") throw new Error(`Object ${id} is not a source tree`);
+  return parsed.files;
+}
+function diffTrees(locked, other) {
+  const changed = [];
+  const removed = [];
+  for (const [name, id] of Object.entries(locked)) {
+    if (!(name in other)) removed.push(name);
+    else if (other[name] !== id) changed.push(name);
+  }
+  const added = Object.keys(other).filter((name) => !(name in locked));
+  return { changed: changed.sort(), added: added.sort(), removed: removed.sort() };
+}
+async function materialize(projectRoot, tree, into) {
+  await fs3.mkdir(into, { recursive: true });
+  const target = await fs3.realpath(into);
+  const tops = new Set(Object.keys(tree).map((name) => name.split("/")[0]));
+  for (const entry of await fs3.readdir(projectRoot, { withFileTypes: true })) {
+    if (NEVER.has(entry.name) && entry.name !== "node_modules") continue;
+    const source = path4.join(projectRoot, entry.name);
+    const destination = path4.join(target, entry.name);
+    const environment = (entry.name.startsWith(".") || entry.name === "node_modules") && !tops.has(entry.name);
+    if (environment) await fs3.symlink(source, destination);
+    else await cloneInto(await fs3.realpath(source), destination);
+  }
+  const live = await collectSources(projectRoot);
+  for (const name of live.files.keys()) {
+    if (!(name in tree)) await fs3.rm(path4.join(target, name), { force: true });
+  }
+  for (const [name, id] of Object.entries(tree)) {
+    const file = path4.join(target, name);
+    await fs3.mkdir(path4.dirname(file), { recursive: true });
+    const parent = await fs3.realpath(path4.dirname(file));
+    if (parent !== target && !parent.startsWith(target + path4.sep)) {
+      throw new Error(`Refusing to restore ${name}: its folder resolves outside the replay copy (${parent})`);
+    }
+    await fs3.rm(file, { force: true });
+    await fs3.writeFile(file, await getObject(projectRoot, id));
+  }
+}
+async function cloneInto(source, destination) {
+  if (process.platform === "darwin") {
+    await run("cp", ["-c", "-R", source, destination]);
+    return;
+  }
+  await fs3.cp(source, destination, { recursive: true, verbatimSymlinks: true, mode: fssync2.constants.COPYFILE_FICLONE });
+}
+
+// src/cli/locks/lock.ts
+var run2 = promisify2(execFile2);
+var LOCKS_DIR = "locks";
+var PREVIEW_SIZE = 800;
+var LOCK_KEY_ORDER = ["format", "version", "id", "name", "status", "note", "supersedes", "created", "graph"];
+async function createLock(options) {
+  const graphFile = path5.resolve(options.graph);
+  const root = path5.dirname(graphFile);
+  const project = new ProjectRoot(root);
+  const id = lockId(options.name);
+  await checkLockId(root, id, options.supersedes);
+  const graphBytes = await fs4.readFile(graphFile);
+  let document = JSON.parse(graphBytes.toString("utf8"));
+  let scene;
+  if (options.scene) {
+    const applied = await sceneDocument(graphFile, options.scene);
+    for (const warning of applied.warnings) console.error(`Warning: ${warning}`);
+    document = applied.document;
+    scene = { file: displayPath(root, path5.resolve(options.scene)), object: await putObject(root, await fs4.readFile(options.scene)) };
+  }
+  if (options.seed !== void 0) document.seed = options.seed;
+  const graphObject = options.scene || options.seed !== void 0 ? await putObject(root, `${JSON.stringify(document, null, 2)}
+`) : await putObject(root, graphBytes);
+  if (!document.nodes?.some((node) => node.id === options.node)) {
+    throw new Error(`No node "${options.node}" in ${path5.basename(graphFile)}`);
+  }
+  const sources = await collectSources(root);
+  const { id: treeId, tree } = await storeSources(root, sources);
+  const inputs = await hashInputs(project, document, options.inputs ?? []);
+  const cooked = options.live ? await cookIn(root, graphFile, document, options) : await cookInCopy(root, tree, path5.relative(root, graphFile), document, options, `lock-${id}`);
+  const preview = await writePreview(root, id, options.preview ? path5.resolve(options.preview) : firstRaster(cooked.root, cooked.ports));
+  if (cooked.dispose) await cooked.dispose();
+  const lock = {
+    format: "cascade.lock",
+    version: 1,
+    id,
+    name: options.name,
+    status: options.status ?? "approved",
+    ...options.note ? { note: options.note } : {},
+    ...options.supersedes ? { supersedes: options.supersedes } : {},
+    created: (/* @__PURE__ */ new Date()).toISOString(),
+    graph: { file: relativeTo(root, graphFile), node: options.node, object: graphObject, ...scene ? { scene } : {} },
+    params: graphParams(document),
+    ...publishedParams(document) ? { published: publishedParams(document) } : {},
+    seeds: graphSeeds(document),
+    inputs,
+    code: {
+      tree: treeId,
+      files: Object.keys(tree).length,
+      ...sources.skipped.length ? { skipped: sources.skipped } : {},
+      modules: await moduleHashes(root, document, tree),
+      ...await stageHashes(root, tree)
+    },
+    versions: {
+      cascade: await cascadeVersion2(),
+      project: await projectVersion(root),
+      node: process.version
+    },
+    host: { kind: "headless", platform: `${process.platform}-${process.arch}`, cooked: options.live ? "live" : "snapshot" },
+    output: { ports: cooked.ports, durationMs: cooked.durationMs, ...cooked.trace ? { trace: cooked.trace } : {} },
+    ...preview ? { preview } : {}
+  };
+  return { lock, file: await writeLock(root, lock) };
+}
+async function writeLock(root, lock) {
+  const lockFile = path5.join(root, LOCKS_DIR, `${lock.id}.json`);
+  await fs4.mkdir(path5.dirname(lockFile), { recursive: true });
+  try {
+    await fs4.writeFile(lockFile, stableJson(lock, LOCK_KEY_ORDER), { flag: "wx" });
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      throw new Error(`${path5.relative(process.cwd(), lockFile)} exists. A lock is never rewritten; make a new one with --supersedes ${lock.id}`);
+    }
+    throw error;
+  }
+  return lockFile;
+}
+async function checkLockId(root, id, supersedes) {
+  const lockFile = path5.join(root, LOCKS_DIR, `${id}.json`);
+  if (await exists(lockFile)) {
+    throw new Error(`${path5.relative(process.cwd(), lockFile)} exists. A lock is never rewritten; make a new one with --supersedes ${id}`);
+  }
+  if (supersedes && !await exists(path5.join(root, LOCKS_DIR, `${supersedes}.json`))) {
+    throw new Error(`--supersedes ${supersedes}: no such lock in ${LOCKS_DIR}/`);
+  }
+}
+async function replayLock(projectRoot, lock, options = {}) {
+  const root = path5.resolve(projectRoot);
+  const project = new ProjectRoot(root);
+  const document = JSON.parse((await getObject(root, lock.graph.object)).toString("utf8"));
+  const tree = await readTree(root, lock.code.tree);
+  const inputsChanged = await changedInputs(project, lock.inputs);
+  if (inputsChanged.length && !options.allowInputChange) {
+    throw new Error([
+      `${lock.id}: ${inputsChanged.length} input ${inputsChanged.length === 1 ? "file has" : "files have"} changed since the lock, so the replay could not reproduce it:`,
+      ...inputsChanged.map((change) => `  ${change.path}: locked ${short(change.expected)}, now ${change.actual === "missing" ? "missing" : short(change.actual)}`),
+      "Restore the inputs, or pass --allow-input-change to replay anyway."
+    ].join("\n"));
+  }
+  const warnings = versionWarnings(lock, await cascadeVersion2());
+  const live = await hashSources(await collectSources(root));
+  const codeSinceLock = diffTrees(tree, live);
+  const graphFile = path5.join(root, lock.graph.file);
+  const ports = Object.keys(lock.output.ports);
+  const cooked = options.live ? await cookIn(root, graphFile, document, { node: lock.graph.node, ports, verbose: options.verbose }) : await cookInCopy(root, tree, lock.graph.file, document, { node: lock.graph.node, ports, verbose: options.verbose }, `replay-${lock.id}`);
+  try {
+    const differences = compareFingerprints(lock.output.ports, cooked.ports);
+    const files = [];
+    if (options.out) {
+      const out = path5.resolve(options.out);
+      await fs4.mkdir(out, { recursive: true });
+      for (const [port, fingerprint] of Object.entries(cooked.ports)) {
+        if (fingerprint.kind !== "file") continue;
+        const target = path5.join(out, `${lock.id}.${port}${path5.extname(fingerprint.path)}`);
+        await fs4.copyFile(cooked.resolve(fingerprint.path), target);
+        files.push(target);
+      }
+    }
+    return {
+      id: lock.id,
+      name: lock.name,
+      status: differences.length ? "mismatch" : "match",
+      cooked: options.live ? "live" : "snapshot",
+      differences,
+      ports: cooked.ports,
+      inputsChanged,
+      codeSinceLock,
+      warnings,
+      durationMs: cooked.durationMs,
+      ...cooked.trace ? { trace: cooked.trace } : {},
+      files,
+      ...options.keep && !options.live ? { kept: cooked.root } : {}
+    };
+  } finally {
+    if (cooked.dispose && !options.keep) await cooked.dispose();
+  }
+}
+async function readLock(projectRoot, idOrFile) {
+  const asFile = path5.resolve(idOrFile);
+  const file = idOrFile.endsWith(".json") && fssync3.existsSync(asFile) ? asFile : path5.join(path5.resolve(projectRoot), LOCKS_DIR, `${idOrFile}.json`);
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs4.readFile(file, "utf8"));
+  } catch {
+    throw new Error(`No lock "${idOrFile}" (looked for ${path5.relative(process.cwd(), file) || file})`);
+  }
+  if (parsed?.format !== "cascade.lock") throw new Error(`${file} is not a Cascade lock`);
+  return { lock: parsed, root: path5.dirname(path5.dirname(file)) };
+}
+async function listLocks(projectRoot) {
+  const directory = path5.join(path5.resolve(projectRoot), LOCKS_DIR);
+  let names;
+  try {
+    names = await fs4.readdir(directory);
+  } catch {
+    return [];
+  }
+  const locks = [];
+  for (const name of names.filter((entry) => entry.endsWith(".json")).sort()) {
+    try {
+      const parsed = JSON.parse(await fs4.readFile(path5.join(directory, name), "utf8"));
+      if (parsed?.format === "cascade.lock") locks.push(parsed);
+    } catch {
+    }
+  }
+  return locks.sort((a, b) => a.created.localeCompare(b.created) || a.id.localeCompare(b.id));
+}
+async function cookIn(root, graphFile, document, options) {
+  const project = new ProjectRoot(root);
+  const { outputs, durationMs, trace } = await cookNode(graphFile, document, options.node, options);
+  const resolve = (relative) => project.resolveMedia(relative);
+  const ports = await fingerprintOutputs({ projectRoot: root, resolve }, outputs, options.ports);
+  return { root, ports, durationMs, resolve, ...trace ? { trace } : {} };
+}
+async function cookInCopy(root, tree, graphRelative, document, options, label) {
+  const copy = await openCopy(root, tree, label);
+  try {
+    return { ...await copy.cook(graphRelative, document, options), dispose: copy.dispose };
+  } catch (error) {
+    await copy.dispose();
+    throw error;
+  }
+}
+async function openCopy(root, tree, label) {
+  const copy = await fs4.mkdtemp(path5.join(os.tmpdir(), `cascade-${label.replace(/[^A-Za-z0-9._-]/g, "_")}-`));
+  const dispose = () => fs4.rm(copy, { recursive: true, force: true });
+  try {
+    await materialize(root, tree, copy);
+  } catch (error) {
+    await dispose();
+    throw error;
+  }
+  const real = await fs4.realpath(copy);
+  return {
+    root: real,
+    dispose,
+    async cook(graphRelative, document, options) {
+      const graphFile = path5.join(real, graphRelative);
+      await fs4.rm(graphFile, { force: true });
+      await fs4.writeFile(graphFile, `${JSON.stringify(document, null, 2)}
+`);
+      return cookIn(real, graphFile, document, {
+        ...options,
+        traceRoot: root,
+        traceGraph: path5.join(root, graphRelative)
+      });
+    }
+  };
+}
+function lockId(name) {
+  const id = name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!id || id.startsWith(".")) throw new Error(`"${name}" does not make a usable lock id`);
+  return id;
+}
+function compact(value) {
+  const json = JSON.stringify(value);
+  return json !== void 0 && json.length > 200 ? digest(stableJson(value)) : value;
+}
+function graphParams(document) {
+  const params = {};
+  for (const node of document.nodes ?? []) {
+    for (const [prop, value] of Object.entries(node.props ?? {})) params[`${node.id}.${prop}`] = compact(value);
+  }
+  return params;
+}
+function publishedParams(document) {
+  const published = document.editor?.parameters;
+  if (!published?.length) return void 0;
+  const nodes = new Map((document.nodes ?? []).map((node) => [node.id, node]));
+  const values = {};
+  for (const parameter of published) values[parameter.id] = compact(nodes.get(parameter.node)?.props?.[parameter.prop] ?? null);
+  return values;
+}
+function graphSeeds(document) {
+  const seeds = { graph: graphSeed(document) };
+  for (const node of document.nodes ?? []) {
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+      if (/seed/i.test(prop)) seeds[`${node.id}.${prop}`] = value;
+    }
+  }
+  for (const parameter of document.editor?.parameters ?? []) {
+    if (parameter.control === "seed") {
+      seeds[`${parameter.node}.${parameter.prop}`] = document.nodes?.find((node) => node.id === parameter.node)?.props?.[parameter.prop] ?? null;
+    }
+  }
+  return seeds;
+}
+async function hashInputs(project, document, extra) {
+  const candidates = new Set(extra.map((file) => relativeTo(project.root, path5.resolve(file))));
+  const walk = (value) => {
+    if (typeof value === "string") {
+      if (value.length < 1024 && !value.includes("\n") && !/^[a-z]+:\/\//i.test(value) && /\.[A-Za-z0-9]{1,6}$/.test(value)) {
+        candidates.add(value.replace(/^\.?\//, ""));
+      }
+    } else if (Array.isArray(value)) value.forEach(walk);
+    else if (value && typeof value === "object") Object.values(value).forEach(walk);
+  };
+  for (const node of document.nodes ?? []) walk(node.props);
+  const inputs = {};
+  for (const candidate of [...candidates].sort()) {
+    const file = resolveInput(project, candidate);
+    if (!file) continue;
+    inputs[candidate] = await digestFile(file);
+  }
+  return inputs;
+}
+function resolveInput(project, relative) {
+  try {
+    const file = project.resolveMedia(relative);
+    return fssync3.statSync(file).isFile() ? file : null;
+  } catch {
+    return null;
+  }
+}
+async function changedInputs(project, inputs) {
+  const changes = [];
+  for (const [name, expected] of Object.entries(inputs)) {
+    const file = resolveInput(project, name);
+    const actual = file ? await digestFile(file) : "missing";
+    if (actual !== expected) changes.push({ path: name, expected, actual });
+  }
+  return changes;
+}
+async function moduleHashes(root, document, tree) {
+  const modules = {};
+  for (const node of document.nodes ?? []) {
+    const id = moduleId(node);
+    if (!id || id in modules) continue;
+    const { file } = await projectModuleFile(root, node, id);
+    if (!file) continue;
+    const name = relativeTo(root, file);
+    modules[id] = tree[name] ?? await digestFile(file);
+  }
+  return modules;
+}
+async function stageHashes(root, tree) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await fs4.readFile(path5.join(root, "cascade.json"), "utf8"));
+  } catch {
+    return {};
+  }
+  const declared = manifest?.exec?.stages;
+  if (!declared) return {};
+  const stages = {};
+  for (const key of ["entrypoint", "worker"]) {
+    const name = typeof declared[key] === "string" ? declared[key].replace(/^\.\//, "") : void 0;
+    if (name && tree[name]) stages[name] = tree[name];
+  }
+  return Object.keys(stages).length ? { stages } : {};
+}
+function firstRaster(root, ports) {
+  for (const fingerprint of Object.values(ports)) {
+    if (fingerprint.kind === "file" && fingerprint.pixels) {
+      try {
+        return new ProjectRoot(root).resolveMedia(fingerprint.path);
+      } catch {
+      }
+    }
+  }
+  return void 0;
+}
+async function writePreview(root, id, source) {
+  if (!source) return void 0;
+  const { default: sharp } = await import("sharp");
+  const file = path5.join(LOCKS_DIR, `${id}.preview.png`);
+  const bytes = await sharp(source, { limitInputPixels: false }).resize(PREVIEW_SIZE, PREVIEW_SIZE, { fit: "inside", withoutEnlargement: true }).png({ compressionLevel: 9, palette: true }).toBuffer();
+  await fs4.mkdir(path5.join(root, LOCKS_DIR), { recursive: true });
+  await fs4.writeFile(path5.join(root, file), bytes);
+  return { file: file.split(path5.sep).join("/"), sha256: digest(bytes) };
+}
+async function git(cwd) {
+  try {
+    const { stdout: commit } = await run2("git", ["rev-parse", "HEAD"], { cwd });
+    const { stdout: status } = await run2("git", ["status", "--porcelain", "--untracked-files=no"], { cwd, maxBuffer: 16 * 1024 * 1024 });
+    return { commit: commit.trim(), dirty: status.trim().length > 0 };
+  } catch {
+    return {};
+  }
+}
+async function cascadeVersion2() {
+  let directory = path5.dirname(fileURLToPath(import.meta.url));
+  for (; ; ) {
+    try {
+      const manifest = JSON.parse(await fs4.readFile(path5.join(directory, "package.json"), "utf8"));
+      if (manifest.name === "@field/cascade") return { version: manifest.version, ...await git(directory) };
+    } catch {
+    }
+    const parent = path5.dirname(directory);
+    if (parent === directory) return {};
+    directory = parent;
+  }
+}
+async function projectVersion(root) {
+  let version;
+  try {
+    version = JSON.parse(await fs4.readFile(path5.join(root, "package.json"), "utf8")).version;
+  } catch {
+  }
+  return { ...version ? { version } : {}, ...await git(root) };
+}
+function versionWarnings(lock, current) {
+  const locked = lock.versions.cascade;
+  const warnings = [];
+  if (locked.version && current.version && locked.version !== current.version) {
+    warnings.push(`Locked with Cascade ${locked.version}, replaying with ${current.version}`);
+  } else if (locked.commit && current.commit && locked.commit !== current.commit) {
+    warnings.push(`Locked with Cascade at ${locked.commit.slice(0, 7)}, replaying at ${current.commit.slice(0, 7)}`);
+  }
+  if (lock.versions.node !== process.version) warnings.push(`Locked under Node ${lock.versions.node}, replaying under ${process.version}`);
+  return warnings;
+}
+function relativeTo(root, file) {
+  const relative = path5.relative(root, file);
+  if (relative.startsWith("..") || path5.isAbsolute(relative)) throw new Error(`${file} is outside the project (${root})`);
+  return relative.split(path5.sep).join("/");
+}
+function displayPath(root, file) {
+  const relative = path5.relative(root, file);
+  return relative.startsWith("..") || path5.isAbsolute(relative) ? file : relative.split(path5.sep).join("/");
+}
+async function exists(file) {
+  try {
+    await fs4.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/cli/locks/ladder.ts
+import fs5 from "node:fs/promises";
+import path6 from "node:path";
+var LADDERS_DIR = "ladders";
+var MAX_VARIANTS = 12;
+var LADDER_KEY_ORDER = ["format", "version", "id", "name", "note", "created", "graph", "vary", "seeds"];
+async function createLadder(options) {
+  const graphFile = path6.resolve(options.graph);
+  const root = path6.dirname(graphFile);
+  const project = new ProjectRoot(root);
+  const id = lockId(options.name);
+  const ladderFile = path6.join(root, LADDERS_DIR, `${id}.json`);
+  if (await exists2(ladderFile) || await exists2(path6.join(root, LADDERS_DIR, id))) {
+    throw new Error(`${LADDERS_DIR}/${id} exists. A ladder is never rewritten; give this one another --name`);
+  }
+  const base = JSON.parse(await fs5.readFile(graphFile, "utf8"));
+  if (!base.nodes?.some((node) => node.id === options.node)) {
+    throw new Error(`No node "${options.node}" in ${path6.basename(graphFile)}`);
+  }
+  const plan = variantPlan(base, options.vary ?? {}, options.seeds);
+  const graphRelative = relativeTo(root, graphFile);
+  const sources = await collectSources(root);
+  const { id: treeId, tree } = await storeSources(root, sources);
+  const directory = path6.join(root, LADDERS_DIR, id);
+  await fs5.mkdir(directory, { recursive: true });
+  const copy = options.live ? void 0 : await openCopy(root, tree, `ladder-${id}`);
+  const variants = [];
+  try {
+    for (const [offset, step] of plan.entries()) {
+      const index = offset + 1;
+      const document = withVariant(base, step.set, step.seed);
+      const cookOptions = { node: options.node, ports: options.ports, verbose: options.verbose };
+      const cooked = copy ? await copy.cook(graphRelative, document, cookOptions) : await cookIn(root, graphFile, document, cookOptions);
+      const source = firstRaster(cooked.root, cooked.ports);
+      if (!source) throw new Error(`Variant ${index}: node "${options.node}" made no raster image to put on a sheet (ports: ${Object.keys(cooked.ports).join(", ")})`);
+      const image = path6.join(directory, `${String(index).padStart(2, "0")}${path6.extname(source).toLowerCase()}`);
+      await fs5.copyFile(source, image);
+      variants.push({
+        index,
+        label: variantLabel(index, step.set, options.seeds ? step.seed : void 0),
+        set: step.set,
+        seed: graphSeed(document),
+        graph: await putObject(root, `${JSON.stringify(document, null, 2)}
+`),
+        params: graphParams(document),
+        seeds: graphSeeds(document),
+        inputs: await hashInputs(project, document, options.inputs ?? []),
+        image: relativeTo(root, image),
+        output: { ports: cooked.ports, durationMs: cooked.durationMs, ...cooked.trace ? { trace: cooked.trace } : {} }
+      });
+    }
+  } finally {
+    await copy?.dispose();
+  }
+  const sheet = await writeSheet(root, path6.join(directory, "sheet.png"), variants, options.columns);
+  const ladder = {
+    format: "cascade.ladder",
+    version: 1,
+    id,
+    name: options.name,
+    ...options.note ? { note: options.note } : {},
+    created: (/* @__PURE__ */ new Date()).toISOString(),
+    graph: { file: graphRelative, node: options.node, object: await putObject(root, await fs5.readFile(graphFile)) },
+    vary: Object.fromEntries(Object.keys(options.vary ?? {}).map((key) => [key, plan.map((step) => step.set[key])])),
+    ...options.seeds ? { seeds: [...options.seeds] } : {},
+    code: {
+      tree: treeId,
+      files: Object.keys(tree).length,
+      ...sources.skipped.length ? { skipped: sources.skipped } : {},
+      modules: await moduleHashes(root, base, tree),
+      ...await stageHashes(root, tree)
+    },
+    versions: { cascade: await cascadeVersion2(), project: await projectVersion(root), node: process.version },
+    host: { kind: "headless", platform: `${process.platform}-${process.arch}`, cooked: options.live ? "live" : "snapshot" },
+    sheet,
+    variants
+  };
+  await fs5.writeFile(ladderFile, stableJson(ladder, LADDER_KEY_ORDER), { flag: "wx" });
+  return { ladder, file: ladderFile };
+}
+function variantPlan(document, vary, seeds) {
+  const lengths = [...Object.values(vary).map((values) => values.length), ...seeds ? [seeds.length] : []];
+  if (!lengths.length) throw new Error("A ladder needs --vary <node.prop>=<a,b,c> or --seeds <a,b,c>");
+  const count = Math.max(...lengths);
+  if (count < 2) throw new Error("A ladder needs at least two variants");
+  if (count > MAX_VARIANTS) throw new Error(`A ladder has at most ${MAX_VARIANTS} variants (got ${count}); three to five is the usual`);
+  for (const [key, values] of Object.entries(vary)) {
+    if (values.length !== 1 && values.length !== count) throw new Error(`--vary ${key} has ${values.length} values; every list needs ${count} (or one)`);
+    const [nodeId, prop] = splitTarget(key);
+    if (!document.nodes?.some((node) => node.id === nodeId)) throw new Error(`--vary ${key}: no node "${nodeId}"`);
+    if (!prop) throw new Error(`--vary ${key}: name the parameter as node.prop`);
+  }
+  if (seeds && seeds.length !== 1 && seeds.length !== count) throw new Error(`--seeds has ${seeds.length} values; it needs ${count} (or one)`);
+  return Array.from({ length: count }, (_, index) => ({
+    set: Object.fromEntries(Object.entries(vary).map(([key, values]) => [key, values[values.length === 1 ? 0 : index]])),
+    seed: seeds ? seeds[seeds.length === 1 ? 0 : index] : graphSeed(document)
+  }));
+}
+function withVariant(document, set, seed) {
+  const copy = structuredClone(document);
+  for (const [key, value] of Object.entries(set)) {
+    const [nodeId, prop] = splitTarget(key);
+    const node = copy.nodes.find((candidate) => candidate.id === nodeId);
+    node.props = { ...node.props ?? {}, [prop]: value };
+  }
+  if (seed !== graphSeed(document) || document.seed !== void 0) copy.seed = seed;
+  return copy;
+}
+function splitTarget(key) {
+  const at = key.lastIndexOf(".");
+  return at <= 0 ? [key, ""] : [key.slice(0, at), key.slice(at + 1)];
+}
+function variantLabel(index, set, seed) {
+  const parts = Object.entries(set).map(([key, value]) => `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+  if (seed !== void 0) parts.push(`seed ${seed}`);
+  return [String(index), ...parts].join("  ");
+}
+async function writeSheet(root, file, variants, columns) {
+  const canvas = await installHeadlessCanvas();
+  try {
+    const images = await Promise.all(variants.map((variant) => fs5.readFile(path6.join(root, variant.image))));
+    const { bytes, layout } = await composeContactSheet(images.map((bytes2) => new Uint8Array(bytes2)), {
+      columns: columns ?? Math.min(variants.length, 5),
+      labels: variants.map((variant) => variant.label),
+      labelSize: 16
+    });
+    await fs5.writeFile(file, bytes);
+    return { file: relativeTo(root, file), sha256: digest(bytes), columns: layout.columns };
+  } finally {
+    canvas.dispose();
+  }
+}
+async function readLadder(projectRoot, idOrFile) {
+  const asFile = path6.resolve(idOrFile);
+  const file = idOrFile.endsWith(".json") && await exists2(asFile) ? asFile : path6.join(path6.resolve(projectRoot), LADDERS_DIR, `${idOrFile}.json`);
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs5.readFile(file, "utf8"));
+  } catch {
+    throw new Error(`No ladder "${idOrFile}" (looked for ${path6.relative(process.cwd(), file) || file})`);
+  }
+  if (parsed?.format !== "cascade.ladder") throw new Error(`${file} is not a Cascade ladder`);
+  return { ladder: parsed, root: path6.dirname(path6.dirname(file)), file };
+}
+async function pickVariant(projectRoot, ladderIdOrFile, index, options = {}) {
+  const { ladder, root, file: ladderFile } = await readLadder(projectRoot, ladderIdOrFile);
+  const variant = ladder.variants.find((candidate) => candidate.index === index);
+  if (!variant) throw new Error(`${ladder.id} has variants 1 to ${ladder.variants.length}; there is no ${index}`);
+  const id = lockId(options.name ?? `${ladder.name} ${index}`);
+  await checkLockId(root, id, options.supersedes);
+  const image = path6.join(root, variant.image);
+  const recorded = Object.values(variant.output.ports).find((port) => port.kind === "file" && port.pixels);
+  const current = await fingerprintFile({ projectRoot: root, resolve: (relative) => path6.join(root, relative) }, image, variant.image).catch(() => void 0);
+  if (!recorded || recorded.kind !== "file" || current?.kind !== "file" || current.pixels !== recorded.pixels) {
+    throw new Error(`${variant.image} is missing or no longer the image the ladder recorded; make a new ladder rather than lock a different picture`);
+  }
+  const document = JSON.parse((await getObject(root, variant.graph)).toString("utf8"));
+  const warnings = [];
+  const changed = await changedInputs(new ProjectRoot(root), variant.inputs);
+  if (changed.length) {
+    warnings.push(`${changed.length} input ${changed.length === 1 ? "file has" : "files have"} changed since the ladder (${changed.map((change) => change.path).join(", ")}); the lock records the ladder's, so a replay needs them restored`);
+  }
+  const preview = await writePreview(root, id, image);
+  const published = publishedParams(document);
+  const lock = {
+    format: "cascade.lock",
+    version: 1,
+    id,
+    name: options.name ?? `${ladder.name} ${index}`,
+    status: options.status ?? "approved",
+    ...options.note ? { note: options.note } : {},
+    ...options.supersedes ? { supersedes: options.supersedes } : {},
+    created: (/* @__PURE__ */ new Date()).toISOString(),
+    graph: { file: ladder.graph.file, node: ladder.graph.node, object: variant.graph },
+    params: variant.params,
+    ...published ? { published } : {},
+    seeds: variant.seeds,
+    inputs: variant.inputs,
+    code: ladder.code,
+    versions: ladder.versions,
+    host: ladder.host,
+    output: variant.output,
+    ...preview ? { preview } : {},
+    ladder: {
+      id: ladder.id,
+      file: relativeTo(root, ladderFile),
+      variant: index,
+      label: variant.label,
+      image: variant.image,
+      sheet: ladder.sheet.file
+    }
+  };
+  const file = await writeLock(root, lock);
+  const picks = [...ladder.picks ?? [], { variant: index, lock: id, at: lock.created }];
+  await fs5.writeFile(ladderFile, stableJson({ ...ladder, picks }, LADDER_KEY_ORDER));
+  return { lock, file, ladder: ladder.id, variant, warnings };
+}
+function parseValues(text) {
+  try {
+    const parsed = JSON.parse(`[${text}]`);
+    if (Array.isArray(parsed)) return parsed;
+  } catch {
+  }
+  return text.split(",").map((word) => word.trim());
+}
+async function exists2(file) {
+  try {
+    await fs5.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/cli/locks/ladderCard.ts
+import fs6 from "node:fs/promises";
+import path7 from "node:path";
+var MAX_CHOICE_OPTIONS = 8;
+function checkCardSize(count) {
+  if (count > MAX_CHOICE_OPTIONS) {
+    throw new Error(`--cairn shows at most ${MAX_CHOICE_OPTIONS} options on a choice card (this ladder has ${count}); ladder fewer variants`);
+  }
+}
+function pickValue(ladderId, index) {
+  return `pick:${ladderId}:${index}`;
+}
+function choiceLabel(variant, seedVaried) {
+  const parts = Object.entries(variant.set).map(([key, value]) => `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+  if (seedVaried) parts.push(`seed ${variant.seed}`);
+  return parts.join(", ");
+}
+async function writeLadderCard(root, ladder, directory, vault) {
+  checkCardSize(ladder.variants.length);
+  const target = path7.resolve(directory);
+  const vaultRoot = vault ? path7.resolve(vault) : await findVault(target);
+  const relative = path7.relative(vaultRoot, target);
+  if (relative.startsWith("..") || path7.isAbsolute(relative)) throw new Error(`--cairn ${target} is not inside the vault ${vaultRoot}`);
+  await fs6.mkdir(target, { recursive: true });
+  const seedVaried = Boolean(ladder.seeds);
+  const files = [];
+  const options = [];
+  for (const variant of ladder.variants) {
+    const file = path7.join(target, `${ladder.id}-${String(variant.index).padStart(2, "0")}${path7.extname(variant.image).toLowerCase()}`);
+    await fs6.copyFile(path7.join(root, variant.image), file);
+    files.push(file);
+    options.push({
+      label: choiceLabel(variant, seedVaried) || `variant ${variant.index}`,
+      value: pickValue(ladder.id, variant.index),
+      image: path7.relative(vaultRoot, file).split(path7.sep).join("/")
+    });
+  }
+  const choice = { prompt: `${ladder.name}: which one? (ladder ${ladder.id}, ${ladder.graph.file} ${ladder.graph.node})`, options };
+  return { choice, fence: choiceFence(choice), vault: vaultRoot, files };
+}
+function choiceFence(choice) {
+  return `\`\`\`cairn:choice
+${JSON.stringify(choice)}
+\`\`\``;
+}
+async function findVault(start) {
+  for (const marker of [".obsidian", ".git"]) {
+    for (let directory = start; ; directory = path7.dirname(directory)) {
+      if (await exists3(path7.join(directory, marker))) return directory;
+      if (path7.dirname(directory) === directory) break;
+    }
+  }
+  throw new Error(`--cairn ${start}: no vault above it (no .obsidian or .git); name it with --vault <dir>`);
+}
+async function exists3(file) {
+  try {
+    await fs6.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/cli/locks/commands.ts
+var LOCK_COMMANDS = ["lock", "locks", "replay", "ladder", "pick"];
+var LOCK_HELP = `
+Locks: this exact render, from this code, these parameters and this seed.
+
+  cascade lock <graph> <node> --name <name> [--note <text>] [--status approved]
+               [--supersedes <id>] [--scene <scene.json>] [--seed <n>] [--input <file>]...
+               [--port <output>]... [--preview <image>] [--live] [--json]
+      Cook <node> and write locks/<id>.json: the graph, parameters, seeds,
+      input hashes, versions, the project's source code (stored in
+      .cascade/objects/) and a fingerprint of every output. --seed sets the
+      graph seed for this render. Cooks from the stored code in a fresh copy
+      of the project unless --live.
+
+  cascade replay <id | locks/<id>.json> [--out <dir>] [--live] [--keep]
+                 [--allow-input-change] [--project <dir>] [--json]
+      Rebuild the lock's code in a throwaway copy, cook the stored graph and
+      compare fingerprints. --live cooks with the project's code as it is now.
+      Exits 1 when the output differs.
+
+  cascade lock verify [<id>...] [--live] [--project <dir>] [--json]
+      Replay every lock (or the named ones) and report which still match.
+
+  cascade locks [<project-dir>] [--json]
+      List the project's locks.
+
+Ladders: three to five options side by side, and a lock at approval.
+
+  cascade ladder <graph> <node> --name <name> [--vary <node.prop>=<a,b,c>]...
+                 [--seeds <a,b,c>] [--columns N] [--port <output>]... [--input <file>]...
+                 [--note <text>] [--live] [--cairn <vault dir> [--vault <dir>]] [--json]
+      Cook <node> once per variant and write ladders/<id>/<n>.png, a labelled
+      contact sheet ladders/<id>/sheet.png, and the record ladders/<id>.json
+      (per variant: graph, params, seed, inputs, output fingerprint; the
+      stored code and git commit once). Values are a JSON list without its
+      brackets (0.5,1,2 or [1,2],[3,4]); lists are zipped, one value applies
+      to every variant. Cooks from the stored code in a fresh copy unless --live.
+      --cairn copies each variant to <dir>/<id>-<nn>.png (a space's
+      _attachments/ladders/<id>/) and prints a cairn:choice card (--json:
+      data.cairnChoice) whose images are relative to the vault (the nearest
+      .obsidian or .git above, or --vault); at most 8 variants. A tap answers
+      "Picked: <label> (pick:<id>:<n>)": run cascade pick <id> <n>.
+
+  cascade pick <ladder-id | ladders/<id>.json> <n> [--name <lock name>] [--note <text>]
+               [--status approved] [--supersedes <id>] [--project <dir>] [--json]
+      Write locks/<id>.json for variant <n> from the ladder's record, without
+      cooking again: its fingerprint is the image that was approved, so
+      cascade replay reproduces that image. Default name: "<ladder> <n>".
+`;
+var SWITCHES = /* @__PURE__ */ new Set(["--json", "--live", "--keep", "--allow-input-change", "--verify", "--verbose", "-v"]);
+function parse(args) {
+  const positional = [];
+  const values = /* @__PURE__ */ new Map();
+  const switches = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (SWITCHES.has(arg)) switches.add(arg === "-v" ? "--verbose" : arg);
+    else if (arg.startsWith("--")) {
+      const value = args[index + 1];
+      if (value === void 0 || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      values.set(arg, [...values.get(arg) ?? [], value]);
+      index += 1;
+    } else positional.push(arg);
+  }
+  return { positional, values, switches };
+}
+var one = (parsed, flag) => parsed.values.get(flag)?.slice(-1)[0];
+async function runLockCommand(args) {
+  const json = args.includes("--json");
+  const log = console.log;
+  if (json) console.log = console.error;
+  const print = (value) => process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+  try {
+    const [command, ...rest] = args;
+    if (command === "locks") await locksCommand(parse(rest), json, print);
+    else if (command === "replay") await replayCommand(parse(rest), json, print);
+    else if (command === "lock" && rest[0] === "verify") await verifyCommand(parse(rest.slice(1)), json, print);
+    else if (command === "lock") await lockCommand(parse(rest), json, print);
+    else if (command === "ladder") await ladderCommand(parse(rest), json, print);
+    else if (command === "pick") await pickCommand(parse(rest), json, print);
+    else throw new Error(`Unknown lock command: ${command}`);
+  } catch (error) {
+    if (json) throw error;
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  } finally {
+    console.log = log;
+  }
+}
+async function lockCommand(parsed, json, print) {
+  const [graph, node] = parsed.positional;
+  const name = one(parsed, "--name");
+  if (!graph || !node || !name) throw new Error("cascade lock needs <graph> <node> --name <name>");
+  const { lock, file } = await createLock({
+    graph,
+    node,
+    name,
+    note: one(parsed, "--note"),
+    status: one(parsed, "--status"),
+    supersedes: one(parsed, "--supersedes"),
+    scene: one(parsed, "--scene"),
+    seed: seedValue(one(parsed, "--seed")),
+    inputs: parsed.values.get("--input"),
+    ports: parsed.values.get("--port"),
+    preview: one(parsed, "--preview"),
+    live: parsed.switches.has("--live"),
+    verbose: parsed.switches.has("--verbose")
+  });
+  if (json) return print({ status: "locked", file, lock });
+  console.log(`Locked ${lock.id} -> ${shown(file)}`);
+  console.log(`  ${lock.graph.file} node ${lock.graph.node}, graph ${short(lock.graph.object)}, code ${short(lock.code.tree)} (${lock.code.files} files)`);
+  console.log(`  ${Object.keys(lock.inputs).length} inputs, ${Object.keys(lock.seeds).length} seeds, cooked from the ${lock.host.cooked} in ${seconds(lock.output.durationMs)}`);
+  for (const [port, fingerprint] of Object.entries(lock.output.ports)) console.log(`  ${port}: ${describePort(fingerprint)}`);
+  if (lock.code.skipped?.length) console.log(`  not stored (over 2 MB): ${lock.code.skipped.join(", ")}`);
+  if (lock.output.trace) console.log(`  trace ${lock.output.trace}`);
+}
+async function replayCommand(parsed, json, print) {
+  const target = parsed.positional[0];
+  if (!target) throw new Error("cascade replay needs a lock id or file");
+  const { lock, root } = await readLock(one(parsed, "--project") ?? process.cwd(), target);
+  const result = await replayLock(root, lock, {
+    out: one(parsed, "--out"),
+    live: parsed.switches.has("--live"),
+    keep: parsed.switches.has("--keep"),
+    allowInputChange: parsed.switches.has("--allow-input-change"),
+    verbose: parsed.switches.has("--verbose")
+  });
+  if (json) return print(result);
+  printReplay(result);
+  if (lock.ladder) console.log(`  picked from ladder ${lock.ladder.id}, variant ${lock.ladder.label}: ${result.status === "match" ? "same pixels as" : "differs from"} ${lock.ladder.image}`);
+  if (result.status !== "match") process.exitCode = 1;
+}
+async function verifyCommand(parsed, json, print) {
+  const root = path8.resolve(one(parsed, "--project") ?? process.cwd());
+  const locks = parsed.positional.length ? await Promise.all(parsed.positional.map(async (id) => (await readLock(root, id)).lock)) : await listLocks(root);
+  if (!locks.length) throw new Error(`No locks in ${path8.join(root, "locks")}`);
+  const results = [];
+  for (const lock of locks) {
+    try {
+      const result = await replayLock(root, lock, {
+        live: parsed.switches.has("--live"),
+        allowInputChange: parsed.switches.has("--allow-input-change"),
+        verbose: parsed.switches.has("--verbose")
+      });
+      results.push(result);
+      if (!json) printReplay(result);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      results.push({ id: lock.id, status: "error", error: message });
+      if (!json) console.log(`${lock.id}: ERROR
+  ${message.split("\n").join("\n  ")}`);
+    }
+  }
+  const failed = results.filter((result) => result.status !== "match").length;
+  if (json) return print({ status: failed ? "failed" : "ok", verified: results.length, failed, results });
+  console.log(`
+${results.length - failed} of ${results.length} locks reproduce${failed ? `; ${failed} do not` : ""}.`);
+  if (failed) process.exitCode = 1;
+}
+async function locksCommand(parsed, json, print) {
+  const root = path8.resolve(parsed.positional[0] ?? one(parsed, "--project") ?? process.cwd());
+  const locks = await listLocks(root);
+  if (json) {
+    return print({
+      project: root,
+      locks: locks.map((lock) => ({
+        id: lock.id,
+        name: lock.name,
+        status: lock.status,
+        created: lock.created,
+        graph: lock.graph.file,
+        node: lock.graph.node,
+        ...lock.note ? { note: lock.note } : {},
+        ...lock.supersedes ? { supersedes: lock.supersedes } : {},
+        commit: lock.versions.project.commit ?? null,
+        preview: lock.preview?.file ?? null
+      }))
+    });
+  }
+  if (!locks.length) return console.log(`No locks in ${path8.join(root, "locks")}`);
+  const width = Math.max(...locks.map((lock) => lock.id.length));
+  for (const lock of locks) {
+    const commit = lock.versions.project.commit ? ` @${lock.versions.project.commit.slice(0, 7)}${lock.versions.project.dirty ? "+" : ""}` : "";
+    const supersedes = lock.supersedes ? `, supersedes ${lock.supersedes}` : "";
+    console.log(`${lock.id.padEnd(width)}  ${lock.status.padEnd(9)} ${lock.created.slice(0, 16).replace("T", " ")}  ${lock.graph.file} ${lock.graph.node}${commit}${supersedes}`);
+  }
+}
+async function ladderCommand(parsed, json, print) {
+  const [graph, node] = parsed.positional;
+  const name = one(parsed, "--name");
+  if (!graph || !node || !name) throw new Error("cascade ladder needs <graph> <node> --name <name> and --vary or --seeds");
+  const vary = {};
+  for (const pair of parsed.values.get("--vary") ?? []) {
+    const at = pair.indexOf("=");
+    if (at <= 0) throw new Error(`--vary takes node.prop=a,b,c (got "${pair}")`);
+    vary[pair.slice(0, at)] = parseValues(pair.slice(at + 1));
+  }
+  const seedsText = one(parsed, "--seeds");
+  const seeds = seedsText === void 0 ? void 0 : seedsText.split(",").map((text) => seedValue(text.trim()));
+  const cairn = one(parsed, "--cairn");
+  if (cairn) checkCardSize(Math.max(0, ...Object.values(vary).map((values) => values.length), seeds?.length ?? 0));
+  const columns = one(parsed, "--columns");
+  const { ladder, file } = await createLadder({
+    graph,
+    node,
+    name,
+    note: one(parsed, "--note"),
+    vary,
+    seeds,
+    columns: columns === void 0 ? void 0 : Number(columns),
+    ports: parsed.values.get("--port"),
+    inputs: parsed.values.get("--input"),
+    live: parsed.switches.has("--live"),
+    verbose: parsed.switches.has("--verbose")
+  });
+  const root = path8.dirname(path8.dirname(file));
+  const card = cairn ? await writeLadderCard(root, ladder, cairn, one(parsed, "--vault")) : void 0;
+  if (json) {
+    return print({
+      status: "laddered",
+      file,
+      sheet: path8.join(root, ladder.sheet.file),
+      variants: ladder.variants.map((variant) => ({ index: variant.index, label: variant.label, image: path8.join(root, variant.image), set: variant.set, seed: variant.seed })),
+      ...card ? { cairnChoice: card.fence, cairn: { vault: card.vault, files: card.files, choice: card.choice } } : {},
+      ladder
+    });
+  }
+  console.log(`Ladder ${ladder.id} -> ${shown(file)}, cooked from the ${ladder.host.cooked}`);
+  console.log(`  sheet ${shown(path8.join(root, ladder.sheet.file))}`);
+  for (const variant of ladder.variants) console.log(`  ${variant.label}  ${variant.image}  (${seconds(variant.output.durationMs)})`);
+  console.log(`Pick one with: cascade pick ${ladder.id} <n> --project ${root}`);
+  if (card) {
+    console.log(`
+Cairn choice card (images in ${shown(path8.dirname(card.files[0]))}); post it as is, and on "Picked: \u2026 (pick:${ladder.id}:<n>)" run cascade pick ${ladder.id} <n> --project ${root}:
+`);
+    console.log(card.fence);
+  }
+}
+async function pickCommand(parsed, json, print) {
+  const [ladder, variant] = parsed.positional;
+  const index = Number(variant);
+  if (!ladder || !Number.isInteger(index)) throw new Error("cascade pick needs <ladder> <variant number>");
+  const result = await pickVariant(one(parsed, "--project") ?? process.cwd(), ladder, index, {
+    name: one(parsed, "--name"),
+    note: one(parsed, "--note"),
+    status: one(parsed, "--status"),
+    supersedes: one(parsed, "--supersedes")
+  });
+  for (const warning of result.warnings) console.error(`Warning: ${warning}`);
+  if (json) return print({ status: "locked", file: result.file, ladder: result.ladder, variant: result.variant.index, warnings: result.warnings, lock: result.lock });
+  const commit = result.lock.versions.project.commit;
+  console.log(`Locked ${result.lock.id} -> ${shown(result.file)}: ${result.ladder} variant ${result.variant.label}`);
+  console.log(`  graph seed ${result.lock.seeds.graph}, code ${short(result.lock.code.tree)}${commit ? `, commit ${commit.slice(0, 7)}${result.lock.versions.project.dirty ? "+" : ""}` : ""}`);
+  console.log(`  image ${result.variant.image}${result.lock.preview ? `, preview ${result.lock.preview.file}` : ""}`);
+  console.log(`Reproduce it with: cascade replay ${result.lock.id}`);
+}
+function printReplay(result) {
+  const verdict = result.status === "match" ? "match" : "MISMATCH";
+  const from = result.cooked === "live" ? "the project's current code" : "the lock's code";
+  console.log(`${result.id}: ${verdict}, replayed from ${from} in ${seconds(result.durationMs)}`);
+  for (const difference of result.differences) {
+    console.log(`  ${difference.port}: locked ${difference.expected}`);
+    console.log(`  ${" ".repeat(difference.port.length)}  replay ${difference.actual}`);
+  }
+  if (result.status === "match") {
+    for (const [port, fingerprint] of Object.entries(result.ports)) console.log(`  ${port}: ${describePort(fingerprint)}`);
+  }
+  const code = result.codeSinceLock;
+  const drift = code.changed.length + code.added.length + code.removed.length;
+  if (drift) {
+    console.log(`  project code since the lock: ${code.changed.length} changed, ${code.added.length} added, ${code.removed.length} removed`);
+    for (const name of code.changed.slice(0, 10)) console.log(`    changed ${name}`);
+    if (code.changed.length > 10) console.log(`    ... and ${code.changed.length - 10} more`);
+  }
+  for (const change of result.inputsChanged) console.log(`  input changed: ${change.path}`);
+  for (const warning of result.warnings) console.log(`  note: ${warning}`);
+  for (const file of result.files) console.log(`  wrote ${shown(file)}`);
+  if (result.trace) console.log(`  trace ${result.trace}`);
+  if (result.kept) console.log(`  replay copy kept at ${result.kept}`);
+}
+function describePort(fingerprint) {
+  if (fingerprint.kind === "value") return `value ${short(fingerprint.sha256)}`;
+  const size = fingerprint.width ? ` ${fingerprint.width}x${fingerprint.height}` : "";
+  return `${fingerprint.path}${size} ${short(fingerprint.pixels ?? fingerprint.sha256)}`;
+}
+function shown(file) {
+  const relative = path8.relative(process.cwd(), file);
+  return relative.startsWith("..") ? file : relative;
+}
+function seedValue(text) {
+  if (text === void 0) return void 0;
+  const value = Number(text);
+  if (!Number.isInteger(value) || value < 0 || value > 4294967295) throw new Error(`--seed must be an integer from 0 to 4294967295 (got "${text}")`);
+  return value;
+}
+function seconds(ms) {
+  return ms < 1e3 ? `${ms} ms` : `${(ms / 1e3).toFixed(1)} s`;
+}
+export {
+  LOCK_COMMANDS,
+  LOCK_HELP,
+  runLockCommand
+};
+//# sourceMappingURL=commands-PHYFYA3F.js.map