@field/cascade 0.10.0 → 0.12.0

package/dist/runtime/runtime.js

@@ -1,11 +1,11 @@
-import { bundleFieldType, bundleSchemasCompatible, bundleValueProblem, canConnectTypes, isBundleValue, selectBundleFields, suggestName, unknownFieldMessage, validateNodeDefinition, } from "@field/cascade/contracts";
+import { bundleFieldType, bundleSchemasCompatible, bundleValueProblem, canConnectTypes, Color, isBundleValue, selectBundleFields, suggestName, unknownFieldMessage, validateNodeDefinition, } from "@field/cascade/contracts";
 import { CascadeRuntimeError } from "./error.js";
 import { builtinNodeRegistrations } from "./builtins/index.js";
 import { deserializeChannel, isEmptyChannel } from "./animation/channel.js";
 import { PropAnimator, isBoundProp } from "./params/index.js";
 import { bundleFieldReferences, parseBundleFieldPath, remoteBundlePath, } from "./expressions/bundlePaths.js";
 import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.js";
-import { isGpuHost } from "./gpu.js";
+import { gpuLimitShortfall, isGpuHost } from "./gpu.js";
 import { DEFAULT_GRAPH_SEED, graphSeed, nodeSeed, seededRandom } from "./seed.js";
 /**
  * Preflight codes that describe something other than "this graph cannot run
@@ -113,16 +113,23 @@ class MutableAbortSignal {
     }
 }
 export 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 } : {}),
+    });
 }
+const SERIAL_EXECUTION = { values: "freeze", concurrency: 1 };
 class Runtime {
     host;
+    execution;
     registrations = new Map();
     graphs = new Set();
     sealed = false;
     disposed = false;
-    constructor(host, registrations) {
+    constructor(host, registrations, execution = SERIAL_EXECUTION) {
         this.host = host;
+        this.execution = execution;
         for (const registration of registrations)
             this.registerNode(registration);
     }
@@ -166,7 +173,7 @@ class Runtime {
         const connections = (document.connections ?? []).map((connection, index) => materializeConnection(connection, index, byId));
         validateCardinality(byId, connections);
         validateTopology(nodes, connections);
-        const graph = new Graph(this.host, nodes, connections, () => this.graphs.delete(graph), document.annotations, graphSeed(document));
+        const graph = new Graph(this.host, nodes, connections, () => this.graphs.delete(graph), document.annotations, graphSeed(document), this.execution);
         // The graph's own frame rate, saved with it; a run's `fps` still overrides.
         const fps = document.timeline?.fps;
         if (typeof fps === "number" && Number.isFinite(fps) && fps > 0)
@@ -188,6 +195,7 @@ class Graph {
     connections;
     onDispose;
     seed;
+    execution;
     graphState = "ready";
     byId;
     dataConnectionsByInput;
@@ -213,14 +221,20 @@ class Graph {
     animator;
     frame = MIN_FRAME;
     fps = DEFAULT_FPS;
+    /** What happens to a value a node hands over; see `RuntimeValuePolicy`. */
+    values;
     constructor(host, nodes, connections, onDispose, annotations = [], 
     /** The document's seed; each node's `context.seed` derives from it. */
-    seed = DEFAULT_GRAPH_SEED) {
+    seed = DEFAULT_GRAPH_SEED, 
+    /** Value policy, concurrency, node scope; see `CreateRuntimeOptions`. */
+    execution = SERIAL_EXECUTION) {
         this.host = host;
         this.nodes = nodes;
         this.connections = connections;
         this.onDispose = onDispose;
         this.seed = seed;
+        this.execution = execution;
+        this.values = execution.values;
         this.byId = new Map(nodes.map((node) => [node.id, node]));
         const byInput = new Map();
         const byNode = new Map();
@@ -316,7 +330,7 @@ class Graph {
                     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)) }
+                        ? { value: this.expose(node.outputs.get(name)) }
                         : {}),
                 },
             ])),
@@ -479,7 +493,15 @@ class Graph {
         return () => this.listeners.delete(listener);
     }
     getOutput(nodeId, outputName) {
-        return snapshot(this.requireNode(nodeId).outputs.get(outputName));
+        return this.expose(this.requireNode(nodeId).outputs.get(outputName));
+    }
+    /**
+     * 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);
@@ -490,7 +512,7 @@ class Graph {
     getOutputs(nodeId) {
         return immutableMap([...this.requireNode(nodeId).outputs].map(([name, value]) => [
             name,
-            snapshot(value),
+            this.expose(value),
         ]));
     }
     dispose() {
@@ -578,19 +600,23 @@ class Graph {
             const ordered = topological(this.nodes, this.connections).filter((node) => initial.includes(node) && !insideFeedback.has(node.id));
             /** Nodes that cooked in this run, for `reuse: "strict"`. */
             const cooked = 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",
@@ -628,7 +654,90 @@ class Graph {
             this.active = undefined;
         }
     }
+    /**
+     * 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 = 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 = new Set();
+        const running = 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 });
         /**
          * `cascade.core.Previous` reads the carried state off its container, the
@@ -710,7 +819,7 @@ class Graph {
                     const definition = node.definition.outputs?.[name];
                     if (!definition || definition.kind !== "data")
                         continue;
-                    const value = outputValue(response.outputs[name], definition, `${node.id}.${name}`);
+                    const value = outputValue(response.outputs[name], definition, `${node.id}.${name}`, this.values);
                     node.outputs.set(name, value);
                     this.emit({
                         type: "node:output",
@@ -739,7 +848,7 @@ class Graph {
                     }),
                 }
                 : {
-                    set: (value) => pendingData.set(name, outputValue(value, definition, `${node.id}.${name}`)),
+                    set: (value) => pendingData.set(name, outputValue(value, definition, `${node.id}.${name}`, this.values)),
                 },
         ]));
         const capabilityEntries = [];
@@ -747,7 +856,11 @@ class Graph {
             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([
@@ -801,12 +914,14 @@ class Graph {
             if (pendingData.has(name)) {
                 const value = pendingData.get(name);
                 node.outputs.set(name, value);
+                // The stored value is already frozen (or trusted), so the event
+                // carries it as is rather than a fresh copy nobody may read.
                 this.emit({
                     type: "node:output",
                     runId,
                     nodeId: node.id,
                     outputName: name,
-                    value: snapshot(value),
+                    value: this.expose(value),
                 });
             }
         for (const emitted of pendingTriggers)
@@ -1262,7 +1377,8 @@ class Graph {
             }
             return Object.freeze({
                 result: carried,
-                history: Object.freeze(history),
+                // Recorded as settled, so reading `history` back is not a copy.
+                history: settle(history),
             });
         }
         finally {
@@ -1406,7 +1522,10 @@ function materialize(authored, registration) {
         const object = saved && typeof saved === "object" && "value" in saved
             ? saved
             : null;
-        const value = runtimeValue(object ? object.value : saved, definition.type, false, `${authored.id}.${name}`);
+        const stored = object ? object.value : saved;
+        const value = runtimeValue(
+        // 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}`);
         props[name] = value;
         // A stored plain value is an author's decision and beats the declared
         // default expression, so any binding seeded above has to go.
@@ -1702,6 +1821,18 @@ function snapshotRegistration(registration) {
     const definition = snapshot(registration.definition);
     return Object.freeze({ ...registration, definition });
 }
+/** A node `cookConcurrently` never overlaps with another; see there. */
+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");
 }
@@ -1882,7 +2013,103 @@ function misuse(code, message) {
     throw runtimeError(code, message);
 }
 function snapshot(value) {
-    return cloneValue(value, new WeakSet());
+    const clone = cloneValue(value, new WeakSet());
+    if (clone !== null && typeof clone === "object")
+        settled.add(clone);
+    return clone;
+}
+/**
+ * Plain arrays and objects already checked and deep-frozen — by `cloneValue`
+ * or `settle` — so a second snapshot of the same value is a lookup, not a
+ * copy. A runtime value is read far more often than it is made: the producer
+ * sets it once, then the event, `getOutputs`, `finish` and `inspect` each
+ * used to clone it again (a 1M-point array four times a frame).
+ *
+ * Only roots and containers of objects are recorded; a leaf of primitives
+ * (a `[x, y]` point) is cheaper to re-walk than to record a million times.
+ */
+const settled = new WeakSet();
+/** Plain containers copied by `cloneValue`, for the copy-count tests. */
+let copiedContainers = 0;
+/** How many plain arrays/objects the runtime has copied in this process. */
+export function runtimeValueCopies() {
+    return copiedContainers;
+}
+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}`);
+}
+/**
+ * Check a value a node handed over and deep-freeze it where it stands: the
+ * same rules as `cloneValue` (finite numbers, no functions, no cycles, class
+ * instances and typed arrays passed through untouched), without allocating.
+ * The producer gave it away with `set()`; freezing is what keeps the
+ * consumers' view of it from changing under them.
+ */
+function settle(value) {
+    if (value === null || typeof value !== "object") {
+        checkScalar(value);
+        return value;
+    }
+    if (!settled.has(value) && isPlainContainer(value)) {
+        settleContainer(value, new WeakSet());
+        settled.add(value);
+    }
+    return value;
+}
+/** Returns whether `value` held any plain container (and so was recorded). */
+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;
+}
+/**
+ * `"trust"`: the top level is checked by `runtimeValue`'s type test and
+ * frozen shallowly, so `push` or `sort` on a handed-over array still throws;
+ * nested contents are not walked.
+ */
+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);
@@ -1902,22 +2129,15 @@ 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 === undefined || value === null || typeof value !== "object")
         return value;
-    const prototype = Object.getPrototypeOf(value);
-    if (!Array.isArray(value) &&
-        prototype !== Object.prototype &&
-        prototype !== null)
+    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]) => [
@@ -1943,17 +2163,19 @@ const TUPLE_LENGTHS = {
  * An output value, checked against its declaration. A bundle with declared
  * fields may only set those, and each one must be a valid value of its type.
  */
-function outputValue(value, definition, path) {
+function outputValue(value, definition, path, policy) {
+    // Handed over by the producer, so adopted (frozen where it stands), not copied.
+    const adopt = policy === "trust" ? trust : settle;
     if (definition.type !== "bundle" || !definition.fields)
-        return runtimeValue(value, definition.type, false, path);
+        return runtimeValue(value, definition.type, false, path, adopt);
     const fields = definition.fields;
     const problem = bundleValueProblem(value, fields);
     if (problem)
         misuse("runtime/value-type", `${path} ${problem}`);
     if (isBundleValue(value))
         for (const [field, item] of Object.entries(value))
-            runtimeValue(item, bundleFieldType(fields[field]), true, `${path}.${field}`);
-    return runtimeValue(value, "bundle", false, path);
+            runtimeValue(item, bundleFieldType(fields[field]), true, `${path}.${field}`, (checked) => checked);
+    return runtimeValue(value, "bundle", false, path, adopt);
 }
 /** Every path an expression names through ch/chs/chv. */
 function expressionPaths(expression) {
@@ -1975,7 +2197,9 @@ function readsBundleFields(node) {
             }
     return false;
 }
-function runtimeValue(value, type, allowUndefined, path) {
+function runtimeValue(value, type, allowUndefined, path, 
+/** How a checked value is kept: copied (a caller's value) by default. */
+keep = snapshot) {
     if (value === undefined) {
         if (allowUndefined)
             return undefined;
@@ -2001,7 +2225,7 @@ function runtimeValue(value, type, allowUndefined, path) {
             type !== "string");
     if (!valid)
         misuse("runtime/value-type", `${path} is not a valid ${type}`);
-    return snapshot(value);
+    return keep(value);
 }
 function sameValues(a, b, equal) {
     return a.length === b.length && a.every((value, index) => equal(value, b[index]));

package/dist/runtime/types.d.ts

@@ -216,9 +216,39 @@ export type RuntimeEvent = {
     readonly type: "run:complete";
     readonly result: RunResult;
 };
+/**
+ * What the runtime does with a value a node hands to `outputs.x.set()`.
+ *
+ * - `"freeze"` (default): checked and deep-frozen in place, never copied. A
+ *   node that mutates its output after handing it over, or mutates an input,
+ *   throws instead of corrupting another node's view.
+ * - `"trust"`: checked at the top level only and shallow-frozen; nested
+ *   contents are the producer's word. For headless runs (`cascade run`), where
+ *   a 1M-point array walked every frame was most of the frame.
+ *
+ * Either way nothing is cloned on the way through: reading an output back
+ * (`getOutputs`, `inspect`, `node:output`) hands out the same frozen value.
+ */
+export type RuntimeValuePolicy = "freeze" | "trust";
 export interface CreateRuntimeOptions {
     readonly host: RuntimeHost;
     readonly nodes?: readonly NodeRegistration[];
+    /** See `RuntimeValuePolicy`. Default `"freeze"`. */
+    readonly values?: RuntimeValuePolicy;
+    /**
+     * How many nodes one run may cook at once (default 1: one after another).
+     * Nodes still START in topological order, a node only once everything it
+     * reads has completed, so the `node:start` sequence and the outputs are the
+     * same as a serial run; only completions interleave. Feedback containers,
+     * trigger-wired and GPU nodes always cook alone.
+     */
+    readonly concurrency?: number;
+    /**
+     * Wraps each node's execute. A Node host uses it to carry the node id
+     * through the cook's async work (AsyncLocalStorage), so a stage call or a
+     * log line is attributed to its node when several cook at once.
+     */
+    readonly nodeScope?: <T>(nodeId: string, run: () => T) => T;
 }
 export interface CascadeRuntime {
     registerNode(registration: NodeRegistration): void;

package/dist/stage.js

@@ -53,7 +53,10 @@ async function overHttp(stage, args, signal) {
   const postStage = async () => fetch("/api/exec", {
     method: "POST",
     headers: { "Content-Type": "application/json", "X-Cascade-Exec-Capability": await capability() },
-    body: JSON.stringify({ stage, args }),
+    // `cook`: a node's cook is a pure function of its inputs, so the server's
+    // default stage cache may serve it (see StageCachePolicy). A panel posts
+    // through its own api.runStage, without this, and is never cached unasked.
+    body: JSON.stringify({ stage, args, caller: "cook" }),
     signal
   });
   let response;