@field/cascade 0.11.0 → 0.13.0

package/dist/cli/{chunk-EUIAC3U3.js → chunk-QKL7CCRS.js}

@@ -3,31 +3,39 @@ import {
   builtinNodeRegistrations,
   headlessBuiltin,
   headlessBuiltinRegistrations
-} from "./chunk-36P5K3SD.js";
+} from "./chunk-MI5JLQYA.js";
 import {
-  imagePath,
-  sequenceFileName,
-  sequenceWidth
-} from "./chunk-ICH7N5PN.js";
+  Color
+} from "./chunk-GRIN2DDP.js";
 import {
   DEFAULT_GRAPH_SEED,
   bundleFieldType,
   bundleSchemasCompatible,
   bundleValueProblem,
   createGpuHost,
+  gpuLimitShortfall,
   graphSeed,
   isBundleValue,
   isGpuHost,
   nodeSeed,
+  requestDeviceWithAdapterLimits,
   seededRandom,
   selectBundleFields,
   suggestName,
   unknownFieldMessage
-} from "./chunk-GFS6W3C5.js";
+} from "./chunk-L6B6FUQP.js";
 import {
   PropAnimator,
   isBoundProp
 } from "./chunk-HFHWYL55.js";
+import {
+  installIoBridge
+} from "./chunk-KBGUO27Q.js";
+import {
+  imagePath,
+  sequenceFileName,
+  sequenceWidth
+} from "./chunk-ICH7N5PN.js";
 import {
   DEFAULT_FPS,
   MIN_FRAME,
@@ -38,23 +46,36 @@ import {
   parseBundleFieldPath,
   remoteBundlePath
 } from "./chunk-CO22XHNG.js";
+import {
+  PythonWorker,
+  PythonWorkerPool,
+  defaultStageWorkerCount
+} from "./chunk-YH637PDL.js";
+import {
+  readStageConfig,
+  runProjectStage
+} from "./chunk-X566FWBV.js";
+import {
+  callStage,
+  stageSources
+} from "./chunk-5ORUQ6ES.js";
 import {
   ProjectRoot,
   extractNodeDefinition
-} from "./chunk-RQZ4SX5R.js";
+} from "./chunk-W5PJ5RMP.js";
 import {
   CAPABILITIES_BY_ENVIRONMENT,
   validateNodeDefinition
-} from "./chunk-A4OAMOZH.js";
+} from "./chunk-NJFMDXHR.js";
 import {
   canConnectTypes
-} from "./chunk-BIJO5OFS.js";
+} from "./chunk-FWMSGKEH.js";
 
 // src/cli/projectRuntime.ts
-import fs4 from "node:fs/promises";
-import path5 from "node:path";
+import fs5 from "node:fs/promises";
+import path6 from "node:path";
 import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "node:url";
-import { existsSync } from "node:fs";
+import { existsSync as existsSync2 } from "node:fs";
 import ts from "typescript";
 import { build } from "esbuild";
 
@@ -117,11 +138,21 @@ var MutableAbortSignal = class {
   }
 };
 function createRuntime(options) {
-  return new Runtime(options.host, [...builtinNodeRegistrations, ...options.nodes ?? []]);
+  return new Runtime(
+    options.host,
+    [...builtinNodeRegistrations, ...options.nodes ?? []],
+    {
+      values: options.values === "trust" ? "trust" : "freeze",
+      concurrency: Math.max(1, Math.floor(Number(options.concurrency ?? 1)) || 1),
+      ...options.nodeScope ? { nodeScope: options.nodeScope } : {}
+    }
+  );
 }
+var SERIAL_EXECUTION = { values: "freeze", concurrency: 1 };
 var Runtime = class {
-  constructor(host, registrations) {
+  constructor(host, registrations, execution = SERIAL_EXECUTION) {
     this.host = host;
+    this.execution = execution;
     this.registrations = /* @__PURE__ */ new Map();
     this.graphs = /* @__PURE__ */ new Set();
     this.sealed = false;
@@ -202,7 +233,8 @@ var Runtime = class {
       connections,
       () => this.graphs.delete(graph),
       document2.annotations,
-      graphSeed(document2)
+      graphSeed(document2),
+      this.execution
     );
     const fps = document2.timeline?.fps;
     if (typeof fps === "number" && Number.isFinite(fps) && fps > 0) graph.setFps(fps);
@@ -217,12 +249,13 @@ var Runtime = class {
   }
 };
 var Graph = class {
-  constructor(host, nodes, connections, onDispose, annotations = [], seed = DEFAULT_GRAPH_SEED) {
+  constructor(host, nodes, connections, onDispose, annotations = [], seed = DEFAULT_GRAPH_SEED, execution = SERIAL_EXECUTION) {
     this.host = host;
     this.nodes = nodes;
     this.connections = connections;
     this.onDispose = onDispose;
     this.seed = seed;
+    this.execution = execution;
     this.graphState = "ready";
     this.listeners = /* @__PURE__ */ new Set();
     this.diagnostics = [];
@@ -241,6 +274,7 @@ var Graph = class {
      * state survives an inner loop running to completion inside one of its steps.
      */
     this.feedbackState = /* @__PURE__ */ new Map();
+    this.values = execution.values;
     this.byId = new Map(nodes.map((node) => [node.id, node]));
     const byInput = /* @__PURE__ */ new Map();
     const byNode = /* @__PURE__ */ new Map();
@@ -350,7 +384,7 @@ var Graph = class {
               kind: definition.kind,
               type: definition.kind === "trigger" ? "trigger" : definition.type,
               connected: this.connectedOutputs.has(`${node.id}\0${name}`),
-              ...definition.kind === "data" && node.outputs.has(name) ? { value: snapshot(node.outputs.get(name)) } : {}
+              ...definition.kind === "data" && node.outputs.has(name) ? { value: this.expose(node.outputs.get(name)) } : {}
             }
           ]
         )
@@ -552,7 +586,15 @@ var Graph = class {
     return () => this.listeners.delete(listener);
   }
   getOutput(nodeId, outputName2) {
-    return snapshot(this.requireNode(nodeId).outputs.get(outputName2));
+    return this.expose(this.requireNode(nodeId).outputs.get(outputName2));
+  }
+  /**
+   * An output value as callers see it. Under `"freeze"` every output was
+   * deep-frozen when it was set, so this is the value itself (the snapshot is
+   * a lookup); under `"trust"` it is handed out as the producer made it.
+   */
+  expose(value) {
+    return this.values === "trust" ? value : snapshot(value);
   }
   getGraphOutput(name) {
     const node = this.graphOutputs.get(name);
@@ -564,7 +606,7 @@ var Graph = class {
     return immutableMap(
       [...this.requireNode(nodeId).outputs].map(([name, value]) => [
         name,
-        snapshot(value)
+        this.expose(value)
       ])
     );
   }
@@ -639,17 +681,21 @@ var Graph = class {
         (node) => initial.includes(node) && !insideFeedback.has(node.id)
       );
       const cooked = /* @__PURE__ */ new Set();
-      for (const node of ordered) {
-        if (signal.aborted) break;
-        if (reuse && this.reusable(node) && !(reuse === "strict" && this.feedsFrom(node, cooked))) {
-          this.emit({ type: "node:start", runId, nodeId: node.id });
-          this.emit({ type: "node:complete", runId, nodeId: node.id });
-          continue;
+      const skip = (node) => !!reuse && this.reusable(node) && !(reuse === "strict" && this.feedsFrom(node, cooked));
+      if (this.execution.concurrency > 1)
+        await this.cookConcurrently(ordered, runId, signal, enqueue, skip, cooked);
+      else
+        for (const node of ordered) {
+          if (signal.aborted) break;
+          if (skip(node)) {
+            this.emit({ type: "node:start", runId, nodeId: node.id });
+            this.emit({ type: "node:complete", runId, nodeId: node.id });
+            continue;
+          }
+          await this.executeNode(node, runId, signal, {}, enqueue);
+          cooked.add(node.id);
+          if (!signal.aborted) node.lastCook = this.cookKey(node);
         }
-        await this.executeNode(node, runId, signal, {}, enqueue);
-        cooked.add(node.id);
-        if (!signal.aborted) node.lastCook = this.cookKey(node);
-      }
       if (injection && !signal.aborted)
         enqueue(injection.nodeId, injection.inputName, injection.payload, {
           kind: "external"
@@ -700,7 +746,79 @@ var Graph = class {
       this.active = void 0;
     }
   }
+  /**
+   * The run's main order with up to `concurrency` nodes cooking at once.
+   *
+   * Nodes START strictly in topological order: the next node starts once
+   * everything it reads has completed and a slot is free, and nothing later
+   * in the order overtakes it. So the `node:start` events — and a run trace
+   * built from them — come in the same order as a serial run on every run;
+   * only completions interleave. A Kahn order puts siblings side by side (the
+   * morph's four renders are adjacent), which is where the overlap is.
+   *
+   * A feedback container, a node with trigger ports and a GPU node cook
+   * alone: their state (the carried step, the trigger queue's sequence, one
+   * device) is ordered by the serial loop and not worth sharing.
+   *
+   * On a failure nothing new starts, the nodes already cooking finish, and
+   * the failure earliest in the order is the run's, so the message does not
+   * depend on which stage happened to answer first.
+   */
+  async cookConcurrently(ordered, runId, signal, enqueue, skip, cooked) {
+    const position = new Map(ordered.map((node, index) => [node.id, index]));
+    const needs = /* @__PURE__ */ new Map();
+    for (const dependency of graphDependencies(this.nodes, this.connections)) {
+      if (!position.has(dependency.sourceId) || !position.has(dependency.targetId)) continue;
+      const list = needs.get(dependency.targetId) ?? [];
+      list.push(dependency.sourceId);
+      needs.set(dependency.targetId, list);
+    }
+    const done = /* @__PURE__ */ new Set();
+    const running = /* @__PURE__ */ new Map();
+    let exclusiveRunning = false;
+    let failure;
+    let next = 0;
+    for (; ; ) {
+      while (!failure && !signal.aborted && !exclusiveRunning && next < ordered.length && running.size < this.execution.concurrency) {
+        const node = ordered[next];
+        if (!(needs.get(node.id) ?? []).every((id) => done.has(id))) break;
+        const alone = cooksAlone(node);
+        if (alone && running.size) break;
+        next++;
+        if (skip(node)) {
+          this.emit({ type: "node:start", runId, nodeId: node.id });
+          this.emit({ type: "node:complete", runId, nodeId: node.id });
+          done.add(node.id);
+          continue;
+        }
+        if (alone) exclusiveRunning = true;
+        const index = position.get(node.id);
+        const task = this.executeNode(node, runId, signal, {}, enqueue).then(
+          () => {
+            cooked.add(node.id);
+            if (!signal.aborted) node.lastCook = this.cookKey(node);
+            done.add(node.id);
+          },
+          (error) => {
+            if (!failure || index < failure.index) failure = { index, error };
+          }
+        ).finally(() => {
+          running.delete(node.id);
+          if (alone) exclusiveRunning = false;
+        });
+        running.set(node.id, task);
+      }
+      if (!running.size) break;
+      await Promise.race(running.values());
+    }
+    if (failure) throw failure.error;
+  }
   async executeNode(node, runId, signal, triggers, enqueue) {
+    const scope = this.execution.nodeScope;
+    if (!scope) return this.cookNode(node, runId, signal, triggers, enqueue);
+    return scope(node.id, () => this.cookNode(node, runId, signal, triggers, enqueue));
+  }
+  async cookNode(node, runId, signal, triggers, enqueue) {
     this.emit({ type: "node:start", runId, nodeId: node.id });
     if (node.moduleId === "cascade.core.Previous") {
       const container = this.enclosingFeedback(node);
@@ -778,7 +896,8 @@ var Graph = class {
           const value = outputValue(
             response.outputs[name],
             definition,
-            `${node.id}.${name}`
+            `${node.id}.${name}`,
+            this.values
           );
           node.outputs.set(name, value);
           this.emit({
@@ -811,7 +930,7 @@ var Graph = class {
           } : {
             set: (value) => pendingData.set(
               name,
-              outputValue(value, definition, `${node.id}.${name}`)
+              outputValue(value, definition, `${node.id}.${name}`, this.values)
             )
           }
         ]
@@ -822,7 +941,10 @@ var Graph = class {
       const installed = this.host.capabilities[name];
       if (name === "gpu" && isGpuHost(installed)) {
         await installed.ensure();
-        capabilityEntries.push([name, installed.forNode(node.id)]);
+        const gpu = installed.forNode(node.id);
+        const shortfall = gpuLimitShortfall(node.id, node.definition.gpuLimits, gpu);
+        if (shortfall) throw new Error(shortfall);
+        capabilityEntries.push([name, gpu]);
       } else {
         capabilityEntries.push([
           name,
@@ -872,7 +994,7 @@ var Graph = class {
           runId,
           nodeId: node.id,
           outputName: name,
-          value: snapshot(value)
+          value: this.expose(value)
         });
       }
     for (const emitted of pendingTriggers)
@@ -1002,8 +1124,8 @@ var Graph = class {
       }
       for (const [prop, binding] of Object.entries(node.bindings)) {
         if (!binding.expression) continue;
-        for (const path6 of expressionPaths(binding.expression)) {
-          const remote = remoteBundlePath(path6);
+        for (const path7 of expressionPaths(binding.expression)) {
+          const remote = remoteBundlePath(path7);
           if (remote) {
             const owner = this.byId.get(remote.node);
             const output = owner?.definition.outputs?.[remote.port];
@@ -1011,12 +1133,12 @@ var Graph = class {
               push(
                 node.id,
                 "runtime/bundle-remote-read",
-                `${node.id}.${prop} reads "${path6}", another node's bundle, without a wire. Wire ${remote.node}.${remote.port} into a bundle input on ${node.id} and read "${remote.port}.${remote.field}" instead`,
+                `${node.id}.${prop} reads "${path7}", another node's bundle, without a wire. Wire ${remote.node}.${remote.port} into a bundle input on ${node.id} and read "${remote.port}.${remote.field}" instead`,
                 `${node.id}.${prop}`
               );
             continue;
           }
-          const reference = parseBundleFieldPath(path6);
+          const reference = parseBundleFieldPath(path7);
           if (!reference) continue;
           const input = node.definition.inputs?.[reference.port];
           if (!input) {
@@ -1025,7 +1147,7 @@ var Graph = class {
             push(
               node.id,
               "runtime/bundle-unknown-port",
-              `${node.id}.${prop} reads "${path6}", but ${node.moduleId} has no input "${reference.port}"` + (suggestion ? ` \u2014 did you mean "${suggestion}.${reference.field}"?` : ""),
+              `${node.id}.${prop} reads "${path7}", but ${node.moduleId} has no input "${reference.port}"` + (suggestion ? ` \u2014 did you mean "${suggestion}.${reference.field}"?` : ""),
               `${node.id}.${prop}`
             );
             continue;
@@ -1334,7 +1456,8 @@ var Graph = class {
       }
       return Object.freeze({
         result: carried,
-        history: Object.freeze(history)
+        // Recorded as settled, so reading `history` back is not a copy.
+        history: settle(history)
       });
     } finally {
       this.feedbackState.delete(node.id);
@@ -1476,8 +1599,10 @@ function materialize(authored, registration) {
     const definition = registration.definition.props?.[name];
     if (!definition) continue;
     const object = saved && typeof saved === "object" && "value" in saved ? saved : null;
+    const stored = object ? object.value : saved;
     const value = runtimeValue(
-      object ? object.value : saved,
+      // A colour saved as `{ r, g, b }` by the class image nodes reads as one.
+      definition.type === "color" ? Color.upgrade(stored) : stored,
       definition.type,
       false,
       `${authored.id}.${name}`
@@ -1734,6 +1859,15 @@ function snapshotRegistration(registration) {
   const definition = snapshot(registration.definition);
   return Object.freeze({ ...registration, definition });
 }
+function cooksAlone(node) {
+  if (node.definition.container === "feedback") return true;
+  if (node.definition.capabilities?.includes("gpu")) return true;
+  const ports = [
+    ...Object.values(node.definition.inputs ?? {}),
+    ...Object.values(node.definition.outputs ?? {})
+  ];
+  return ports.some((port) => port.kind === "trigger");
+}
 function isGated(node) {
   return Object.values(node.definition.inputs ?? {}).some(
     (input) => input.kind === "trigger"
@@ -1877,7 +2011,69 @@ function misuse(code, message) {
   throw runtimeError(code, message);
 }
 function snapshot(value) {
-  return cloneValue(value, /* @__PURE__ */ new WeakSet());
+  const clone = cloneValue(value, /* @__PURE__ */ new WeakSet());
+  if (clone !== null && typeof clone === "object") settled.add(clone);
+  return clone;
+}
+var settled = /* @__PURE__ */ new WeakSet();
+var copiedContainers = 0;
+function isPlainContainer(value) {
+  if (Array.isArray(value)) return true;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function checkScalar(value) {
+  if (typeof value === "number" && !Number.isFinite(value))
+    misuse("runtime/non-serializable-value", "Runtime numbers must be finite");
+  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint")
+    misuse(
+      "runtime/non-serializable-value",
+      `Runtime values cannot contain ${typeof value}`
+    );
+}
+function settle(value) {
+  if (value === null || typeof value !== "object") {
+    checkScalar(value);
+    return value;
+  }
+  if (!settled.has(value) && isPlainContainer(value)) {
+    settleContainer(value, /* @__PURE__ */ new WeakSet());
+    settled.add(value);
+  }
+  return value;
+}
+function settleContainer(value, ancestors) {
+  let nested = false;
+  const visit = (item) => {
+    if (item === null || typeof item !== "object") {
+      checkScalar(item);
+      return;
+    }
+    if (settled.has(item) || !isPlainContainer(item)) return;
+    if (ancestors.has(item))
+      misuse(
+        "runtime/non-serializable-value",
+        "Runtime values cannot contain cycles"
+      );
+    if (!nested) {
+      nested = true;
+      ancestors.add(value);
+    }
+    if (settleContainer(item, ancestors)) settled.add(item);
+  };
+  if (Array.isArray(value)) for (let index = 0; index < value.length; index++) visit(value[index]);
+  else for (const key of Object.keys(value)) visit(value[key]);
+  if (nested) ancestors.delete(value);
+  Object.freeze(value);
+  return nested;
+}
+function trust(value) {
+  if (value === null || typeof value !== "object") {
+    checkScalar(value);
+    return value;
+  }
+  if (isPlainContainer(value)) Object.freeze(value);
+  return value;
 }
 function immutableMap(entries) {
   const source = new Map(entries);
@@ -1911,24 +2107,17 @@ function immutableMap(entries) {
   return view;
 }
 function cloneValue(value, ancestors) {
-  if (typeof value === "number" && !Number.isFinite(value))
-    misuse("runtime/non-serializable-value", "Runtime numbers must be finite");
-  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint")
-    misuse(
-      "runtime/non-serializable-value",
-      `Runtime values cannot contain ${typeof value}`
-    );
+  checkScalar(value);
   if (value === void 0 || value === null || typeof value !== "object")
     return value;
-  const prototype = Object.getPrototypeOf(value);
-  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
-    return value;
+  if (settled.has(value) || !isPlainContainer(value)) return value;
   if (ancestors.has(value))
     misuse(
       "runtime/non-serializable-value",
       "Runtime values cannot contain cycles"
     );
   ancestors.add(value);
+  copiedContainers++;
   const clone = Array.isArray(value) ? value.map((item) => cloneValue(item, ancestors)) : Object.fromEntries(
     Object.entries(value).map(([key, item]) => [
       key,
@@ -1950,16 +2139,17 @@ var TUPLE_LENGTHS = {
   mat4: 16,
   color: 4
 };
-function outputValue(value, definition, path6) {
+function outputValue(value, definition, path7, policy) {
+  const adopt = policy === "trust" ? trust : settle;
   if (definition.type !== "bundle" || !definition.fields)
-    return runtimeValue(value, definition.type, false, path6);
+    return runtimeValue(value, definition.type, false, path7, adopt);
   const fields = definition.fields;
   const problem = bundleValueProblem(value, fields);
-  if (problem) misuse("runtime/value-type", `${path6} ${problem}`);
+  if (problem) misuse("runtime/value-type", `${path7} ${problem}`);
   if (isBundleValue(value))
     for (const [field, item] of Object.entries(value))
-      runtimeValue(item, bundleFieldType(fields[field]), true, `${path6}.${field}`);
-  return runtimeValue(value, "bundle", false, path6);
+      runtimeValue(item, bundleFieldType(fields[field]), true, `${path7}.${field}`, (checked) => checked);
+  return runtimeValue(value, "bundle", false, path7, adopt);
 }
 function expressionPaths(expression) {
   const paths = [];
@@ -1977,17 +2167,17 @@ function readsBundleFields(node) {
       }
   return false;
 }
-function runtimeValue(value, type, allowUndefined, path6) {
+function runtimeValue(value, type, allowUndefined, path7, keep = snapshot) {
   if (value === void 0) {
     if (allowUndefined) return void 0;
-    misuse("runtime/value-type", `${path6} requires a ${type} value`);
+    misuse("runtime/value-type", `${path7} requires a ${type} value`);
   }
   const tupleLength = TUPLE_LENGTHS[type];
   const valid = type === "float" && typeof value === "number" && Number.isFinite(value) || type === "int" && typeof value === "number" && Number.isInteger(value) || type === "bool" && typeof value === "boolean" || type === "string" && typeof value === "string" || tupleLength !== void 0 && Array.isArray(value) && value.length === tupleLength && value.every(
     (item) => type.endsWith("i") ? typeof item === "number" && Number.isInteger(item) : typeof item === "number" && Number.isFinite(item)
   ) || type === "bundle" && isBundleValue(value) || !tupleLength && type !== "bundle" && type !== "float" && type !== "int" && type !== "bool" && type !== "string";
-  if (!valid) misuse("runtime/value-type", `${path6} is not a valid ${type}`);
-  return snapshot(value);
+  if (!valid) misuse("runtime/value-type", `${path7} is not a valid ${type}`);
+  return keep(value);
 }
 function sameValues(a, b, equal) {
   return a.length === b.length && a.every((value, index) => equal(value, b[index]));
@@ -2047,6 +2237,9 @@ function validateNodeModuleArchitecture(source, fileName, ts2) {
     (statement) => ts2.isVariableStatement(statement) && isDefinition(statement)
   );
   for (const statement of file.statements) {
+    if (ts2.isVariableStatement(statement) && !isDefinition(statement) && !supersededByDefinition(statement) && isPureConstant(statement)) {
+      continue;
+    }
     if (ts2.isVariableStatement(statement) && !isDefinition(statement)) {
       const superseded = supersededByDefinition(statement);
       add(
@@ -2111,6 +2304,48 @@ function validateNodeModuleArchitecture(source, fileName, ts2) {
     if (!declaration || !ts2.isIdentifier(declaration.name)) return null;
     return declaration.name.text === "icon" || declaration.name.text === "runsOn" ? declaration.name.text : null;
   }
+  function isPureConstant(statement) {
+    if (!(statement.declarationList.flags & ts2.NodeFlags.Const)) return false;
+    return statement.declarationList.declarations.every(
+      (declaration) => ts2.isIdentifier(declaration.name) && declaration.initializer !== void 0 && isPure(declaration.initializer, false)
+    );
+  }
+  function isPure(node, frozen) {
+    if (ts2.isNumericLiteral(node) || ts2.isStringLiteral(node) || ts2.isBigIntLiteral(node) || ts2.isNoSubstitutionTemplateLiteral(node) || node.kind === ts2.SyntaxKind.TrueKeyword || node.kind === ts2.SyntaxKind.FalseKeyword || node.kind === ts2.SyntaxKind.NullKeyword) return true;
+    if (ts2.isIdentifier(node)) return true;
+    if (ts2.isArrowFunction(node) || ts2.isFunctionExpression(node)) return true;
+    if (ts2.isParenthesizedExpression(node)) return isPure(node.expression, frozen);
+    if (ts2.isAsExpression(node))
+      return isPure(node.expression, frozen || isConstAssertion(node.type));
+    if (ts2.isSatisfiesExpression(node) || ts2.isNonNullExpression(node) || ts2.isTypeAssertionExpression(node))
+      return isPure(node.expression, frozen);
+    if (ts2.isPrefixUnaryExpression(node))
+      return node.operator !== ts2.SyntaxKind.PlusPlusToken && node.operator !== ts2.SyntaxKind.MinusMinusToken && isPure(node.operand, false);
+    if (ts2.isBinaryExpression(node))
+      return !isAssignment(node.operatorToken.kind) && isPure(node.left, false) && isPure(node.right, false);
+    if (ts2.isConditionalExpression(node))
+      return isPure(node.condition, false) && isPure(node.whenTrue, frozen) && isPure(node.whenFalse, frozen);
+    if (ts2.isTemplateExpression(node))
+      return node.templateSpans.every((span) => isPure(span.expression, false));
+    if (ts2.isPropertyAccessExpression(node)) return isPure(node.expression, false);
+    if (ts2.isElementAccessExpression(node))
+      return isPure(node.expression, false) && isPure(node.argumentExpression, false);
+    if (ts2.isArrayLiteralExpression(node))
+      return frozen && node.elements.every((element) => !ts2.isSpreadElement(element) && isPure(element, true));
+    if (ts2.isObjectLiteralExpression(node))
+      return frozen && node.properties.every((property) => ts2.isPropertyAssignment(property) ? !ts2.isComputedPropertyName(property.name) && isPure(property.initializer, true) : ts2.isShorthandPropertyAssignment(property));
+    if (ts2.isCallExpression(node) && ts2.isPropertyAccessExpression(node.expression) && ts2.isIdentifier(node.expression.expression) && node.expression.expression.text === "Object" && node.expression.name.text === "freeze" && node.arguments.length === 1) {
+      const [argument] = node.arguments;
+      return ts2.isArrayLiteralExpression(argument) ? argument.elements.every((element) => !ts2.isSpreadElement(element) && isPure(element, false)) : ts2.isObjectLiteralExpression(argument) ? argument.properties.every((property) => ts2.isPropertyAssignment(property) && !ts2.isComputedPropertyName(property.name) && isPure(property.initializer, false)) : false;
+    }
+    return false;
+  }
+  function isConstAssertion(type) {
+    return ts2.isTypeReferenceNode(type) && ts2.isIdentifier(type.typeName) && type.typeName.text === "const";
+  }
+  function isAssignment(kind) {
+    return kind >= ts2.SyntaxKind.FirstAssignment && kind <= ts2.SyntaxKind.LastAssignment;
+  }
   function isDefinition(statement) {
     return Boolean(statement.declarationList.flags & ts2.NodeFlags.Const) && Boolean(statement.modifiers?.some((item) => item.kind === ts2.SyntaxKind.ExportKeyword)) && statement.declarationList.declarations.length === 1 && ts2.isIdentifier(statement.declarationList.declarations[0].name) && statement.declarationList.declarations[0].name.text === "definition";
   }
@@ -2147,25 +2382,41 @@ function normalize(value) {
 }
 
 // src/cli/nodeFiles.ts
+import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+var KEYED_DIR = ".cascade-cache/keyed";
+var KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
 function createNodeFileCapability(project) {
   const within2 = (relative, what) => {
     try {
-      return project.resolve(relative.replace(/^\.?\//, ""));
+      const clean = relative.replace(/^\.?\//, "");
+      return what === "writing" ? project.resolve(clean) : project.resolveMedia(clean);
     } catch (error) {
       throw new Error(
         `files: ${what} outside the project is refused \u2014 ${relative} (${error instanceof Error ? error.message : String(error)})`
       );
     }
   };
-  const cacheOnly = (relative) => {
+  const writable = (relative) => {
     const clean = relative.replace(/^\.?\//, "");
-    if (!clean.startsWith(".cascade-cache/"))
+    const full = within2(clean, "writing");
+    if (!project.writeFolderOf(clean))
       throw new Error(
-        `files: writes are confined to .cascade-cache/ \u2014 got ${clean}. A node's output is derived data, and the same rule applies in the browser.`
+        `files: writes are confined to .cascade-cache/ and the folders cascade.json "writes" declares \u2014 got ${clean}. A node's output is derived data; declare an export folder such as "writes": ["renders"] to write named files.`
       );
-    return within2(clean, "writing");
+    return full;
+  };
+  const writeWhole2 = async (full, data) => {
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    const staging = `${full}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    await fs.writeFile(staging, data);
+    await fs.rename(staging, full);
+  };
+  const keyed = (key) => {
+    if (typeof key !== "string" || key.length > 512 || !KEY.test(key))
+      throw new Error(`files.cache: key ${JSON.stringify(key)} must be letters, digits, ".", "_" and "-" in "/"-separated parts, each starting with a letter or digit`);
+    return within2(`${KEYED_DIR}/${key}`, "writing");
   };
   const live = (options) => {
     if (options.signal.aborted) throw new Error("files: cancelled");
@@ -2177,9 +2428,22 @@ function createNodeFileCapability(project) {
     },
     async write(relative, data, options) {
       live(options);
-      const full = cacheOnly(relative);
-      await fs.mkdir(path.dirname(full), { recursive: true });
-      await fs.writeFile(full, data);
+      await writeWhole2(writable(relative), data);
+    },
+    cache: {
+      async get(key, options) {
+        live(options);
+        try {
+          return new Uint8Array(await fs.readFile(keyed(key)));
+        } catch (error) {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        }
+      },
+      async put(key, data, options) {
+        live(options);
+        await writeWhole2(keyed(key), data);
+      }
     },
     async list(relative, options) {
       live(options);
@@ -2211,56 +2475,198 @@ import { pathToFileURL } from "node:url";
 
 // src/cli/headlessIo.ts
 import crypto from "node:crypto";
+import { existsSync } from "node:fs";
 import fs2 from "node:fs/promises";
 import path2 from "node:path";
-
-// server/src/runtime/io.ts
-var IO_BRIDGE_KEY = "__cascadeIoBridge";
-function installIoBridge(bridge) {
-  const globals = globalThis;
-  const previous = globals[IO_BRIDGE_KEY];
-  globals[IO_BRIDGE_KEY] = bridge ?? void 0;
-  return () => {
-    globals[IO_BRIDGE_KEY] = previous;
-  };
-}
-
-// src/cli/headlessIo.ts
 var CACHE_DIR = ".cascade-cache";
 function contentAddressed(relative, body) {
-  const hash = crypto.createHash("sha1").update(body).digest("hex").slice(0, 12);
+  return addressed(relative, crypto.createHash("sha1").update(body).digest("hex").slice(0, 12));
+}
+function pixelAddressed(relative, pixels) {
+  const hash = crypto.createHash("sha1").update(`${pixels.width}x${pixels.height}\0`).update(pixels.data).digest("hex").slice(0, 12);
+  return addressed(relative, hash);
+}
+function addressed(relative, hash) {
   const directory = path2.posix.dirname(relative);
   const name = path2.posix.basename(relative);
   const [stem, ...rest] = name.split(".");
   const tail = rest.length ? `.${rest.join(".")}` : "";
   return path2.posix.join(directory, `${stem}.${hash}${tail}`);
 }
+var INTERMEDIATE_PNG = { level: 1, adaptiveFiltering: false };
+var FINAL_PNG = { level: 6, adaptiveFiltering: true };
+var sharpLoad;
+function loadSharp() {
+  sharpLoad ??= import("sharp").then((module) => module.default, () => null);
+  return sharpLoad;
+}
+async function encodePixelsPng(pixels, options = INTERMEDIATE_PNG) {
+  const sharp = await loadSharp();
+  if (sharp) {
+    const raw = Buffer.from(pixels.data.buffer, pixels.data.byteOffset, pixels.data.byteLength);
+    return sharp(raw, { raw: { width: pixels.width, height: pixels.height, channels: 4 } }).png({ compressionLevel: options.level, adaptiveFiltering: options.adaptiveFiltering }).toBuffer();
+  }
+  const Canvas = globalThis.OffscreenCanvas;
+  const Data = globalThis.ImageData;
+  if (!Canvas || !Data) throw new Error("cascade/io: cannot encode a PNG here (neither sharp nor a canvas is installed)");
+  const canvas = new Canvas(pixels.width, pixels.height);
+  canvas.getContext("2d").putImageData(new Data(pixels.data, pixels.width, pixels.height), 0, 0);
+  return new Uint8Array(await (await canvas.convertToBlob({ type: "image/png" })).arrayBuffer());
+}
+async function writeWhole(full, data) {
+  await fs2.mkdir(path2.dirname(full), { recursive: true });
+  const staging = `${full}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  await fs2.writeFile(staging, data);
+  await fs2.rename(staging, full);
+}
+var RESIDENT_BUDGET_BYTES = 512 * 1024 * 1024;
+var ResidentImages = class {
+  constructor(project, budget = RESIDENT_BUDGET_BYTES) {
+    this.project = project;
+    this.budget = budget;
+    this.held = /* @__PURE__ */ new Map();
+    this.bytes = 0;
+    /** Files written behind, for a test or a trace. */
+    this.encodes = 0;
+  }
+  /** Hold the pixels, start the write behind, return the path at once. */
+  keep(relative, pixels) {
+    const target = pixelAddressed(relative, pixels);
+    const known = this.held.get(target);
+    if (known) {
+      this.touch(target, known);
+      return target;
+    }
+    const full = this.project.resolve(target);
+    const entry = {
+      pixels,
+      done: false,
+      written: (async () => {
+        if (existsSync(full)) return;
+        this.encodes += 1;
+        await writeWhole(full, await encodePixelsPng(pixels, INTERMEDIATE_PNG));
+      })()
+    };
+    entry.written.then(() => {
+      entry.done = true;
+      this.trim();
+    }, () => {
+      entry.done = true;
+    });
+    this.held.set(target, entry);
+    this.bytes += pixels.data.byteLength;
+    this.trim();
+    return target;
+  }
+  /** The pixels behind a path, while held. */
+  pixels(relative) {
+    const entry = this.held.get(relative);
+    if (!entry) return void 0;
+    this.touch(relative, entry);
+    return entry.pixels;
+  }
+  /** Resolve when `relative` (or every held image) is a whole file. */
+  async settle(relative) {
+    if (relative !== void 0) {
+      await this.held.get(relative)?.written;
+      return;
+    }
+    await Promise.all([...this.held.values()].filter((entry) => !entry.done).map((entry) => entry.written));
+  }
+  touch(key, entry) {
+    this.held.delete(key);
+    this.held.set(key, entry);
+  }
+  /** Let the oldest written images go until under budget; a pending one stays. */
+  trim() {
+    if (this.bytes <= this.budget) return;
+    for (const [key, entry] of this.held) {
+      if (this.bytes <= this.budget) break;
+      if (!entry.done) continue;
+      this.held.delete(key);
+      this.bytes -= entry.pixels.data.byteLength;
+    }
+  }
+};
+var residentStores = /* @__PURE__ */ new Map();
+function residentImages(project) {
+  return residentStores.get(project.root);
+}
+async function settleProjectImages(project) {
+  await residentImages(project)?.settle();
+}
+async function copyImageFile(project, relative, destination) {
+  const clean = relative.replace(/^\.?\//, "");
+  const store = residentImages(project);
+  const pixels = /\.png$/i.test(clean) ? store?.pixels(clean) : void 0;
+  if (pixels) {
+    await writeWhole(destination, await encodePixelsPng(pixels, FINAL_PNG));
+    return;
+  }
+  await store?.settle(clean);
+  await fs2.copyFile(project.resolveMedia(clean), destination);
+}
 function createIoBridge(project) {
-  return {
+  const confined = (relative) => {
+    const clean = relative.replace(/^\.?\//, "");
+    if (!clean.startsWith(`${CACHE_DIR}/`)) {
+      throw new Error(`cascade/io: writes are confined to ${CACHE_DIR}/ \u2014 got ${clean}`);
+    }
+    return clean;
+  };
+  const bridge = {
+    /** An intermediate image: held in memory when the run keeps pixels, else a fast PNG now. */
+    async keep(relative, pixels) {
+      const clean = confined(relative);
+      if (!pixels.width || !pixels.height) throw new Error(`cascade/io: refusing to store an empty image to ${clean}`);
+      const store = residentImages(project);
+      if (store) return store.keep(clean, pixels);
+      const target = pixelAddressed(clean, pixels);
+      const full = project.resolve(target);
+      if (!existsSync(full)) await writeWhole(full, await encodePixelsPng(pixels, INTERMEDIATE_PNG));
+      return target;
+    },
+    pixels(relative) {
+      return residentImages(project)?.pixels(relative.replace(/^\.?\//, ""));
+    },
     async read(relative) {
-      const full = project.resolveMedia(relative.replace(/^\.?\//, ""));
+      const clean = relative.replace(/^\.?\//, "");
+      const full = project.resolveMedia(clean);
       try {
+        await residentImages(project)?.settle(clean);
         return await fs2.readFile(full);
       } catch (error) {
         throw new Error(`cascade/io: cannot load ${relative} \u2014 ${error instanceof Error ? error.message : error}`);
       }
     },
     async write(relative, data) {
-      const clean = relative.replace(/^\.?\//, "");
-      if (!clean.startsWith(`${CACHE_DIR}/`)) {
-        throw new Error(`cascade/io: writes are confined to ${CACHE_DIR}/ \u2014 got ${clean}`);
-      }
+      const clean = confined(relative);
       if (!data.byteLength) throw new Error(`cascade/io: refusing to write an empty file to ${clean}`);
       const target = contentAddressed(clean, data);
-      const full = project.resolve(target);
-      await fs2.mkdir(path2.dirname(full), { recursive: true });
-      await fs2.writeFile(full, data);
+      await writeWhole(project.resolve(target), data);
       return target;
     }
   };
+  return bridge;
 }
-function installProjectIo(project) {
-  return installIoBridge(createIoBridge(project));
+function installProjectIo(project, options = {}) {
+  let removeStore = () => {
+  };
+  if (options.resident) {
+    const store = new ResidentImages(project);
+    const previous = residentStores.get(project.root);
+    residentStores.set(project.root, store);
+    removeStore = () => {
+      if (residentStores.get(project.root) !== store) return;
+      if (previous) residentStores.set(project.root, previous);
+      else residentStores.delete(project.root);
+    };
+  }
+  const removeBridge = installIoBridge(createIoBridge(project));
+  return () => {
+    removeBridge();
+    removeStore();
+  };
 }
 
 // src/cli/nodeAssets.ts
@@ -2280,7 +2686,18 @@ function createNodeAssetCapability(project) {
       const written = await io.write(`${CACHE_DIR2}/${assetFileName(metadata.suggestedName)}`, data);
       return { path: written, ...metadata.mediaType ? { mediaType: metadata.mediaType } : {} };
     },
+    // `cascade/image`'s `writeImage` hands an intermediate over as pixels:
+    // the same file policy as `write`, through the bridge's fast PNG.
+    async keepImage(pixels, metadata) {
+      const written = await io.keep(`${CACHE_DIR2}/${assetFileName(metadata.suggestedName)}`, pixels);
+      return { path: written, mediaType: "image/png" };
+    },
+    // And reads them back from memory while the run holds them.
+    imagePixels(ref) {
+      return io.pixels(String(ref.path));
+    },
     async resolveUrl(ref) {
+      await settleProjectImages(project);
       const full = project.resolveMedia(String(ref.path).replace(/^\.?\//, ""));
       return { value: pathToFileURL(full).href, release: () => {
       } };
@@ -2300,24 +2717,43 @@ function looksLikeImage(value) {
   return IMAGE_EXTENSIONS.has(path4.extname(file).toLowerCase());
 }
 function collectImageOutputs(graph, options = {}) {
+  return planImageOutputs(graph, options).collect();
+}
+function planImageOutputs(graph, options = {}) {
   const wanted = new Set(options.nodes ?? []);
   const extra = new Set(options.extra ?? []);
-  const found = [];
   const inspection = graph.inspect();
   const isAssertion = (moduleId2) => moduleId2.startsWith("cascade.assert.");
   const assertions = new Set(inspection.nodes.filter((node) => isAssertion(node.moduleId)).map((node) => node.id));
   const consumed = new Set(inspection.connections.filter((connection) => !assertions.has(connection.target.nodeId)).map((connection) => `${connection.source.nodeId}\0${connection.source.outputName}`));
+  const candidates = [];
   for (const node of inspection.nodes) {
     const named = wanted.has(node.id) || extra.has(node.id);
     if (wanted.size && !named) continue;
     if (!named && assertions.has(node.id)) continue;
-    const ports = Object.entries(node.outputs).filter(([, port]) => port.value !== void 0 && (port.type === "image" || port.type === "any" && looksLikeImage(port.value)));
-    for (const [name, port] of ports) {
-      if (!named && port.connected && consumed.has(`${node.id}\0${name}`)) continue;
-      found.push({ nodeId: node.id, port: name, value: port.value, shared: ports.length > 1 });
-    }
+    const ports = Object.entries(node.outputs).filter(([, port]) => port.type === "image" || port.type === "any").map(([name, port]) => ({
+      name,
+      type: port.type,
+      // Consumed downstream: not a final image, though it still counts
+      // towards `shared` when it carries one.
+      skip: !named && port.connected && consumed.has(`${node.id}\0${name}`)
+    }));
+    if (ports.length) candidates.push({ nodeId: node.id, ports });
   }
-  return found;
+  return {
+    collect() {
+      const found = [];
+      for (const candidate of candidates) {
+        const values = graph.getOutputs(candidate.nodeId);
+        const ports = candidate.ports.map((port) => ({ ...port, value: values.get(port.name) })).filter((port) => port.value !== void 0 && (port.type === "image" || looksLikeImage(port.value)));
+        for (const port of ports) {
+          if (port.skip) continue;
+          found.push({ nodeId: candidate.nodeId, port: port.name, value: port.value, shared: ports.length > 1 });
+        }
+      }
+      return found;
+    }
+  };
 }
 function unknownNodes(graph, ids) {
   const known = new Set(graph.inspect().nodes.map((node) => node.id));
@@ -2346,7 +2782,8 @@ async function saveStillImages(graph, project, options) {
       continue;
     }
     const name = stillFileName(output, relative);
-    await fs3.copyFile(source, path4.join(out.directory, name));
+    if (path4.isAbsolute(relative)) await fs3.copyFile(source, path4.join(out.directory, name));
+    else await copyImageFile(project, relative, path4.join(out.directory, name));
     saved.push({ node: output.nodeId, port: output.port, source, file: out.spell(name) });
   }
   if (out && !saved.length) {
@@ -2378,7 +2815,7 @@ function createDawnGpuHost() {
       try {
         const adapter = await gpu.requestAdapter();
         if (!adapter) throw new Error("Dawn found no WebGPU adapter. Check GPU drivers and backend availability; headless rendering still needs a hardware or explicitly configured software adapter.");
-        device = await adapter.requestDevice();
+        device = await requestDeviceWithAdapterLimits(adapter);
         const info = adapter.info;
         return { device, info: {
           vendor: info.vendor,
@@ -2397,9 +2834,376 @@ function createDawnGpuHost() {
   });
 }
 
+// src/cli/nodeShape.ts
+var LONG_EXECUTE_LINES = 150;
+var MIXED_JOB_COUNT = 4;
+var JOB_ORDER = ["load", "generate", "colour", "draw", "export"];
+var BY_NAME = {
+  load: /^(readFile(Sync)?|loadImage|loadFont|loadJson|readJson|fetch|decodeImage)$/,
+  generate: /^(random|rng|hash\d*|noise\w*|\w*[nN]oise\d*|fbm|simplex\w*|perlin\w*|worley\w*|poisson\w*|scatter\w*)$/,
+  colour: /^(oklch|oklab|\w*[oO]klab\w*|\w*[oO]klch\w*|okMix|hsl\w*|palette\w*|mixColou?r|lerpColou?r|\w*Palette)$/,
+  draw: /^(getContext|beginPath|fillRect|strokeRect|drawImage|putImageData|createImageData|arc|lineTo|createRenderPipeline|createComputePipeline|draw|drawIndexed|dispatchWorkgroups)$/,
+  export: /^(writeFile(Sync)?|savePng|saveSvg|saveJpe?g|toBuffer|toBlob|toDataURL|encodePng|encodeJpe?g|encodeImage)$/
+};
+var CAPABILITY_RECEIVER = /(^|\.)(files|assets)$/;
+function measureNodeShape(source, fileName, ts2) {
+  const file = ts2.createSourceFile(fileName, source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TS);
+  let executeLines = null;
+  let executeLine = null;
+  const jobs = /* @__PURE__ */ new Set();
+  for (const statement of file.statements) {
+    const body = executeBody(statement);
+    if (!body) continue;
+    const start = file.getLineAndCharacterOfPosition(body.getStart(file)).line;
+    const end = file.getLineAndCharacterOfPosition(body.getEnd()).line;
+    executeLines = end - start + 1;
+    executeLine = file.getLineAndCharacterOfPosition(statement.getStart(file)).line + 1;
+  }
+  visit(file);
+  return { executeLines, executeLine, jobs: JOB_ORDER.filter((job) => jobs.has(job)) };
+  function executeBody(statement) {
+    if (ts2.isFunctionDeclaration(statement) && statement.name?.text === "execute") return statement.body;
+    if (ts2.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts2.isIdentifier(declaration.name) || declaration.name.text !== "execute") continue;
+        const init = declaration.initializer;
+        if (init && (ts2.isArrowFunction(init) || ts2.isFunctionExpression(init))) return init.body;
+      }
+    }
+    return void 0;
+  }
+  function visit(node) {
+    if (ts2.isCallExpression(node)) classify(node.expression);
+    ts2.forEachChild(node, visit);
+  }
+  function classify(callee) {
+    let name;
+    if (ts2.isIdentifier(callee)) name = callee.text;
+    else if (ts2.isPropertyAccessExpression(callee)) {
+      name = callee.name.text;
+      const receiver = callee.expression.getText(file);
+      if (CAPABILITY_RECEIVER.test(receiver)) {
+        if (/^(read|list|stat|resolveUrl)$/.test(name)) jobs.add("load");
+        if (name === "write") jobs.add("export");
+      }
+      if (receiver === "Math" && name === "random") {
+        jobs.add("generate");
+        return;
+      }
+    }
+    if (!name) return;
+    for (const job of JOB_ORDER) if (BY_NAME[job].test(name)) jobs.add(job);
+  }
+}
+function nodeShapeWarnings(source, fileName, ts2, moduleId2) {
+  const shape = measureNodeShape(source, fileName, ts2);
+  const where = moduleId2 ?? fileName;
+  const out = [];
+  if (shape.executeLines !== null && shape.executeLines > LONG_EXECUTE_LINES) {
+    out.push({
+      phase: "shape",
+      code: "shape/long-execute",
+      message: `${where}: execute is ${shape.executeLines} lines (over ${LONG_EXECUTE_LINES}). Split it into single-job nodes wired in the graph.`,
+      file: fileName,
+      line: shape.executeLine ?? void 0
+    });
+  }
+  const loadsAndExports = shape.jobs.includes("load") && shape.jobs.includes("export") && shape.jobs.length > 2;
+  if (shape.jobs.length >= MIXED_JOB_COUNT || loadsAndExports) {
+    out.push({
+      phase: "shape",
+      code: "shape/mixed-jobs",
+      message: `${where}: one node does ${shape.jobs.join(", ")} (judged from the calls it makes). Give each job its own node.`,
+      file: fileName
+    });
+  }
+  return out;
+}
+function reportNodeShape(warnings) {
+  if (!warnings.length) return;
+  console.warn([
+    `Node shape \u2014 ${warnings.length === 1 ? "one warning" : `${warnings.length} warnings`} (advice only, the check still passes):`,
+    ...warnings.map((item) => `  ${item.code}: ${item.message}`),
+    '  See "Design the graph" in doc/PROJECT_AUTHORING.md.'
+  ].join("\n"));
+}
+
+// server/src/runtime/stage.ts
+var BRIDGE_KEY = "__cascadeStageBridge";
+function installStageBridge(bridge) {
+  const globals = globalThis;
+  const previous = globals[BRIDGE_KEY];
+  globals[BRIDGE_KEY] = bridge ?? void 0;
+  return () => {
+    globals[BRIDGE_KEY] = previous;
+  };
+}
+
+// src/cli/projectStages.ts
+function stageWorkerCount(config, poolSize) {
+  if (poolSize !== void 0) return Math.max(1, Math.floor(poolSize));
+  const fromEnv = Number(process.env.CASCADE_STAGE_WORKERS);
+  if (Number.isInteger(fromEnv) && fromEnv >= 1) return fromEnv;
+  return config.workers ?? defaultStageWorkerCount();
+}
+var LANES_KEY = "__cascadeStageLanes";
+function installedStageLanes() {
+  const lanes = globalThis[LANES_KEY];
+  return typeof lanes === "number" && lanes > 1 ? lanes : 1;
+}
+function installProjectStages(project, options = {}) {
+  let worker = null;
+  const warmWorker = (config) => {
+    if (options.worker === false || !config.worker) return null;
+    const entrypoint = config.worker;
+    const sources = stageSources(project, config);
+    const size = stageWorkerCount(config, options.poolSize);
+    const key = `${config.python}\0${entrypoint}\0${sources.roots.join("\0")}\0${size}`;
+    if (worker?.key !== key) {
+      worker?.process.shutdown();
+      worker = {
+        key,
+        process: new PythonWorkerPool(size, () => new PythonWorker(project, entrypoint, config.python, process.env, {
+          sources,
+          // The one-shot path's bound, not Studio's two minutes: an offline
+          // render may run a stage for several.
+          requestTimeoutMs: 10 * 60 * 1e3,
+          // What a stage prints is shown with --verbose only, as before.
+          onStderr: options.onOutput ? (text) => {
+            for (const line2 of text.split("\n")) options.onOutput(null, "stderr", line2);
+          } : options.verbose ? (text) => {
+            for (const line2 of text.split("\n")) console.warn(`[stage-worker] ${line2}`);
+          } : () => {
+          }
+        }))
+      };
+    }
+    return worker.process;
+  };
+  const globals = globalThis;
+  const previousLanes = globals[LANES_KEY];
+  try {
+    const config = readStageConfig(project);
+    globals[LANES_KEY] = options.worker === false || !config.worker ? 1 : stageWorkerCount(config, options.poolSize);
+  } catch {
+    globals[LANES_KEY] = 1;
+  }
+  if (options.prewarm) {
+    try {
+      warmWorker(readStageConfig(project))?.warm();
+    } catch {
+    }
+  }
+  const dispose = installStageBridge(async (stage, args, callOptions) => {
+    await settleProjectImages(project);
+    const config = readStageConfig(project);
+    const warm = warmWorker(config);
+    if (warm) {
+      const { result: result2 } = await callStage(project, config, stage, args, (envelope) => warm.callWithMeta(stage, args, { signal: callOptions?.signal, cascade: envelope }), { onTrace: options.onTrace });
+      return result2;
+    }
+    const { result } = await callStage(project, config, stage, args, async (envelope) => ({
+      result: await runProjectStage(project, stage, args, {
+        // A superseded cook kills its subprocess rather than waiting for it.
+        signal: callOptions?.signal,
+        cascade: envelope,
+        codeHash: envelope.code,
+        /**
+         * A stage can log, and until 0.8 nobody could read it: `stderr` was
+         * consulted only on failure and `stdout` only for its last line. Behind
+         * `--verbose`, because a stage that prints per mark would bury the
+         * render it is part of; prefixed with the stage name, because a graph
+         * runs several.
+         */
+        onOutput: options.onOutput ? (stream, text) => {
+          for (const line2 of text.split("\n")) options.onOutput(stage, stream, line2);
+        } : options.verbose ? (stream, text) => {
+          const write = stream === "stderr" ? console.warn : console.log;
+          for (const line2 of text.split("\n")) write(`[${stage}] ${line2}`);
+        } : void 0
+      })
+    }), { onTrace: options.onTrace });
+    return result;
+  });
+  return () => {
+    dispose();
+    globals[LANES_KEY] = previousLanes;
+    worker?.process.shutdown();
+    worker = null;
+  };
+}
+
+// src/cli/runTrace.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import fs4 from "node:fs";
+import path5 from "node:path";
+var MAX_NODE_LOGS = 500;
+var MAX_LOG_LINE = 2e3;
+var cookingNode = new AsyncLocalStorage();
+function traceNodeScope(nodeId, run) {
+  return cookingNode.run(nodeId, run);
+}
+var RunTrace = class {
+  constructor(graphFile, cascade, seed) {
+    this.graphFile = graphFile;
+    this.cascade = cascade;
+    this.seed = seed;
+    this.runs = [];
+    this.current = null;
+    /** Nodes of the latest run still cooking, by id. */
+    this.cooking = /* @__PURE__ */ new Map();
+    /** Stage calls made outside any node (a run with no graph events). */
+    this.loose = [];
+    this.startedAt = /* @__PURE__ */ new Date();
+    this.runStarted = null;
+    this.envNames = [];
+  }
+  /** The node a stage call or log line belongs to. */
+  owner() {
+    const id = cookingNode.getStore();
+    if (id !== void 0) {
+      const scoped = this.cooking.get(id)?.node;
+      if (scoped) return scoped;
+    }
+    return this.current?.node;
+  }
+  /** Follow one loaded graph's events. Returns the unsubscribe. */
+  attach(graph) {
+    const modules = new Map(graph.inspect().nodes.map((node) => [node.id, node.moduleId]));
+    return graph.subscribe((event) => {
+      if (event.type === "run:start") {
+        this.runs.push({ runId: event.runId, frame: graph.getFrame(), nodes: [] });
+        this.runStarted = performance.now();
+      } else if (event.type === "run:complete") {
+        const run = this.runs[this.runs.length - 1];
+        if (run && this.runStarted !== null) run.ms = Math.round(performance.now() - this.runStarted);
+        this.runStarted = null;
+      } else if (event.type === "node:start") {
+        const run = this.runs[this.runs.length - 1];
+        if (!run) return;
+        const node = { id: event.nodeId, module: modules.get(event.nodeId) ?? "", ms: 0, stages: [] };
+        run.nodes.push(node);
+        this.current = { node, started: performance.now() };
+        this.cooking.set(event.nodeId, this.current);
+      } else if (event.type === "node:complete") {
+        const cooking = this.cooking.get(event.nodeId);
+        if (!cooking) return;
+        cooking.node.ms = Math.round(performance.now() - cooking.started);
+        this.cooking.delete(event.nodeId);
+        if (this.current === cooking) this.current = null;
+      }
+    });
+  }
+  /**
+   * The latest run's whole frame took `frameMs`, its outputs saved: what is
+   * left after the cook is the save. Called by the frame loop per frame and
+   * once by a still run.
+   */
+  recordSaved(frameMs) {
+    const run = this.runs[this.runs.length - 1];
+    if (!run) return;
+    run.frameMs = Math.round(frameMs);
+    if (run.ms !== void 0) run.saveMs = Math.max(0, run.frameMs - run.ms);
+  }
+  /** Record a stage call against the node cooking now. */
+  recordStage(trace) {
+    const node = this.owner();
+    if (node) node.stages.push(trace);
+    else this.loose.push(trace);
+  }
+  /**
+   * Record a line printed while a node cooks, against that node. Returns
+   * false when no node is cooking, so the caller leaves the line alone (the
+   * CLI's own messages are not node output).
+   */
+  recordLog(level, text) {
+    const node = this.owner();
+    if (!node) return false;
+    for (const line2 of text.split("\n")) {
+      if (!line2.trim()) continue;
+      node.logs ??= [];
+      if (node.logs.length >= MAX_NODE_LOGS) {
+        node.logsDropped = (node.logsDropped ?? 0) + 1;
+        continue;
+      }
+      node.logs.push({ level, text: line2.length > MAX_LOG_LINE ? `${line2.slice(0, MAX_LOG_LINE)}\u2026` : line2 });
+    }
+    return true;
+  }
+  /** Every logged line in order, with its node. */
+  logs() {
+    return this.runs.flatMap((run) => run.nodes.flatMap((node) => (node.logs ?? []).map((line2) => ({ node: node.id, ...line2 }))));
+  }
+  /** The names (never the values) of variables `--env` set, for the trace. */
+  setEnvNames(names) {
+    this.envNames = [...names];
+  }
+  /** Every stage call in order, with its node. */
+  stages() {
+    const list = [];
+    for (const run of this.runs) {
+      for (const node of run.nodes) for (const stage of node.stages) list.push({ node: node.id, ...stage });
+    }
+    for (const stage of this.loose) list.push({ node: null, ...stage });
+    return list;
+  }
+  toJSON() {
+    return {
+      format: 1,
+      graph: this.graphFile,
+      startedAt: this.startedAt.toISOString(),
+      cascade: this.cascade,
+      seed: this.seed,
+      ...this.envNames.length ? { env: this.envNames } : {},
+      runs: this.runs
+    };
+  }
+  /** Write the trace into the project and return its project-relative path. */
+  write(projectRoot) {
+    const stamp = this.startedAt.toISOString().replace(/[:.]/g, "-");
+    const name = `${stamp}-${path5.basename(this.graphFile, ".cascade")}.json`;
+    const relative = path5.posix.join(".cascade", "runs", name);
+    const full = path5.join(projectRoot, relative);
+    fs4.mkdirSync(path5.dirname(full), { recursive: true });
+    fs4.writeFileSync(full, JSON.stringify(this.toJSON(), null, 2) + "\n");
+    pruneTraces(path5.dirname(full));
+    return relative;
+  }
+};
+var CONSOLE_LEVELS = ["log", "info", "warn", "error", "debug"];
+function captureNodeConsole(trace) {
+  const original = Object.fromEntries(CONSOLE_LEVELS.map((level) => [level, console[level]]));
+  for (const level of CONSOLE_LEVELS) {
+    console[level] = (...args) => {
+      trace.recordLog(level, args.map((arg) => typeof arg === "string" ? arg : arg instanceof Error ? arg.stack ?? arg.message : safeJson(arg)).join(" "));
+      original[level](...args);
+    };
+  }
+  return () => {
+    for (const level of CONSOLE_LEVELS) console[level] = original[level];
+  };
+}
+function safeJson(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+var KEPT_TRACES = 200;
+function pruneTraces(directory) {
+  const traces = fs4.readdirSync(directory).filter((name) => name.endsWith(".json")).sort();
+  for (const name of traces.slice(0, Math.max(0, traces.length - KEPT_TRACES))) {
+    fs4.rmSync(path5.join(directory, name), { force: true });
+  }
+}
+
 // src/cli/projectRuntime.ts
+function headlessExecution() {
+  return { values: "trust", concurrency: installedStageLanes(), nodeScope: traceNodeScope };
+}
 function createProjectHost(file, registrations) {
-  const project = new ProjectRoot(path5.dirname(path5.resolve(file)));
+  const project = new ProjectRoot(path6.dirname(path6.resolve(file)));
   return createNodeRuntimeHost({
     modules: resolver(registrations),
     shell: project.shell,
@@ -2524,6 +3328,7 @@ async function checkProjectGraph(file, document2, strict = false) {
     throw new Error(`Static check requires definition-v1 modules; dynamic modules: ${dynamic.join(", ")}`);
   }
   await preflightAgainstRunHost(file, prepared.registrations, document2);
+  reportNodeShape(prepared.shape);
   return unresolved;
 }
 async function runDeterministicProjectGraph(file, document2, entryNode, observe, afterRun) {
@@ -2533,7 +3338,10 @@ async function runDeterministicProjectGraph(file, document2, entryNode, observe,
   const host = createProjectHost(file, prepared.registrations);
   const runtime = createRuntime({
     host,
-    nodes: prepared.registrations
+    nodes: prepared.registrations,
+    // A run trusts what its nodes hand over instead of walking it to freeze
+    // (Studio and `cook` keep `"freeze"`), and overlaps independent stages.
+    ...headlessExecution()
   });
   let graph;
   try {
@@ -2547,6 +3355,7 @@ async function runDeterministicProjectGraph(file, document2, entryNode, observe,
     if (result.status !== "completed") {
       throw new Error(result.diagnostics.map((item) => item.message).join("\n") || `Graph ${result.status}`);
     }
+    await settleProjectImages({ root: path6.dirname(path6.resolve(file)) });
     await afterRun?.(graph);
     return true;
   } finally {
@@ -2570,6 +3379,7 @@ async function cookProjectGraph(file, document2, target, observe) {
     const result = await graph.run(target ? { target: { kind: "node", nodeId: target } } : {});
     if (result.status !== "completed")
       throw new Error(result.diagnostics.map((item) => item.message).join("\n") || `Graph ${result.status}`);
+    await settleProjectImages({ root: path6.dirname(path6.resolve(file)) });
     const outputs = /* @__PURE__ */ new Map();
     for (const node of graph.inspect().nodes) outputs.set(node.id, new Map(graph.getOutputs(node.id)));
     return { outputs, assets: host.capabilities?.assets };
@@ -2585,11 +3395,15 @@ async function renderDeterministicProjectFrames(file, document2, options) {
   const prepared = await prepare(file, document2, true);
   reportUnresolved(prepared);
   if (!usesDeterministicHost(document2, prepared)) return null;
-  const project = new ProjectRoot(path5.dirname(path5.resolve(file)));
+  const project = new ProjectRoot(path6.dirname(path6.resolve(file)));
   const host = createProjectHost(file, prepared.registrations);
   const runtime = createRuntime({
     host,
-    nodes: prepared.registrations
+    nodes: prepared.registrations,
+    // Every frame hands over fresh values; walking them to freeze was most
+    // of a big-array frame. Independent stages (the morph's four renders)
+    // cook side by side on the stage pool.
+    ...headlessExecution()
   });
   let graph;
   const width = sequenceWidth(options.end);
@@ -2605,9 +3419,10 @@ async function renderDeterministicProjectFrames(file, document2, options) {
     const targets = options.nodes?.length ? options.nodes : options.entryNode ? [options.entryNode] : [];
     const extra = options.outNodes ?? [];
     const out = outDirectory(options.out, (relative) => project.resolve(relative));
-    await fs4.mkdir(out.directory, { recursive: true });
+    await fs5.mkdir(out.directory, { recursive: true });
     const missing = unknownNodes(graph, [...targets, ...extra]);
     if (missing.length) throw new Error(`No node ${missing.map((id) => `"${id}"`).join(", ")} in this graph (--node/--out-node take node ids; cascade graph read lists them).`);
+    const imageOutputs = planImageOutputs(graph, { nodes: targets, extra });
     for await (const frame of options.frameSource ?? frameRange(options.start, options.end, options.step ?? 1)) {
       const frameStarted = performance.now();
       if (options.signal?.aborted) {
@@ -2639,7 +3454,7 @@ async function renderDeterministicProjectFrames(file, document2, options) {
           `frame ${frame} ${result.status} \u2014 ${result.diagnostics.map((item) => item.message).join("; ") || "no diagnostics"}`
         );
       }
-      const outputs = collectImageOutputs(graph, { nodes: targets, extra });
+      const outputs = imageOutputs.collect();
       if (!outputs.length) {
         throw new Error(
           targets.length || extra.length ? `No image output on ${[...targets, ...extra].join(", ")} \u2014 check that the node has an image output (or a Null passing one).` : "No image output to save: the graph has no unconsumed image port. Name the node to render with --node, or a mid-graph one to save as well with --out-node."
@@ -2651,7 +3466,7 @@ async function renderDeterministicProjectFrames(file, document2, options) {
         if (!source) continue;
         const name = sequenceFileName(output.nodeId, frame, source, width, output.shared ? output.port : void 0);
         const relative = source.replace(/^\.?\//, "");
-        await fs4.copyFile(project.resolveMedia(relative), path5.join(out.directory, name));
+        await copyImageFile(project, relative, path6.join(out.directory, name));
         files.push(out.spell(name));
         written.push({ nodeId: output.nodeId, port: output.port, source: relative, file: out.spell(name) });
       }
@@ -2659,6 +3474,7 @@ async function renderDeterministicProjectFrames(file, document2, options) {
       await options.onFrame?.({ frame, outputs: written, durationMs: performance.now() - frameStarted });
       if (options.verbose) console.log(`  frame ${frame}`);
     }
+    await settleProjectImages(project);
     try {
       gpu = { renderer: "dawn", adapter: host.capabilities.gpu.adapterInfo };
     } catch {
@@ -2691,7 +3507,7 @@ async function inspectProjectGraph(file, document2) {
     };
   });
   return {
-    file: path5.resolve(file),
+    file: path6.resolve(file),
     version: document2.version ?? null,
     deterministic: nodes.length > 0 && nodes.every((node) => node.classification === "definition-v1"),
     nodes,
@@ -2702,11 +3518,12 @@ async function prepare(file, document2, compileExecutors) {
   if (!document2 || typeof document2 !== "object" || !Array.isArray(document2.nodes)) {
     throw new Error("Graph document must contain a nodes array");
   }
-  const projectRoot = path5.dirname(path5.resolve(file));
+  const projectRoot = path6.dirname(path6.resolve(file));
   const registrations = [];
   const deterministic = /* @__PURE__ */ new Set();
   const seen = /* @__PURE__ */ new Set();
   const unresolved = [];
+  const shape = [];
   for (const node of document2.nodes) {
     const id = moduleId(node);
     if (!id || seen.has(id)) continue;
@@ -2728,7 +3545,7 @@ async function prepare(file, document2, compileExecutors) {
       registrations.push(savedRegistration(id, node));
       continue;
     }
-    const source = await fs4.readFile(moduleFile, "utf8");
+    const source = await fs5.readFile(moduleFile, "utf8");
     const mentionsDefinition = /\bexport\s+const\s+definition\b/.test(source);
     const extracted = extractNodeDefinition(source, moduleFile, ts);
     if (!extracted.ok) {
@@ -2744,24 +3561,34 @@ async function prepare(file, document2, compileExecutors) {
     if (architectureDiagnostics.length) {
       throw new Error(architectureDiagnostics.map(formatDiagnostic).join("\n"));
     }
+    shape.push(...nodeShapeWarnings(source, moduleFile, ts, id));
     let executor;
     deterministic.add(id);
     registrations.push({
       kind: "definition-v1",
       moduleId: id,
       definition: extracted.definition,
-      loadExecute: compileExecutors ? () => executor ??= compileExecute(projectRoot, moduleFile) : async () => {
+      loadExecute: compileExecutors ? () => executor ??= compileExecute(projectRoot, moduleFile).then((execute) => (
+        // A server node may read an image input with `node:fs`, the one
+        // reader the host cannot make wait, so it starts once every image
+        // written behind is on disk. Portable and browser nodes cannot
+        // reach the filesystem and keep the in-memory handoff.
+        extracted.definition.runsOn === "server" ? async (...args) => {
+          await settleProjectImages({ root: projectRoot });
+          return execute(...args);
+        } : execute
+      )) : async () => {
         throw new Error("Static validation never loads execute");
       }
     });
   }
-  return { registrations, deterministic, unresolved };
+  return { registrations, deterministic, unresolved, shape };
 }
 async function projectModuleFile(root, node, id) {
   const tried = [];
   const source = node.source;
   if (source && typeof source === "object" && source.type === "project" && typeof source.file === "string") {
-    const candidate2 = path5.resolve(root, source.file);
+    const candidate2 = path6.resolve(root, source.file);
     if (within(root, candidate2)) {
       tried.push(candidate2);
       if (await exists(candidate2)) return { file: candidate2, tried };
@@ -2769,7 +3596,7 @@ async function projectModuleFile(root, node, id) {
   }
   if (!id.startsWith("project.")) return { file: null, tried };
   const name = id.slice("project.".length);
-  const candidate = path5.resolve(root, "nodes", name, "index.ts");
+  const candidate = path6.resolve(root, "nodes", name, "index.ts");
   if (!within(root, candidate)) return { file: null, tried };
   tried.push(candidate);
   return { file: await exists(candidate) ? candidate : null, tried };
@@ -2787,7 +3614,7 @@ function reExportedDefinition(source) {
   });
 }
 function unresolvedModule(id, node, tried, root) {
-  const relative = tried.map((candidate) => path5.relative(root, candidate) || candidate);
+  const relative = tried.map((candidate) => path6.relative(root, candidate) || candidate);
   const where = relative.length ? `looked for ${relative.join(" and ")}` : `no project file is possible for this module id \u2014 a project module is named "project.<dir>" or carries a source file`;
   return {
     phase: "prepare",
@@ -2797,9 +3624,9 @@ function unresolvedModule(id, node, tried, root) {
   };
 }
 async function compileExecute(projectRoot, moduleFile) {
-  const cache = path5.join(projectRoot, ".cascade-cache", "nodes");
-  await fs4.mkdir(cache, { recursive: true });
-  const output = path5.join(cache, `${path5.basename(path5.dirname(moduleFile))}.mjs`);
+  const cache = path6.join(projectRoot, ".cascade-cache", "nodes");
+  await fs5.mkdir(cache, { recursive: true });
+  const output = path6.join(cache, `${path6.basename(path6.dirname(moduleFile))}.mjs`);
   const staging = `${output}.${process.pid}.${Date.now()}.tmp`;
   await build({
     entryPoints: [moduleFile],
@@ -2812,24 +3639,27 @@ async function compileExecute(projectRoot, moduleFile) {
     sourcemap: "inline",
     plugins: [cliImageModule()]
   });
-  await fs4.rename(staging, output);
+  await fs5.rename(staging, output);
   const loaded = await import(`${pathToFileURL2(output).href}?v=${Date.now()}`);
   if (typeof loaded.execute !== "function") throw new Error(`${moduleFile} does not export execute`);
   return loaded.execute;
 }
 function cliImageModule() {
-  const here = path5.dirname(fileURLToPath(import.meta.url));
-  const source = [
-    path5.join(here, "runtime", "image.ts"),
+  const here = path6.dirname(fileURLToPath(import.meta.url));
+  const shim = (name) => [
+    path6.join(here, "runtime", `${name}.ts`),
     // dist/cli/runtime, copied by build-cli
-    path5.join(here, "..", "..", "server", "src", "runtime", "image.ts")
+    path6.join(here, "..", "..", "server", "src", "runtime", `${name}.ts`)
     // running from src
-  ].find((candidate) => existsSync(candidate));
+  ].find((candidate) => existsSync2(candidate));
+  const sources = { image: shim("image"), io: shim("io") };
   return {
     name: "cascade-cli-image",
     setup(builder) {
-      if (!source) return;
-      builder.onResolve({ filter: /^(?:@field\/)?cascade\/image$/ }, () => ({ path: source }));
+      builder.onResolve({ filter: /^(?:@field\/)?cascade\/(?:image|io)$/ }, (args) => {
+        const source = sources[args.path.endsWith("/io") ? "io" : "image"];
+        return source ? { path: source } : void 0;
+      });
     }
   };
 }
@@ -2919,12 +3749,12 @@ function formatDiagnostic(diagnostic) {
   return `${location}${diagnostic.code}: ${diagnostic.message}`;
 }
 function within(root, candidate) {
-  const relative = path5.relative(path5.resolve(root), candidate);
-  return relative === "" || !relative.startsWith("..") && !path5.isAbsolute(relative);
+  const relative = path6.relative(path6.resolve(root), candidate);
+  return relative === "" || !relative.startsWith("..") && !path6.isAbsolute(relative);
 }
 async function exists(file) {
   try {
-    await fs4.access(file);
+    await fs5.access(file);
     return true;
   } catch {
     return false;
@@ -2989,6 +3819,10 @@ export {
   validateNodeModuleArchitecture,
   installProjectIo,
   saveStillImages,
+  installProjectStages,
+  cookingNode,
+  RunTrace,
+  captureNodeConsole,
   createProjectHost,
   classifyPreflight,
   validateProjectGraph,
@@ -3003,4 +3837,4 @@ export {
   builtinModuleIds,
   diagnoseGraph
 };
-//# sourceMappingURL=chunk-EUIAC3U3.js.map
+//# sourceMappingURL=chunk-QKL7CCRS.js.map