@field/cascade 0.3.1 → 0.5.1

package/dist/runtime/runtime.js

@@ -4,6 +4,7 @@ import { builtinNodeRegistrations } from "./builtins/index.js";
 import { deserializeChannel, isEmptyChannel } from "./animation/channel.js";
 import { PropAnimator, isBoundProp } from "./params/index.js";
 import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.js";
+import { isGpuHost } from "./gpu.js";
 /**
  * Preflight codes that describe something other than "this graph cannot run
  * here", so `run` proceeds and a checker reports them as warnings.
@@ -48,6 +49,7 @@ import { DEFAULT_FPS, MIN_FRAME } from "./expressions/time.js";
 export const PREFLIGHT_WARNING_CODES = new Set([
     "runtime/preflight-environment",
     "runtime/stray-params",
+    "runtime/unknown-props",
 ]);
 /**
  * The only preflight code that does not stop a run.
@@ -60,6 +62,7 @@ export const PREFLIGHT_WARNING_CODES = new Set([
  */
 const RUN_TOLERATED_CODES = new Set([
     "runtime/stray-params",
+    "runtime/unknown-props",
 ]);
 class MutableAbortSignal {
     report;
@@ -553,7 +556,15 @@ class Graph {
                 queue.push({ nodeId, inputName, event });
                 this.emit({ type: "trigger:queued", runId, nodeId, inputName, event });
             };
-            const ordered = topological(this.nodes, this.connections).filter((node) => initial.includes(node));
+            /**
+             * Feedback descendants are removed from the main order: their container
+             * runs them, once per step. Leaving them here would cook each of them a
+             * second time, out of the loop and with whatever state the last step
+             * happened to leave behind — which reads as a simulation that is one step
+             * wrong rather than as a scheduling bug.
+             */
+            const insideFeedback = this.feedbackDescendants();
+            const ordered = topological(this.nodes, this.connections).filter((node) => initial.includes(node) && !insideFeedback.has(node.id));
             for (const node of ordered) {
                 if (signal.aborted)
                     break;
@@ -598,6 +609,24 @@ class Graph {
     }
     async executeNode(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
+         * same way `cascade.core.Input` reads the parent's wired input: a boundary's
+         * value comes from the parent's evaluation, not from a wire of its own.
+         *
+         * Outside a container it falls through to its own `initial`, which is what
+         * makes a node dragged out of a loop explicable rather than an error.
+         */
+        if (node.moduleId === "cascade.core.Previous") {
+            const container = this.enclosingFeedback(node);
+            const state = container ? this.feedbackState.get(container) : undefined;
+            if (state) {
+                node.outputs.set("value", state.value);
+                node.outputs.set("step", state.step);
+                this.emit({ type: "node:complete", runId, nodeId: node.id });
+                return;
+            }
+        }
         const inputs = Object.fromEntries(Object.entries(node.definition.inputs ?? {}).map(([name, definition]) => {
             if (definition.kind === "trigger")
                 return [name, triggers[name]];
@@ -683,12 +712,23 @@ class Graph {
                     set: (value) => pendingData.set(name, runtimeValue(value, definition.type, false, `${node.id}.${name}`)),
                 },
         ]));
-        const capabilities = Object.freeze(Object.fromEntries((node.definition.capabilities ?? []).map((name) => [
-            name,
-            name === "shell"
-                ? bindShellToRun(this.host.capabilities.shell, signal)
-                : this.host.capabilities[name],
-        ])));
+        const capabilityEntries = [];
+        for (const name of node.definition.capabilities ?? []) {
+            const installed = this.host.capabilities[name];
+            if (name === "gpu" && isGpuHost(installed)) {
+                await installed.ensure();
+                capabilityEntries.push([name, installed.forNode(node.id)]);
+            }
+            else {
+                capabilityEntries.push([
+                    name,
+                    name === "shell"
+                        ? bindShellToRun(this.host.capabilities.shell, signal)
+                        : installed,
+                ]);
+            }
+        }
+        const capabilities = Object.freeze(Object.fromEntries(capabilityEntries));
         const props = Object.freeze({ ...node.props });
         const progress = {
             report: (event) => this.emit({ type: "node:progress", runId, nodeId: node.id, ...event }),
@@ -704,6 +744,15 @@ class Graph {
         });
         if (signal.aborted)
             return;
+        if (node.definition.container === "feedback") {
+            // Resolved here rather than in the node's own execute, because the loop
+            // needs the graph and a definition-v1 node is given only its own id.
+            const feedback = await this.runFeedback(node, runId, signal, enqueue);
+            if (signal.aborted)
+                return;
+            pendingData.set("result", feedback.result);
+            pendingData.set("history", feedback.history);
+        }
         if (node.moduleId === "cascade.core.Subnet") {
             for (const child of this.nodes) {
                 if (child.parent !== node.id ||
@@ -751,6 +800,8 @@ class Graph {
         const diagnostics = [];
         const push = (code, nodeId, message) => diagnostics.push({ phase: "preflight", code, path: nodeId, message });
         for (const node of nodes) {
+            if (node.unknownProps.length)
+                push("runtime/unknown-props", node.id, `${node.moduleId} stores ${node.unknownProps.join(", ")} under "props", and its definition declares no such prop — ${node.unknownProps.length === 1 ? "that value was" : "those values were"} dropped on load. A prop renamed or removed leaves its value behind; a name that never existed is a typo`);
             if (node.strayParams.length)
                 push("runtime/stray-params", node.id, `${node.moduleId} stores ${node.strayParams.join(", ")} under "params", which this runtime does not read — move ${node.strayParams.length === 1 ? "it" : "them"} to "props" or "inputs", whichever the definition declares, or the ${node.strayParams.length === 1 ? "value is" : "values are"} silently the default`);
             const remote = this.isRemote(node);
@@ -942,6 +993,128 @@ class Graph {
     isDisposed() {
         return this.graphState === "disposed";
     }
+    /**
+     * The state a feedback container is carrying, while it is running.
+     *
+     * Runtime state on the instance rather than on the node, because it is alive
+     * only during one container's loop and a node's `outputs` map is the graph's
+     * result — putting a half-finished step in there would make a partially
+     * simulated value readable by anything that inspects outputs mid-run.
+     *
+     * Keyed by container id so nested feedback works: an outer loop's carried
+     * state survives an inner loop running to completion inside one of its steps.
+     */
+    feedbackState = new Map();
+    /**
+     * Every node under a feedback container, transitively.
+     *
+     * These are excluded from the main cook order — the container runs them, once
+     * per step. Computed once per run rather than per step: the hierarchy cannot
+     * change mid-run, and this is walked for every node in the order.
+     */
+    feedbackDescendants() {
+        const containers = new Set(this.nodes
+            .filter((node) => node.definition.container === "feedback")
+            .map((node) => node.id));
+        if (!containers.size)
+            return new Set();
+        const inside = new Set();
+        for (const node of this.nodes) {
+            let parent = node.parent;
+            const seen = new Set();
+            while (parent && !seen.has(parent)) {
+                seen.add(parent);
+                if (containers.has(parent)) {
+                    inside.add(node.id);
+                    break;
+                }
+                parent = this.byId.get(parent)?.parent;
+            }
+        }
+        return inside;
+    }
+    /**
+     * Run a feedback container's contents `steps` times and return the last
+     * result.
+     *
+     * The order the children run in is the graph's own topological order
+     * restricted to this container's descendants, which is what makes the forces
+     * inside behave like nodes rather than like a list: wiring one into another
+     * changes the order they apply in.
+     */
+    async runFeedback(node, runId, signal, enqueue) {
+        const initial = this.dataInputValue(node, "initial");
+        const requested = this.dataInputValue(node, "steps");
+        const steps = Math.max(0, Math.trunc(Number(requested ?? 0)));
+        if (!Number.isFinite(steps))
+            throw runtimeError("runtime/feedback-steps", `${node.id}.steps is not a finite number`);
+        const children = topological(this.nodes, this.connections).filter((child) => this.enclosingFeedback(child) === node.id);
+        // The step's result comes from the Output boundary at index 0, the same
+        // convention a subnet uses. Resolved before the loop so that a container
+        // with no Output fails immediately rather than after simulating everything
+        // and finding nothing to return.
+        const sink = children.find((child) => child.parent === node.id &&
+            child.moduleId === "cascade.core.Output" &&
+            integerProp(child.props.outputIndex) === 0);
+        if (steps > 0 && !sink)
+            throw runtimeError("runtime/feedback-no-output", `${node.id} has no cascade.core.Output inside it, so a step has no result to carry. Add one and wire the step's result into it.`);
+        /**
+         * How many step results to keep for the `history` output.
+         *
+         * Zero by default and read once, before the loop: a simulation that
+         * quietly held every frame of its own geometry would be the difference
+         * between a preview and a tab that runs out of memory, so keeping history
+         * is something a graph asks for and bounds.
+         */
+        const keep = Math.max(0, integerProp(node.props.history));
+        const history = [];
+        // Zero steps is the initial state, not a failure: frame zero of a
+        // simulation is where it starts, and a graph that throws at the beginning
+        // of the timeline is unusable.
+        let carried = initial;
+        try {
+            for (let step = 0; step < steps; step += 1) {
+                if (signal.aborted)
+                    break;
+                this.feedbackState.set(node.id, { value: carried, step });
+                for (const child of children) {
+                    if (signal.aborted)
+                        break;
+                    await this.executeNode(child, runId, signal, {}, enqueue);
+                }
+                if (signal.aborted)
+                    break;
+                carried = sink.outputs.get("output");
+                if (keep > 0) {
+                    history.push(carried);
+                    // Trimmed inside the loop rather than after it, so the peak memory is
+                    // the cap and not the step count.
+                    if (history.length > keep)
+                        history.shift();
+                }
+            }
+            return Object.freeze({
+                result: carried,
+                history: Object.freeze(history),
+            });
+        }
+        finally {
+            this.feedbackState.delete(node.id);
+        }
+    }
+    /** The nearest ancestor that is a feedback container, or undefined. */
+    enclosingFeedback(node) {
+        let parent = node.parent;
+        const seen = new Set();
+        while (parent && !seen.has(parent)) {
+            seen.add(parent);
+            const candidate = this.byId.get(parent);
+            if (candidate?.definition.container === "feedback")
+                return candidate.id;
+            parent = candidate?.parent;
+        }
+        return undefined;
+    }
     requireNode(id) {
         const node = this.byId.get(id);
         if (!node)
@@ -1022,6 +1195,25 @@ function materialize(authored, registration) {
         }
     for (const [name, definition] of Object.entries(registration.definition.props ?? {}))
         props[name] = runtimeValue(definition.default, definition.type, false, `${authored.id}.${name}`);
+    /**
+     * `props` is a map and `params` was a list, and a migration that changes the
+     * key without changing the shape leaves an array here.
+     *
+     * Fatal, and the reason is what it costs: `Object.entries` of an array gives
+     * keys `"0"`, `"1"`, which match no declared prop, so **every authored value
+     * is dropped and every signal stays green.** Measured on 2026-09-08 —
+     * preflight empty, the prop back at its default, `cascade run` reporting
+     * `completed`. `cloud-plots` rendered a whole picture against no moment and
+     * was reported as working on the strength of an exit code.
+     *
+     * An error rather than a warning, unlike a leftover under `params`: that is a
+     * real state an unconverted sketch is legitimately in and must keep
+     * validating, whereas `props` as an array is never valid — the schema
+     * declares a record — and nothing passes through it on the way to being
+     * right. Same reasoning as `definition/re-exported`.
+     */
+    if (Array.isArray(authored.props))
+        misuse("runtime/props-not-a-map", `Node ${authored.id} stores props as a list. "props" is a map of name to value; "params" was the list. Every value in it is being dropped, silently, and the graph would run on its defaults`);
     const bindings = {};
     // A declared default expression, applied only where the document stored
     // nothing at all for the prop. The loop below then runs over what *was*
@@ -1079,6 +1271,7 @@ function materialize(authored, registration) {
         props,
         bindings,
         strayParams: strayParams(authored, registration),
+        unknownProps: unknownProps(authored, registration),
         outputs: new Map(),
     };
 }
@@ -1103,6 +1296,27 @@ function materialize(authored, registration) {
  * naming nothing is a different fault, and reporting it would make this fire on
  * documents where no value was lost.
  */
+/**
+ * Names stored under `props` that the definition does not declare.
+ *
+ * The mirror of `strayParams`, and the gap that one had: it asks *is anything
+ * still under the old key*, which is blind to *did what arrived under the new
+ * key arrive in the right form*. One is a leftover, the other is a botched
+ * move, and the second is worse because it looks finished.
+ *
+ * A warning rather than an error, because unlike an array container this is a
+ * state a real document reaches honestly: a prop renamed or removed from a
+ * definition leaves its value behind, and the graph runs on the defaults. Same
+ * class as a leftover under `params`, and the same severity for the same
+ * reason — a sketch mid-conversion must keep validating.
+ */
+function unknownProps(authored, registration) {
+    const props = authored.props;
+    if (!props || Array.isArray(props))
+        return [];
+    const declared = registration.definition.props ?? {};
+    return Object.keys(props).filter((name) => !(name in declared));
+}
 function strayParams(authored, registration) {
     const definition = registration.definition;
     const declared = new Set([
@@ -1294,8 +1508,9 @@ function validateHierarchy(nodes, byId) {
         const parent = byId.get(node.parent);
         if (!parent)
             misuse("runtime/parent-not-found", `Node ${node.id} references missing parent ${node.parent}`);
-        if (parent.definition.container !== "subnet")
-            misuse("runtime/parent-not-container", `Node ${node.id} parent ${node.parent} is not a subnet container`);
+        if (parent.definition.container !== "subnet" &&
+            parent.definition.container !== "feedback")
+            misuse("runtime/parent-not-container", `Node ${node.id} parent ${node.parent} is not a container`);
     }
     for (const node of nodes) {
         const visited = new Set([node.id]);
@@ -1425,6 +1640,66 @@ function dataDependencies(nodes, connections) {
             dependencies.set(`${dependency.sourceId}\0${dependency.targetId}`, dependency);
         }
     }
+    /**
+     * Project data dependencies across every Feedback boundary they cross.
+     *
+     * Feedback descendants are removed from the main execution order because
+     * their container runs them. Therefore an outside source wired to a child
+     * must delay every enclosing container, and a child wired to an outside
+     * consumer must make that consumer wait for the container. Nested or sibling
+     * loops need the same projection between their scheduled containers.
+     *
+     * Shared ancestors are excluded: a wire whose endpoints are already inside
+     * the same loop orders the children only. Projecting it onto that shared
+     * container would create a false container-to-itself cycle.
+     */
+    const parents = new Map(nodes.map((node) => [node.id, node.parent]));
+    const feedbackContainers = new Set(nodes
+        .filter((node) => node.definition.container === "feedback")
+        .map((node) => node.id));
+    if (feedbackContainers.size) {
+        const feedbackLineage = (id) => {
+            const lineage = [];
+            const seen = new Set();
+            let current = id;
+            while (current && !seen.has(current)) {
+                seen.add(current);
+                if (feedbackContainers.has(current))
+                    lineage.push(current);
+                current = parents.get(current);
+            }
+            return lineage;
+        };
+        const add = (sourceId, targetId) => {
+            if (sourceId === targetId)
+                return;
+            const dependency = { sourceId, targetId };
+            dependencies.set(`${sourceId}\0${targetId}`, dependency);
+        };
+        for (const connection of connections) {
+            if (connection.kind !== "data")
+                continue;
+            const sourceLineage = feedbackLineage(connection.source.nodeId);
+            const targetLineage = feedbackLineage(connection.target.nodeId);
+            const sourceSet = new Set(sourceLineage);
+            const targetSet = new Set(targetLineage);
+            const crossedFrom = sourceLineage.filter((id) => !targetSet.has(id));
+            const crossedInto = targetLineage.filter((id) => !sourceSet.has(id));
+            if (crossedFrom.length > 0 && crossedInto.length > 0) {
+                for (const sourceId of crossedFrom)
+                    for (const targetId of crossedInto)
+                        add(sourceId, targetId);
+            }
+            else if (crossedFrom.length > 0) {
+                for (const sourceId of crossedFrom)
+                    add(sourceId, connection.target.nodeId);
+            }
+            else {
+                for (const targetId of crossedInto)
+                    add(connection.source.nodeId, targetId);
+            }
+        }
+    }
     return [...dependencies.values()];
 }
 function runtimeError(code, message) {

package/dist/runtime/scene/index.d.ts

@@ -0,0 +1,50 @@
+import type { Scene } from "@field/cascade/contracts";
+import { type Bounds } from "../geometry/primitives.js";
+export type { Bounds };
+/**
+ * Axis-aligned bounds over every geometry in the scene, or `undefined` when
+ * there is nothing in it.
+ *
+ * Always three components, even when every geometry inside is 2D — a 2D
+ * geometry's `P` has a `size` of 2 and `geometryBounds` returns two components
+ * for it, and a viewport doing arithmetic on `min[2]` needs it to be `0` rather
+ * than `undefined`. Padding here rather than at each caller is the whole reason
+ * this function exists instead of callers mapping `geometryBounds`.
+ */
+export declare function sceneBounds(scene: Scene): Bounds | undefined;
+export interface SceneDimensionality {
+    readonly is2d: boolean;
+    /** Why. Shown in the viewport's mode control, so it is never a mystery. */
+    readonly reason: "camera" | "normals" | "depth" | "flat" | "empty";
+}
+/**
+ * Is this scene flat enough to look at as a drawing?
+ *
+ * Marcus, 2026-09-09: *"i want the viewer to detect if our geometry is 2D or 3D
+ * and adapt the viewport accordingly … unless our geometry / camera wants a 3D
+ * view."*
+ *
+ * Three conditions, and every one of them is a **fact about the cooked output**
+ * rather than a guess about intent, which is the property that makes this
+ * safe to act on:
+ *
+ * 1. A wired camera forces 3D whatever the bounds say. That is the *"unless the
+ *    camera wants a 3D view"* clause, and it is also the escape hatch for a
+ *    deliberately flat 3D scene — somebody who wires a camera has said which
+ *    way they are looking at it.
+ * 2. A point `N` attribute forces 3D. Normals only mean something on a surface.
+ * 3. Otherwise, flat iff the Z extent is below a relative epsilon.
+ *
+ * ## This may only ever set the *initial* mode
+ *
+ * A particle simulation can be planar at frame 1 and gain depth by frame 20.
+ * Re-running this on every cook would flip the viewport mid-playback, which is
+ * worse than either mode would have been. So the Viewer calls this **once**,
+ * when a node has no remembered view, and never again — which is why the
+ * per-node view memory is not a separate feature but the thing that makes
+ * detect-once implementable at all. Without somewhere to keep the answer the
+ * only options are re-detecting, which flips, and never detecting, which is
+ * useless.
+ */
+export declare function sceneDimensionality(scene: Scene): SceneDimensionality;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/scene/index.js

@@ -0,0 +1,94 @@
+import { geometryBounds } from "../geometry/primitives.js";
+/**
+ * Axis-aligned bounds over every geometry in the scene, or `undefined` when
+ * there is nothing in it.
+ *
+ * Always three components, even when every geometry inside is 2D — a 2D
+ * geometry's `P` has a `size` of 2 and `geometryBounds` returns two components
+ * for it, and a viewport doing arithmetic on `min[2]` needs it to be `0` rather
+ * than `undefined`. Padding here rather than at each caller is the whole reason
+ * this function exists instead of callers mapping `geometryBounds`.
+ */
+export function sceneBounds(scene) {
+    const min = [
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+        Number.POSITIVE_INFINITY,
+    ];
+    const max = [
+        Number.NEGATIVE_INFINITY,
+        Number.NEGATIVE_INFINITY,
+        Number.NEGATIVE_INFINITY,
+    ];
+    let found = false;
+    for (const geometry of scene.geometry) {
+        const bounds = geometryBounds(geometry);
+        if (bounds === undefined)
+            continue;
+        found = true;
+        for (let axis = 0; axis < 3; axis += 1) {
+            const low = bounds.min[axis] ?? 0;
+            const high = bounds.max[axis] ?? 0;
+            if (low < min[axis])
+                min[axis] = low;
+            if (high > max[axis])
+                max[axis] = high;
+        }
+    }
+    return found ? { min, max } : undefined;
+}
+/**
+ * Relative epsilon for the flatness test.
+ *
+ * Absolute would be wrong in both directions: a scene in millimetres is
+ * legitimately 0.4 deep, and a scene in metres can carry 0.4 of floating-point
+ * noise on a plane that was meant to be flat. So the test is against the scene's
+ * own size.
+ */
+const FLATNESS_EPSILON = 1e-6;
+/**
+ * Is this scene flat enough to look at as a drawing?
+ *
+ * Marcus, 2026-09-09: *"i want the viewer to detect if our geometry is 2D or 3D
+ * and adapt the viewport accordingly … unless our geometry / camera wants a 3D
+ * view."*
+ *
+ * Three conditions, and every one of them is a **fact about the cooked output**
+ * rather than a guess about intent, which is the property that makes this
+ * safe to act on:
+ *
+ * 1. A wired camera forces 3D whatever the bounds say. That is the *"unless the
+ *    camera wants a 3D view"* clause, and it is also the escape hatch for a
+ *    deliberately flat 3D scene — somebody who wires a camera has said which
+ *    way they are looking at it.
+ * 2. A point `N` attribute forces 3D. Normals only mean something on a surface.
+ * 3. Otherwise, flat iff the Z extent is below a relative epsilon.
+ *
+ * ## This may only ever set the *initial* mode
+ *
+ * A particle simulation can be planar at frame 1 and gain depth by frame 20.
+ * Re-running this on every cook would flip the viewport mid-playback, which is
+ * worse than either mode would have been. So the Viewer calls this **once**,
+ * when a node has no remembered view, and never again — which is why the
+ * per-node view memory is not a separate feature but the thing that makes
+ * detect-once implementable at all. Without somewhere to keep the answer the
+ * only options are re-detecting, which flips, and never detecting, which is
+ * useless.
+ */
+export function sceneDimensionality(scene) {
+    if (scene.camera !== null)
+        return { is2d: false, reason: "camera" };
+    for (const geometry of scene.geometry)
+        if (geometry.point.N !== undefined)
+            return { is2d: false, reason: "normals" };
+    const bounds = sceneBounds(scene);
+    if (bounds === undefined)
+        return { is2d: true, reason: "empty" };
+    const depth = (bounds.max[2] ?? 0) - (bounds.min[2] ?? 0);
+    const size = Math.max((bounds.max[0] ?? 0) - (bounds.min[0] ?? 0), (bounds.max[1] ?? 0) - (bounds.min[1] ?? 0), Math.abs(bounds.max[2] ?? 0), Math.abs(bounds.min[2] ?? 0));
+    const tolerance = Math.max(size, 1) * FLATNESS_EPSILON;
+    return depth <= tolerance
+        ? { is2d: true, reason: "flat" }
+        : { is2d: false, reason: "depth" };
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/series/index.d.ts

@@ -0,0 +1,41 @@
+import type { CascadeAbortSignal, CascadePreset, CascadeSeries, SeriesInstanceResult } from "@field/cascade/contracts";
+import type { LoadedCascadeGraph } from "../types.js";
+/**
+ * The graph's current values for those keys, as a preset.
+ *
+ * Read through `inspect()` rather than from the nodes directly, so the values
+ * are the same snapshots every other reader gets. A key the graph does not
+ * have is left out rather than defaulted: `applyPreset` is the thing that
+ * decides an unknown key is a misuse, and it should keep deciding that.
+ */
+export declare function seriesBaseline(graph: LoadedCascadeGraph, series: CascadeSeries): CascadePreset;
+export interface RunSeriesOptions {
+    readonly signal?: CascadeAbortSignal;
+    readonly frame?: number;
+    readonly fps?: number;
+    /**
+     * The instance to cook first, by id.
+     *
+     * *"Making changes to the underlying network re-renders the current selected
+     * item first then the entire series."* The order of the results is always the
+     * series' own order whatever this says — only the order of the **work**
+     * changes, because the caller is watching one instance and waiting for a
+     * list would defeat the point.
+     */
+    readonly first?: string;
+    /** Called as each instance finishes, in cook order rather than list order,
+     *  so a gallery can fill in as results arrive instead of after all of them. */
+    readonly onInstance?: (result: SeriesInstanceResult) => void;
+}
+export interface SeriesRunResult {
+    /** In the series' own order, whatever order the work ran in. */
+    readonly instances: readonly SeriesInstanceResult[];
+    /** By record id, which is the address everything downstream uses. */
+    readonly byId: ReadonlyMap<string, SeriesInstanceResult>;
+    readonly status: "completed" | "cancelled" | "failed";
+}
+/** Ids must be unique, or an instance has no address at all — and every
+ *  judgement, override and cache key in the plan hangs off that address. */
+export declare function validateSeries(series: CascadeSeries): void;
+export declare function runSeries(graph: LoadedCascadeGraph, series: CascadeSeries, options?: RunSeriesOptions): Promise<SeriesRunResult>;
+//# sourceMappingURL=index.d.ts.map