@field/cascade 0.3.0 → 0.3.1

package/dist/cli/index.js

@@ -782,6 +782,20 @@ function validateNodeDefinition(value) {
         );
       if ("step" in raw && (typeof raw.step !== "number" || !Number.isFinite(raw.step) || raw.step <= 0))
         add("invalid-step", "step must be greater than zero", `${path23}.step`);
+      if (section === "props" && "expression" in raw && (typeof raw.expression !== "string" || raw.expression.length === 0))
+        add(
+          "invalid-expression",
+          "expression must be a non-empty string",
+          `${path23}.expression`
+        );
+      for (const field of ["min", "max"]) {
+        if (field in raw && (typeof raw[field] !== "number" || !Number.isFinite(raw[field])))
+          add(
+            `invalid-${field}`,
+            `${field} must be a finite number`,
+            `${path23}.${field}`
+          );
+      }
       if (typeof raw.min === "number" && typeof raw.max === "number" && raw.min > raw.max)
         add("invalid-range", "min must not exceed max", path23);
     }
@@ -801,7 +815,7 @@ var init_validate = __esm({
     CONTROLS = /* @__PURE__ */ new Set(["number", "slider", "range", "int", "boolean", "text", "textarea", "select", "vector", "matrix", "color", "image", "asset"]);
     CAPABILITIES_BY_ENVIRONMENT = {
       portable: ["assets", "media"],
-      browser: ["assets", "media", "webgl"],
+      browser: ["assets", "media", "gpu"],
       server: ["files", "assets", "media", "python", "shell"]
     };
     ALLOWED = CAPABILITIES_BY_ENVIRONMENT;
@@ -814,7 +828,7 @@ var init_validate = __esm({
     );
     OUTPUT_FIELDS = fields("kind type description");
     PROP_FIELDS = fields(
-      "type default label description min max step accept control options"
+      "type default label description min max step accept control options expression"
     );
   }
 });
@@ -5750,6 +5764,17 @@ var Node = class _Node {
     this.portsUsedDuringSetup = /* @__PURE__ */ new Set();
     // Port index map for O(1) lookups (portId -> port)
     this._portMap = /* @__PURE__ */ new Map();
+    // ============ Props System ============
+    /**
+     * Add a parameter to this node
+     * Short alias for defineProp - use in setup()
+     */
+    /** Props whose declared default expression has already been applied — see
+     *  `bindParameterProp`, which must not reinstate one the author deleted. */
+    this.defaultExpressionsApplied = /* @__PURE__ */ new Set();
+    /** Props whose plain stored value explicitly overrides a declared default
+     *  expression. The marker survives even when that value equals the default. */
+    this.plainPropOverrides = /* @__PURE__ */ new Set();
     this.id = id;
     this.type = type;
     this.graph = graph;
@@ -5884,11 +5909,6 @@ var Node = class _Node {
       targetPort.onChange?.(value);
     }
   }
-  // ============ Props System ============
-  /**
-   * Add a parameter to this node
-   * Short alias for defineProp - use in setup()
-   */
   addParm(name, config) {
     this.props[name] = config;
     this.propsDeclaredByCode.add(name);
@@ -5989,6 +6009,9 @@ var Node = class _Node {
       deleteExpression: () => {
         const { expression: _, expressionError: __, ...rest } = self.props[name];
         self.props[name] = rest;
+        if (self.defaultExpressionsApplied.has(name)) {
+          self.plainPropOverrides.add(name);
+        }
         self.updateTimeDependent();
         self.markDirty();
       },
@@ -6068,6 +6091,12 @@ var Node = class _Node {
       ...channel ? { channel } : {}
     };
   }
+  preservePlainProp(name) {
+    this.plainPropOverrides.add(name);
+  }
+  preservesPlainProp(name) {
+    return this.plainPropOverrides.has(name) && this.defaultExpressionsApplied.has(name);
+  }
   /** Read a channel back off disk. Bad data yields no channel, never a throw. */
   restorePropChannel(name, data) {
     if (!this.props[name]) return;
@@ -6215,6 +6244,14 @@ var Node = class _Node {
       this.props[name] = prop;
       this.props = { ...this.props };
     }
+    if (options.defaultExpression && !this.defaultExpressionsApplied.has(name)) {
+      this.defaultExpressionsApplied.add(name);
+      if (!this.plainPropOverrides.has(name) && !prop.expression) {
+        prop.expression = options.defaultExpression;
+        this.props = { ...this.props };
+        this.updateTimeDependent();
+      }
+    }
     prop.fromParameter = name;
     prop.hidden = true;
     const control = paramControlType(parameter.dataType);
@@ -8103,6 +8140,7 @@ var silentProgress = { report: () => {
 function parameterOptions(definition) {
   return {
     ...definition.label ? { label: definition.label } : {},
+    ...definition.expression ? { defaultExpression: definition.expression } : {},
     ...definition.min === void 0 ? {} : { min: definition.min },
     ...definition.max === void 0 ? {} : { max: definition.max },
     ...definition.step === void 0 ? {} : { step: definition.step },
@@ -8112,6 +8150,9 @@ function parameterOptions(definition) {
     promotable: false
   };
 }
+function asGpuHost(value) {
+  return value && typeof value.ensure === "function" && typeof value.forNode === "function" ? value : null;
+}
 function attachDefinition(node, registration, capabilities) {
   const definition = registration.definition;
   const pendingTriggers = /* @__PURE__ */ new Map();
@@ -8186,12 +8227,18 @@ function attachDefinition(node, registration, capabilities) {
       if (!port) throw new Error(`Missing output ${registration.moduleId}.${name}`);
       return [name, output.kind === "trigger" ? { trigger: (payload) => port.trigger(payload) } : { set: (value) => port.setValue(value) }];
     }));
+    let nodeCapabilities = capabilities;
+    const gpuHost = (definition.capabilities ?? []).includes("gpu") ? asGpuHost(capabilities.gpu) : null;
+    if (gpuHost) {
+      await gpuHost.ensure();
+      nodeCapabilities = { ...capabilities, gpu: gpuHost.forNode(node.id) };
+    }
     const context = {
       nodeId: node.id,
       inputs: inputValues,
       outputs,
       props: Object.fromEntries(node.parameters.map((parameter) => [parameter.name, parameter.value])),
-      capabilities,
+      capabilities: nodeCapabilities,
       signal: new AbortController().signal,
       progress: silentProgress
     };
@@ -8230,8 +8277,140 @@ var browserAssetCapability = {
   }
 };
 
+// src/nodes/definition/gpuCapability.ts
+var PAGE_SCOPE = "\0page";
+var MISSING_DEVICE = "The gpu capability was used before its device was ready \u2014 the host must await ensure() before a cook.";
+function createStudioGpuCapability() {
+  const gpu = globalThis.navigator?.gpu;
+  if (!gpu) return void 0;
+  let device = null;
+  let adapterInfo = null;
+  let limits = {};
+  let starting = null;
+  let destroyed = false;
+  const caches = /* @__PURE__ */ new Map();
+  function dropCaches() {
+    for (const entries of caches.values()) {
+      for (const entry of entries.values()) entry.destroy?.(entry.value);
+    }
+    caches.clear();
+  }
+  async function start() {
+    const adapter = await gpu.requestAdapter();
+    if (!adapter) {
+      throw new Error("No WebGPU adapter is available \u2014 the browser reports WebGPU but the system offers no GPU to render on.");
+    }
+    const next = await adapter.requestDevice();
+    const info = adapter.info;
+    device = next;
+    adapterInfo = {
+      vendor: info?.vendor ?? "",
+      architecture: info?.architecture ?? "",
+      device: info?.device ?? "",
+      description: info?.description ?? ""
+    };
+    limits = readLimits(next.limits ?? adapter.limits);
+    void next.lost.then((info2) => {
+      if (destroyed || info2?.reason === "destroyed") return;
+      device = null;
+      starting = null;
+      dropCaches();
+      console.warn(`The GPU device was lost (${info2?.reason ?? "unknown"}) \u2014 ${info2?.message || "no message given"}. A fresh device will be requested on the next cook.`);
+    });
+  }
+  const host = {
+    get device() {
+      if (!device) throw new Error(MISSING_DEVICE);
+      return device;
+    },
+    get adapterInfo() {
+      if (!adapterInfo) throw new Error(MISSING_DEVICE);
+      return adapterInfo;
+    },
+    get limits() {
+      return limits;
+    },
+    cache(key2, create, destroy) {
+      return host.forNode(PAGE_SCOPE).cache(key2, create, destroy);
+    },
+    async ensure() {
+      if (destroyed) throw new Error("The gpu capability has been disposed.");
+      if (device) return;
+      starting ??= start().catch((error) => {
+        starting = null;
+        throw error;
+      });
+      await starting;
+    },
+    forNode(nodeId) {
+      return {
+        get device() {
+          if (!device) throw new Error(MISSING_DEVICE);
+          return device;
+        },
+        get adapterInfo() {
+          if (!adapterInfo) throw new Error(MISSING_DEVICE);
+          return adapterInfo;
+        },
+        get limits() {
+          return limits;
+        },
+        cache(key2, create, destroy) {
+          if (!device) throw new Error(MISSING_DEVICE);
+          let entries = caches.get(nodeId);
+          if (!entries) {
+            entries = /* @__PURE__ */ new Map();
+            caches.set(nodeId, entries);
+          }
+          const existing = entries.get(key2);
+          if (existing) return existing.value;
+          const value = create(device);
+          entries.set(key2, { value, destroy });
+          return value;
+        }
+      };
+    },
+    async dispose() {
+      destroyed = true;
+      dropCaches();
+      device?.destroy();
+      device = null;
+      starting = null;
+    }
+  };
+  return host;
+}
+function readLimits(source) {
+  if (!source || typeof source !== "object") return {};
+  const out = {};
+  for (const key2 of limitNames(source)) {
+    const value = source[key2];
+    if (typeof value === "number") out[key2] = value;
+  }
+  return out;
+}
+function limitNames(source) {
+  const names = new Set(Object.keys(source));
+  for (let cursor = Object.getPrototypeOf(source); cursor && cursor !== Object.prototype; cursor = Object.getPrototypeOf(cursor)) {
+    for (const key2 of Object.getOwnPropertyNames(cursor)) if (key2 !== "constructor") names.add(key2);
+  }
+  return [...names];
+}
+
 // src/nodes/definition/projectDefinition.ts
-var studioCapabilities = { assets: browserAssetCapability };
+var studioCapabilities = {
+  assets: browserAssetCapability,
+  // Installed only where the browser has WebGPU, and absent rather than
+  // stubbed otherwise. That is what makes the failure a sentence: the preflight
+  // reports `runtime/missing-capability` and the adapter throws "requires the
+  // Studio gpu capability", both naming what is missing. A stub that threw on
+  // first use would name nothing.
+  ...gpuCapabilityIfAvailable()
+};
+function gpuCapabilityIfAvailable() {
+  const gpu = createStudioGpuCapability();
+  return gpu ? { gpu } : {};
+}
 function declaresDefinitionV1(value) {
   return typeof value === "object" && value !== null && value.apiVersion === 1;
 }
@@ -9429,7 +9608,9 @@ var Graph = class _Graph {
       result.parent = node.parent.id;
     }
     const rawParameterValue = (p) => node.rawParameterValue(p.name);
-    const changedParameters = (node.parameters ?? []).filter((p) => p.promoted || JSON.stringify(rawParameterValue(p)) !== JSON.stringify(p.defaultValue));
+    const changedParameters = (node.parameters ?? []).filter(
+      (p) => p.promoted || node.preservesPlainProp(p.name) || JSON.stringify(rawParameterValue(p)) !== JSON.stringify(p.defaultValue)
+    );
     const parameters = changedParameters.filter((p) => p.documentField !== "props").map((p) => p.promoted ? { name: p.name, value: rawParameterValue(p), promoted: true } : { name: p.name, value: rawParameterValue(p) });
     if (parameters.length > 0) {
       result.params = parameters;
@@ -9644,6 +9825,12 @@ var Graph = class _Graph {
           }
           if (expression && node.props[key2]) {
             node.props[key2].expression = expression;
+          } else {
+            node.preservePlainProp(key2);
+          }
+          if (!expression && node.props[key2]?.expression) {
+            delete node.props[key2].expression;
+            node.props[key2] = { ...node.props[key2] };
           }
           if (propData?.channel && node.props[key2]) {
             node.restorePropChannel(key2, propData.channel);
@@ -11411,6 +11598,9 @@ var PREFLIGHT_WARNING_CODES = /* @__PURE__ */ new Set([
   "runtime/preflight-environment",
   "runtime/stray-params"
 ]);
+var RUN_TOLERATED_CODES = /* @__PURE__ */ new Set([
+  "runtime/stray-params"
+]);
 var MutableAbortSignal = class {
   constructor(report) {
     this.report = report;
@@ -11559,6 +11749,46 @@ var Graph2 = class {
     this.frame = MIN_FRAME;
     this.fps = DEFAULT_FPS;
     this.byId = new Map(nodes.map((node) => [node.id, node]));
+    const byInput = /* @__PURE__ */ new Map();
+    const byNode = /* @__PURE__ */ new Map();
+    const connectedInputs = /* @__PURE__ */ new Set();
+    const connectedOutputs = /* @__PURE__ */ new Set();
+    for (const connection of connections) {
+      connectedInputs.add(
+        `${connection.target.nodeId}\0${connection.target.inputName}`
+      );
+      connectedOutputs.add(
+        `${connection.source.nodeId}\0${connection.source.outputName}`
+      );
+      if (connection.kind !== "data") continue;
+      const inputKey = `${connection.target.nodeId}\0${connection.target.inputName}`;
+      const inputConnections = byInput.get(inputKey) ?? [];
+      inputConnections.push(connection);
+      byInput.set(inputKey, inputConnections);
+      const nodeConnections = byNode.get(connection.target.nodeId) ?? [];
+      nodeConnections.push(connection);
+      byNode.set(connection.target.nodeId, nodeConnections);
+    }
+    this.dataConnectionsByInput = new Map(
+      [...byInput].map(([key2, inputConnections]) => [
+        key2,
+        Object.freeze(
+          inputConnections.sort(
+            (first, second) => (first.variadicIndex ?? first.order) - (second.variadicIndex ?? second.order)
+          )
+        )
+      ])
+    );
+    this.dataConnectionsByNode = new Map(
+      [...byNode].map(([key2, nodeConnections]) => [
+        key2,
+        Object.freeze(
+          nodeConnections.sort((first, second) => first.order - second.order)
+        )
+      ])
+    );
+    this.connectedInputs = connectedInputs;
+    this.connectedOutputs = connectedOutputs;
     this.graphInputs = graphBoundaries(nodes, "cascade.core.Input", "inputName");
     this.graphOutputs = graphBoundaries(nodes, "cascade.core.Output", "outputName");
     this.authoredAnnotations = Object.freeze(
@@ -11568,9 +11798,7 @@ var Graph2 = class {
       nodes,
       node: (id) => this.byId.get(id),
       inputNode: (node, index) => {
-        const feeding = this.connections.filter(
-          (connection) => connection.kind === "data" && connection.target.nodeId === node.id
-        ).sort((a, b) => a.order - b.order);
+        const feeding = this.dataConnectionsByNode.get(node.id) ?? [];
         const source = feeding[index]?.source.nodeId;
         return (source ? this.byId.get(source) : void 0) ?? null;
       },
@@ -11614,9 +11842,7 @@ var Graph2 = class {
             {
               kind: definition.kind,
               type: definition.kind === "trigger" ? "trigger" : definition.type,
-              connected: this.connections.some(
-                (connection) => connection.target.nodeId === node.id && connection.target.inputName === name
-              ),
+              connected: this.connectedInputs.has(`${node.id}\0${name}`),
               ...definition.kind === "data" ? { value: snapshot(node.inputs[name]) } : {}
             }
           ]
@@ -11629,9 +11855,7 @@ var Graph2 = class {
             {
               kind: definition.kind,
               type: definition.kind === "trigger" ? "trigger" : definition.type,
-              connected: this.connections.some(
-                (connection) => connection.source.nodeId === node.id && connection.source.outputName === name
-              ),
+              connected: this.connectedOutputs.has(`${node.id}\0${name}`),
               ...definition.kind === "data" && node.outputs.has(name) ? { value: snapshot(node.outputs.get(name)) } : {}
             }
           ]
@@ -11981,11 +12205,7 @@ var Graph2 = class {
           const index = integerProp(node.props.inputIndex);
           return [name, this.dataInputValue(parent, `input_${index}`)];
         }
-        const connections = this.connections.filter(
-          (item) => item.kind === "data" && item.target.nodeId === node.id && item.target.inputName === name
-        ).sort(
-          (first, second) => (first.variadicIndex ?? first.order) - (second.variadicIndex ?? second.order)
-        );
+        const connections = this.dataConnectionsByInput.get(`${node.id}\0${name}`) ?? [];
         if (definition.variadic) {
           const values = connections.map(
             (connection2) => this.requireNode(connection2.source.nodeId).outputs.get(
@@ -12215,7 +12435,7 @@ var Graph2 = class {
   }
   assertPreflight(nodes) {
     const [first] = this.preflightDiagnostics(nodes).filter(
-      (diagnostic2) => !PREFLIGHT_WARNING_CODES.has(diagnostic2.code)
+      (diagnostic2) => !RUN_TOLERATED_CODES.has(diagnostic2.code)
     );
     if (first) throw new CascadeRuntimeError(first.code, [first]);
   }
@@ -12229,8 +12449,9 @@ var Graph2 = class {
   }
   runSelection(target) {
     if (target.kind === "all") {
+      const gatedDataDescendants = this.gatedDataDescendants();
       const initial = this.nodes.filter(
-        (node) => !isGated(node) && !this.hasGatedDataAncestor(node.id)
+        (node) => !isGated(node) && !gatedDataDescendants.has(node.id)
       );
       const ids = new Set(initial.map((node) => node.id));
       let changed = true;
@@ -12278,8 +12499,24 @@ var Graph2 = class {
     }
     return this.nodes.filter((node) => ids.has(node.id));
   }
-  hasGatedDataAncestor(nodeId) {
-    return this.dataClosure(nodeId).some(isGated);
+  gatedDataDescendants() {
+    const outgoing = /* @__PURE__ */ new Map();
+    for (const dependency of dataDependencies(this.nodes, this.connections)) {
+      const targets = outgoing.get(dependency.sourceId) ?? [];
+      targets.push(dependency.targetId);
+      outgoing.set(dependency.sourceId, targets);
+    }
+    const queue = this.nodes.filter(isGated).map((node) => node.id);
+    const descendants = new Set(queue);
+    let queueIndex = 0;
+    while (queueIndex < queue.length) {
+      for (const targetId of outgoing.get(queue[queueIndex++]) ?? []) {
+        if (descendants.has(targetId)) continue;
+        descendants.add(targetId);
+        queue.push(targetId);
+      }
+    }
+    return descendants;
   }
   triggerDataAncestors(nodeId) {
     const dependencies = this.dataClosure(nodeId).filter(
@@ -12455,7 +12692,17 @@ function materialize(authored, registration) {
       `${authored.id}.${name}`
     );
   const bindings = {};
-  for (const [name, saved] of Object.entries(authored.props ?? {})) {
+  const storedProps = authored.props ?? {};
+  for (const [name, definition] of Object.entries(
+    registration.definition.props ?? {}
+  )) {
+    if (!definition.expression || name in storedProps) continue;
+    bindings[name] = {
+      value: props[name],
+      expression: definition.expression
+    };
+  }
+  for (const [name, saved] of Object.entries(storedProps)) {
     const definition = registration.definition.props?.[name];
     if (!definition) continue;
     const object = saved && typeof saved === "object" && "value" in saved ? saved : null;
@@ -12466,7 +12713,10 @@ function materialize(authored, registration) {
       `${authored.id}.${name}`
     );
     props[name] = value;
-    if (!object) continue;
+    if (!object) {
+      delete bindings[name];
+      continue;
+    }
     const channel = deserializeChannel(object.channel);
     const expression = typeof object.expression === "string" && object.expression ? object.expression : void 0;
     const binding = {
@@ -12727,6 +12977,7 @@ function validateTopology(nodes, connections) {
   topological(nodes, connections);
 }
 function topological(nodes, connections) {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
   const indegree = new Map(nodes.map((node) => [node.id, 0]));
   const outgoing = new Map(nodes.map((node) => [node.id, []]));
   for (const dependency of graphDependencies(nodes, connections)) {
@@ -12738,13 +12989,14 @@ function topological(nodes, connections) {
   }
   const queue = nodes.filter((node) => indegree.get(node.id) === 0);
   const result = [];
-  while (queue.length) {
-    const node = queue.shift();
+  let queueIndex = 0;
+  while (queueIndex < queue.length) {
+    const node = queue[queueIndex++];
     result.push(node);
     for (const id of outgoing.get(node.id)) {
       indegree.set(id, indegree.get(id) - 1);
       if (indegree.get(id) === 0)
-        queue.push(nodes.find((candidate) => candidate.id === id));
+        queue.push(byId.get(id));
     }
   }
   if (result.length !== nodes.length)
@@ -13163,6 +13415,15 @@ async function preflightAgainstRunHost(file, registrations, document2) {
   }
   if (!diagnostics.length) return;
   const { errors, warnings } = classifyPreflight(diagnostics);
+  reportPreflightWarnings(host, warnings);
+  if (!errors.length) return;
+  throw new Error([
+    `This graph cannot run on the ${host.environment} host that "cascade run" uses:`,
+    ...errors.map(line),
+    ...capabilityAdvice(host, errors)
+  ].join("\n"));
+}
+function reportPreflightWarnings(host, warnings) {
   const elsewhere = warnings.filter((item) => item.code === "runtime/preflight-environment");
   const lossy = warnings.filter((item) => item.code === "runtime/stray-params");
   if (elsewhere.length) {
@@ -13179,12 +13440,6 @@ async function preflightAgainstRunHost(file, registrations, document2) {
       `  This graph will run, on the defaults, and look like it worked.`
     ].join("\n"));
   }
-  if (!errors.length) return;
-  throw new Error([
-    `This graph cannot run on the ${host.environment} host that "cascade run" uses:`,
-    ...errors.map(line),
-    ...capabilityAdvice(host, errors)
-  ].join("\n"));
 }
 function line(item) {
   return `  ${item.code}${item.path ? ` [${item.path}]` : ""}: ${item.message}`;
@@ -13242,21 +13497,31 @@ async function runDeterministicProjectGraph(file, document2, entryNode) {
   if (deterministicCount !== nodes.length) {
     throw new Error("Mixed deterministic and dynamic graphs are not executable until the bounded legacy adapter is implemented");
   }
+  const host = createProjectHost(file, prepared.registrations);
   const runtime = createRuntime({
-    host: createProjectHost(file, prepared.registrations),
+    host,
     nodes: prepared.registrations
   });
-  const graph = await runtime.load(document2);
-  const result = await graph.run(entryNode ? { target: { kind: "node", nodeId: entryNode } } : {});
-  await graph.dispose();
-  await runtime.dispose();
-  if (result.status !== "completed") {
-    throw new Error(result.diagnostics.map((item) => item.message).join("\n") || `Graph ${result.status}`);
+  let graph;
+  try {
+    graph = await runtime.load(document2);
+    reportPreflightWarnings(
+      host,
+      classifyPreflight(graph.preflight()).warnings.filter((item) => item.code === "runtime/stray-params")
+    );
+    const result = await graph.run(entryNode ? { target: { kind: "node", nodeId: entryNode } } : {});
+    if (result.status !== "completed") {
+      throw new Error(result.diagnostics.map((item) => item.message).join("\n") || `Graph ${result.status}`);
+    }
+    return true;
+  } finally {
+    await graph?.dispose();
+    await runtime.dispose();
   }
-  return true;
 }
 async function renderDeterministicProjectFrames(file, document2, options) {
   const prepared = await prepare(file, document2, true);
+  reportUnresolved(prepared);
   const nodes = Array.isArray(document2?.nodes) ? document2.nodes : [];
   const deterministicCount = nodes.filter((node) => prepared.deterministic.has(moduleId(node))).length;
   if (!nodes.length || deterministicCount === 0) return null;
@@ -13264,11 +13529,13 @@ async function renderDeterministicProjectFrames(file, document2, options) {
     throw new Error("Mixed deterministic and dynamic graphs are not executable until the bounded legacy adapter is implemented");
   }
   const project = new ProjectRoot(path9.dirname(path9.resolve(file)));
+  const host = createProjectHost(file, prepared.registrations);
   const runtime = createRuntime({
-    host: createProjectHost(file, prepared.registrations),
+    host,
     nodes: prepared.registrations
   });
   const graph = await runtime.load(document2);
+  reportPreflightWarnings(host, classifyPreflight(graph.preflight()).warnings);
   const outDirectory = project.resolve(options.out);
   await fs7.mkdir(outDirectory, { recursive: true });
   const width = sequenceWidth(options.end);
@@ -13328,6 +13595,7 @@ function imageOutputs(graph, entryNode) {
 }
 async function inspectProjectGraph(file, document2) {
   const prepared = await prepare(file, document2, false);
+  reportUnresolved(prepared);
   const registrations = new Map(
     [...builtinNodeRegistrations, ...prepared.registrations].map((item) => [item.moduleId, item])
   );
@@ -13422,7 +13690,7 @@ function unresolvedModule(id, node, tried, root) {
     phase: "prepare",
     code: "project/module-not-found",
     path: node.id,
-    message: `${id} has no module file \u2014 ${where}. Loading the ports the document saved instead, which cannot run: a typo and an unconverted legacy node look identical from here`
+    message: `${id} has no module file \u2014 ${where}. Only known legacy modules can use saved-port compatibility, for inspection only; unknown and explicit project modules are rejected`
   };
 }
 async function compileExecute(projectRoot, moduleFile) {

package/dist/cli/runtime/gpu.ts

@@ -0,0 +1,76 @@
+/**
+ * `cascade/gpu` — WebGPU's flag namespaces as plain values.
+ *
+ * Small, and it was load-bearing. TypeScript's DOM library declares the WebGPU
+ * *interfaces* but not the constant objects, so the only way to reach
+ * `GPUTextureUsage.RENDER_ATTACHMENT` was off `globalThis` — which
+ * `architecture/ambient-state` correctly forbids inside a node module, because
+ * an ambient read makes a node's inputs invisible to the static reader that
+ * lets `cascade check` say anything without cooking.
+ *
+ * So a sketch had to choose between a rule and a working shader, and it chose
+ * a project library file to hide the read in. Both stay honest now: the rule
+ * keeps its teeth and a node imports these instead. That is the whole reason
+ * this file exists, and it is why it had to land with the capability rather
+ * than after it — a rule whose only workaround is removed at the same moment
+ * is a rule; one enforced a release earlier is a nuisance.
+ *
+ * The values are fixed by the WebGPU specification, not by an implementation,
+ * which is what makes writing them down safe rather than a guess. They are
+ * checked against a real browser's own globals in `tests/gpu-usage-flags.test.ts`
+ * — the numbers below were verified against Chrome rather than recalled.
+ */
+
+/** `GPUBufferUsage`. */
+export const BufferUsage = {
+  MAP_READ: 0x0001,
+  MAP_WRITE: 0x0002,
+  COPY_SRC: 0x0004,
+  COPY_DST: 0x0008,
+  INDEX: 0x0010,
+  VERTEX: 0x0020,
+  UNIFORM: 0x0040,
+  STORAGE: 0x0080,
+  INDIRECT: 0x0100,
+  QUERY_RESOLVE: 0x0200,
+} as const;
+
+/** `GPUTextureUsage`. */
+export const TextureUsage = {
+  COPY_SRC: 0x01,
+  COPY_DST: 0x02,
+  TEXTURE_BINDING: 0x04,
+  STORAGE_BINDING: 0x08,
+  RENDER_ATTACHMENT: 0x10,
+  /**
+   * Chrome 147 has this and it is newer than the rest — verified present
+   * 2026-09-08 alongside the others, but do not assume every implementation
+   * carries it. Included rather than omitted deliberately: leaving it out
+   * would send a node that wants it back to `globalThis`, which is the exact
+   * ambient read this file exists to remove, so an honest constant with a
+   * caveat beats an omission that forces a rule violation.
+   */
+  TRANSIENT_ATTACHMENT: 0x20,
+} as const;
+
+/** `GPUShaderStage`, for a bind group layout entry's `visibility`. */
+export const ShaderStage = {
+  VERTEX: 0x1,
+  FRAGMENT: 0x2,
+  COMPUTE: 0x4,
+} as const;
+
+/** `GPUMapMode`, for `buffer.mapAsync`. */
+export const MapMode = {
+  READ: 0x1,
+  WRITE: 0x2,
+} as const;
+
+/** `GPUColorWrite`, for a colour target's `writeMask`. */
+export const ColorWrite = {
+  RED: 0x1,
+  GREEN: 0x2,
+  BLUE: 0x4,
+  ALPHA: 0x8,
+  ALL: 0xf,
+} as const;