@nodetool-ai/node-sdk 0.7.0-rc.23 → 0.8.1

package/dist/graph-validation.js

@@ -0,0 +1,1165 @@
+/**
+ * Static workflow-graph validation.
+ *
+ * Checks a graph against the node registry WITHOUT executing it: unknown node
+ * types, duplicate ids, missing required / unselected-model properties, dangling
+ * edges, unknown edge handles, mis-spelled dynamic slot types, Code node bodies
+ * (syntax, inputs, outputs), and (best-effort) edge type mismatches. Catches the
+ * breakage that would otherwise only surface after a full workflow run.
+ *
+ * Takes a {@link GraphValidationRegistry} (the slice of NodeRegistry it needs)
+ * so it can be unit-tested with a fake and reused by the CLI and agent tools.
+ */
+import { isLoopFeedbackHandle, legacyGameNodeDiagnostic, migrateGraphNodeTypes } from "@nodetool-ai/protocol";
+import { getProcessSandboxModuleCatalog } from "@nodetool-ai/runtime";
+import { inferredCodeInputNames, inferredCodeOutputNames } from "./code-analysis.js";
+import { isJsCodeNodeType, validateCodeNodeBody } from "./code-node-validation.js";
+import { jsScriptPortMismatches, readJsScriptLink } from "./js-script-link.js";
+import { portTypeAliases } from "./port-types.js";
+import { isNonEmptyString, isObjectLike, isRecord, isString } from "./type-predicates.js";
+import { slotTypeToString, typeMetaToString, typesIncompatible, valueIncompatibleWithType } from "./type-compat.js";
+/**
+ * Editor-only base nodes that carry no executable class — the graph loader
+ * prunes them before a run, so they must not be flagged as "unknown". Their
+ * short names; matched against the `nodetool.workflows.base_node.*` namespace.
+ */
+const EDITOR_ONLY_NODE_NAMES = new Set([
+    "Comment",
+    "Group",
+    "Reroute"
+]);
+export function isEditorOnlyType(nodeType) {
+    const dot = nodeType.lastIndexOf(".");
+    const name = dot >= 0 ? nodeType.slice(dot + 1) : nodeType;
+    return (nodeType.includes(".workflows.base_node.") &&
+        EDITOR_ONLY_NODE_NAMES.has(name));
+}
+/** Handles like `__control__` / `__output__` are framework-internal, not props. */
+function isReservedHandle(handle) {
+    return handle.startsWith("__") && handle.endsWith("__");
+}
+function asRecord(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * `nodes` / `edges` as the arrays their types promise. The graph is parsed from
+ * untrusted JSON on every entry point — a file, a stored row, an LLM's inline
+ * graph — so a member that is a number or an object reaches here and has to be
+ * reported rather than thrown at `.map`. Absent stays absent: an empty half of
+ * a graph is what the other checks already read it as.
+ */
+function graphMembers(value, field, issues) {
+    if (value == null)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    issues.push({
+        severity: "error",
+        code: "invalid_graph",
+        message: `graph.${field} must be an array, not ${isObjectLike(value) ? "an object" : `a ${typeof value}`}`
+    });
+    return [];
+}
+/**
+ * Typed dynamic slot declarations of a node, from either graph shape: the
+ * kernel/runner node carries `dynamic_inputs` at the top level, a ReactFlow
+ * node carries it inside `data`.
+ */
+function readDynamicInputs(node) {
+    const own = asRecord(node.dynamic_inputs);
+    if (own)
+        return own;
+    const fromData = asRecord(node.data?.dynamic_inputs);
+    return (fromData ?? {});
+}
+/** Inline dynamic slot values, from either graph shape. */
+function readDynamicProperties(node) {
+    return (asRecord(node.dynamic_properties) ??
+        asRecord(node.data?.dynamic_properties) ??
+        {});
+}
+/** Typed dynamic output declarations, from either graph shape. */
+function readDynamicOutputs(node) {
+    return (asRecord(node.dynamic_outputs) ?? asRecord(node.data?.dynamic_outputs) ?? {});
+}
+/**
+ * The declared properties of a node, from either graph shape.
+ *
+ * The editor's `NodeData` nests the props bag under `data.properties` (the same
+ * wrapper `readDynamicInputs` and friends unwrap). Reading `data` itself as the
+ * bag made every editor-exported node look like it was missing every required
+ * property. `data` is still the fallback for older/hand-written shapes that
+ * flattened the props onto it.
+ */
+function readProperties(node) {
+    return (asRecord(node.properties) ??
+        asRecord(node.data?.properties) ??
+        asRecord(node.data) ??
+        {});
+}
+/** True for a DSL wiring handle ({__handle: true, source, sourceHandle}). */
+function isWiringHandle(value) {
+    return isRecord(value) && value["__handle"] === true;
+}
+/** Property paths holding a wiring handle, e.g. `tiles[0]`. */
+function collectWiringHandlePaths(value, path, out, depth = 0) {
+    if (depth > MODEL_REF_MAX_DEPTH)
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => collectWiringHandlePaths(item, `${path}[${index}]`, out, depth + 1));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    if (isWiringHandle(value)) {
+        out.push(path);
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        collectWiringHandlePaths(child, path ? `${path}.${key}` : key, out, depth + 1);
+    }
+}
+/**
+ * A control edge is spelled `edge_type: "control"` in the kernel/runner shape
+ * and `type: "control"` / `data.edge_type: "control"` in the ReactFlow shape.
+ */
+function isControlEdge(raw) {
+    return (raw.edge_type === "control" ||
+        raw.type === "control" ||
+        raw.data?.edge_type === "control");
+}
+function normalizeEdge(raw, index) {
+    return {
+        id: isString(raw.id) ? raw.id : `edge-${index}`,
+        source: String(raw.source ?? ""),
+        sourceHandle: String(raw.sourceHandle ?? raw.source_handle ?? ""),
+        target: String(raw.target ?? ""),
+        targetHandle: String(raw.targetHandle ?? raw.target_handle ?? ""),
+        isControl: isControlEdge(raw)
+    };
+}
+/**
+ * True for a model-reference value: a tagged object whose `type` ends in
+ * `_model` (`image_model`, `asr_model`, `tts_model`, `language_model`, …).
+ * Keying on that suffix avoids reacting to any unrelated object that happens
+ * to carry a `provider` field.
+ */
+function isModelRef(value) {
+    // Null first, matching `asRecord` above: `typeof null === "object"`, so the
+    // check is load-bearing — without it `value.type` below throws on null.
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const kind = value.type;
+    return typeof kind === "string" && kind.endsWith("_model");
+}
+/**
+ * How deep the property walk goes looking for model refs. A node's props are a
+ * shallow bag by convention; the depth exists for the shapes that nest one —
+ * a list of models, or a model inside a settings object — not to crawl payloads.
+ */
+const MODEL_REF_MAX_DEPTH = 4;
+/**
+ * Every model reference reachable from `value`.
+ *
+ * Checking only top-level property values missed the ones the type system
+ * allows anywhere: a `list[image_model]` property, or a model nested in a
+ * config object. Those fail exactly like a top-level one does — once the node
+ * runs — so they are worth the same check.
+ */
+function collectModelRefs(value, path, propertyName, out, depth = 0) {
+    if (depth > MODEL_REF_MAX_DEPTH)
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => collectModelRefs(item, `${path}[${index}]`, propertyName, out, depth + 1));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    if (isModelRef(value)) {
+        out.push({ path, propertyName, ref: value });
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        collectModelRefs(child, path ? `${path}.${key}` : key, propertyName, out, depth + 1);
+    }
+}
+/** Model references in one node's declared and dynamic property bags. */
+function collectNodeModelRefs(node) {
+    const sites = [];
+    for (const [propName, value] of Object.entries(readProperties(node))) {
+        collectModelRefs(value, propName, propName, sites);
+    }
+    for (const [propName, value] of Object.entries(readDynamicProperties(node))) {
+        collectModelRefs(value, propName, propName, sites);
+    }
+    return sites;
+}
+/**
+ * Provider id of a model reference, or undefined when it names none. A blank
+ * provider is left to {@link collectModelSelectionIssues}, which reports it
+ * only when an id is present — an entirely empty ref is an unselected model,
+ * which the registry's own property check already covers.
+ */
+function modelProviderOf(ref) {
+    const provider = ref.provider;
+    if (!isNonEmptyString(provider))
+        return undefined;
+    return provider;
+}
+/**
+ * The type an edge's source handle carries, reporting any handle it cannot
+ * resolve. An empty string means the edge is not type-checked at this end — no
+ * metadata, a reserved handle, or a dynamic output declaring no type.
+ */
+function resolveSourceHandleType(edge, sourceNode, sourceMeta, issues) {
+    if (!sourceMeta ||
+        !edge.sourceHandle ||
+        isReservedHandle(edge.sourceHandle)) {
+        return "";
+    }
+    const declared = sourceMeta.outputs.find((o) => o.name === edge.sourceHandle);
+    if (declared)
+        return typeMetaToString(declared.type);
+    // Metadata, not instance state: `reactFlowNodeToGraphNode` writes
+    // `dynamic_outputs: {}` on every node, so testing the instance field
+    // disabled this check for nearly every saved graph. Mirrors the target
+    // side's use of `supports_dynamic_inputs`.
+    if (sourceMeta.supports_dynamic_outputs !== true) {
+        issues.push({
+            severity: "error",
+            code: "unknown_handle",
+            edgeId: edge.id,
+            nodeId: edge.source,
+            nodeType: String(sourceNode.type ?? ""),
+            message: `Edge "${edge.id}" references output "${edge.sourceHandle}" not found on ${String(sourceNode.type)}`
+        });
+        return "";
+    }
+    // An empty map is a node that never declared any dynamic output (the
+    // ReactFlow → graph conversion writes `{}` on every node), so only a
+    // populated one can say a handle is missing. A name the body emits counts as
+    // declared: the editor shows it and an agent can connect to it.
+    const dynamicOutputs = readDynamicOutputs(sourceNode);
+    const names = Object.keys(dynamicOutputs);
+    const inferred = isJsCodeNodeType(String(sourceNode.type ?? ""))
+        ? inferredCodeOutputNames(String(readProperties(sourceNode).code ?? ""))
+        : [];
+    if (names.length > 0 &&
+        !new Set([...names, ...inferred]).has(edge.sourceHandle)) {
+        issues.push({
+            severity: "error",
+            code: "unknown_handle",
+            edgeId: edge.id,
+            nodeId: edge.source,
+            nodeType: String(sourceNode.type ?? ""),
+            message: `Edge "${edge.id}" references output "${edge.sourceHandle}" on ${String(sourceNode.type)}, which declares ${names.map((n) => `"${n}"`).join(", ")}`
+        });
+        return "";
+    }
+    return typeMetaToString(dynamicOutputs[edge.sourceHandle]);
+}
+/**
+ * The type an edge's target handle expects — the mirror of
+ * {@link resolveSourceHandleType}, except that a dynamic slot declaring no
+ * type is reported rather than passed over in silence.
+ */
+function resolveTargetHandleType(edge, targetNode, targetMeta, issues) {
+    if (!targetMeta ||
+        !edge.targetHandle ||
+        isReservedHandle(edge.targetHandle)) {
+        return { type: "", typedDynamicSlot: false };
+    }
+    const declared = targetMeta.properties.find((p) => p.name === edge.targetHandle);
+    if (declared) {
+        return { type: typeMetaToString(declared.type), typedDynamicSlot: false };
+    }
+    if (targetMeta.supports_dynamic_inputs !== true) {
+        issues.push({
+            severity: "error",
+            code: "unknown_handle",
+            edgeId: edge.id,
+            nodeId: edge.target,
+            nodeType: String(targetNode.type ?? ""),
+            message: `Edge "${edge.id}" targets input "${edge.targetHandle}" not found on ${String(targetNode.type)}`
+        });
+        return { type: "", typedDynamicSlot: false };
+    }
+    const slotType = slotTypeToString(readDynamicInputs(targetNode)[edge.targetHandle]);
+    if (slotType) {
+        return { type: slotType, typedDynamicSlot: true };
+    }
+    issues.push({
+        severity: "info",
+        code: "untyped_dynamic_slot",
+        edgeId: edge.id,
+        nodeId: edge.target,
+        nodeType: String(targetNode.type ?? ""),
+        message: `Edge "${edge.id}" targets dynamic input "${edge.targetHandle}" on ${String(targetNode.type)}, which declares no type — the connection is not type-checked`
+    });
+    return { type: "", typedDynamicSlot: false };
+}
+/**
+ * Self-loops and cycles — both fatal at run time, neither visible before it.
+ *
+ * `Graph.validateEdgeEndpoints` (kernel) rejects a self-loop on *any* edge:
+ * the node waits on an input only its own completion can close, so the run
+ * hangs. `analyzeCorrelation` requires the **data** subgraph to be a DAG, and
+ * its topological sort skips control edges — so cycles are looked for over
+ * data edges only, matching the kernel exactly.
+ *
+ * Kahn's algorithm, iterative: a deep graph must not blow the stack.
+ */
+function detectCycles(byId, normEdges) {
+    const issues = [];
+    const selfLooped = new Set();
+    for (const e of normEdges) {
+        if (e.source !== e.target || !byId.has(e.source))
+            continue;
+        if (selfLooped.has(e.source))
+            continue;
+        selfLooped.add(e.source);
+        issues.push({
+            severity: "error",
+            code: "cycle",
+            nodeId: e.source,
+            nodeType: String(byId.get(e.source)?.type ?? ""),
+            edgeId: e.id,
+            message: `Node "${e.source}" is connected to itself by edge "${e.id}"; self-loop edges are not supported and deadlock the run`
+        });
+    }
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const id of byId.keys()) {
+        incoming.set(id, 0);
+        outgoing.set(id, []);
+    }
+    for (const e of normEdges) {
+        if (e.isControl)
+            continue;
+        if (e.source === e.target)
+            continue;
+        if (!byId.has(e.source) || !byId.has(e.target))
+            continue;
+        if (isLoopFeedbackHandle(String(byId.get(e.target)?.type ?? ""), e.targetHandle)) {
+            continue;
+        }
+        outgoing.get(e.source).push(e.target);
+        incoming.set(e.target, (incoming.get(e.target) ?? 0) + 1);
+    }
+    const queue = [];
+    for (const [id, count] of incoming) {
+        if (count === 0)
+            queue.push(id);
+    }
+    let ordered = 0;
+    // Index instead of shift(): shift() on a large array is O(n) per call.
+    for (let head = 0; head < queue.length; head++) {
+        ordered++;
+        for (const target of outgoing.get(queue[head]) ?? []) {
+            const next = (incoming.get(target) ?? 0) - 1;
+            incoming.set(target, next);
+            if (next === 0)
+                queue.push(target);
+        }
+    }
+    if (ordered < byId.size) {
+        const seen = new Set(queue);
+        const remaining = [...byId.keys()].filter((id) => !seen.has(id));
+        issues.push({
+            severity: "error",
+            code: "cycle",
+            nodeId: remaining[0],
+            nodeType: String(byId.get(remaining[0])?.type ?? ""),
+            message: `Cycle detected in graph; a cycle may only close on the "next" or "condition" input of a Loop node. Involved nodes: ${remaining.join(", ")}`
+        });
+    }
+    return issues;
+}
+/**
+ * Model id of a model reference. A blank id is an unselected model, which the
+ * registry's own property check already reports.
+ */
+function modelIdOf(ref) {
+    const id = ref.id;
+    if (!isNonEmptyString(id))
+        return undefined;
+    return id;
+}
+/**
+ * The `_model` type tag of a model reference. Which catalog an id has to appear
+ * in depends on it: a provider's ASR ids and its image ids are separate lists,
+ * and only some are knowable offline.
+ */
+function modelKindOf(ref) {
+    return String(ref.type);
+}
+/**
+ * The few known ids closest to `id`, to turn "not a model" into a fix. Manifest
+ * ids are long and slash-separated (`fal-ai/ltx-2/image-to-video/fast`), so a
+ * shared prefix locates a near-miss far better than edit distance over the
+ * whole string; ties break toward the closest length.
+ */
+function nearestModelIds(id, known, limit = 3) {
+    const needle = id.toLowerCase();
+    const prefixLen = (candidate) => {
+        const other = candidate.toLowerCase();
+        let i = 0;
+        while (i < needle.length && i < other.length && needle[i] === other[i])
+            i++;
+        return i;
+    };
+    return ([...known]
+        .map((candidate) => ({ candidate, score: prefixLen(candidate) }))
+        // A single shared character is noise, not a suggestion.
+        .filter((entry) => entry.score >= 3)
+        .sort((a, b) => b.score - a.score ||
+        Math.abs(a.candidate.length - id.length) -
+            Math.abs(b.candidate.length - id.length) ||
+        a.candidate.localeCompare(b.candidate))
+        .slice(0, limit)
+        .map((entry) => entry.candidate));
+}
+/**
+ * Every provider/model id in `graph` that the runtime cannot honour.
+ *
+ * Split out of {@link validateGraph} so a caller that wants only this — a run
+ * preflight, an agent about to save a graph — pays for a property walk instead
+ * of a full graph validation, and so all of them report the same thing. The
+ * checks stay in `validateGraph` too; this is the same code, not a second
+ * opinion.
+ *
+ * Both checks fail toward silence. An empty provider list means the registry
+ * could not be reached, not that zero providers exist; an undefined model list
+ * means the catalog is only knowable online. Neither is evidence of a bad id.
+ */
+export function collectModelSelectionIssues(graph, registry) {
+    const providerIds = registry.listProviderIds?.();
+    const knownProviders = providerIds && providerIds.length > 0 ? new Set(providerIds) : null;
+    if (!knownProviders)
+        return [];
+    const issues = [];
+    for (const node of graph.nodes ?? []) {
+        const nodeId = String(node.id ?? "");
+        const nodeType = String(node.type ?? "");
+        for (const { path, ref } of collectNodeModelRefs(node)) {
+            const modelId = modelIdOf(ref);
+            const provider = modelProviderOf(ref);
+            if (provider === undefined) {
+                // No provider and no id is an unselected model — the registry's own
+                // property check reports that one. An id without a provider is
+                // different: it names a model nothing can route to.
+                if (modelId !== undefined) {
+                    issues.push({
+                        severity: "error",
+                        code: "missing_provider",
+                        nodeId,
+                        nodeType,
+                        message: `Property "${path}" selects model "${modelId}" but names no ` +
+                            "provider; the runtime cannot resolve a model id on its own"
+                    });
+                }
+                continue;
+            }
+            if (!knownProviders.has(provider)) {
+                issues.push({
+                    severity: "error",
+                    code: "unknown_provider",
+                    nodeId,
+                    nodeType,
+                    message: `Property "${path}" selects provider "${provider}", which is ` +
+                        `not registered. Known providers: ${[...knownProviders]
+                            .sort()
+                            .join(", ")}`
+                });
+                continue;
+            }
+            // The provider is real; the id it names may still not be. A model id is
+            // only checkable where the catalog is known offline — undefined from the
+            // registry means unknown, so nothing is reported.
+            if (modelId === undefined)
+                continue;
+            const knownModels = registry.listModelIds?.(provider, modelKindOf(ref));
+            if (!knownModels || knownModels.length === 0)
+                continue;
+            if (knownModels.includes(modelId))
+                continue;
+            const suggestions = nearestModelIds(modelId, knownModels);
+            issues.push({
+                severity: "error",
+                code: "unknown_model",
+                nodeId,
+                nodeType,
+                message: `Property "${path}" selects model "${modelId}", which provider ` +
+                    `"${provider}" does not offer.` +
+                    (suggestions.length > 0
+                        ? ` Did you mean: ${suggestions.join(", ")}?`
+                        : "")
+            });
+        }
+    }
+    return issues;
+}
+/** A property value that reaches a provider as "the caller set nothing". */
+function isBlankPropertyValue(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (isString(value))
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+/**
+ * Properties a node leaves blank that the model it selects declares it will not
+ * run without.
+ *
+ * A generic media node takes one shape and routes it to whichever provider the
+ * `model` property names, and those providers disagree about what is optional:
+ * Veo 3.1 animates an image with no prompt, Kling refuses the same call with
+ * `500 This field is required` — no field named, no node named, after the
+ * upstream half of the graph has been paid for. The requirement is already
+ * written down in the generated provider manifests; this is the check that
+ * reads it while the graph is still being authored.
+ *
+ * Reported at `info`, which is the honest severity: the graph is not wrong, it
+ * is *model-specific*. Pinned to Veo it runs; the finding is that swapping the
+ * model breaks it. `info` also keeps it below the `--warnings-as-errors`
+ * ratchet the shipped-examples gate runs at, so a generated manifest that marks
+ * something required by mistake cannot fail a build over a graph that works.
+ *
+ * Only where every part of the answer is known: the provider must enumerate its
+ * requirements offline, the node must declare a property of that name, nothing
+ * may feed it, and the model reference must be the node's own top-level
+ * property. Anything less is silence.
+ */
+function collectRequiredModelInputIssues(nodeId, nodeType, node, declaredProperties, connectedHandles, registry) {
+    if (!registry.listRequiredTextInputs)
+        return [];
+    const properties = readProperties(node);
+    const issues = [];
+    const reported = new Set();
+    for (const { path, propertyName, ref } of collectNodeModelRefs(node)) {
+        // A model nested in a settings object or a list configures something other
+        // than this node's own inputs, so its requirements say nothing about them.
+        if (path !== propertyName)
+            continue;
+        const provider = modelProviderOf(ref);
+        const modelId = modelIdOf(ref);
+        if (provider === undefined || modelId === undefined)
+            continue;
+        const required = registry.listRequiredTextInputs(provider, modelKindOf(ref), modelId);
+        if (!required)
+            continue;
+        for (const name of required) {
+            if (reported.has(name))
+                continue;
+            if (!declaredProperties.has(name))
+                continue;
+            if (connectedHandles.has(name))
+                continue;
+            if (!isBlankPropertyValue(properties[name]))
+                continue;
+            reported.add(name);
+            issues.push({
+                severity: "info",
+                code: "missing_required_model_input",
+                nodeId,
+                nodeType,
+                message: `Node "${nodeId}" leaves "${name}" empty, and model "${modelId}" ` +
+                    `(${provider}) declares it required. Set "${name}" or wire it — ` +
+                    "until then, swapping this node's model breaks the graph."
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Every credential name a graph's nodes declare, deduplicated per node.
+ *
+ * Split out of {@link collectMissingSecretIssues} so a host can resolve the
+ * names against its store first and hand back only the availability set —
+ * validation stays synchronous and store-shaped knowledge stays with the
+ * host that owns it.
+ */
+export function collectSecretRequirementSites(graph, registry) {
+    const sites = [];
+    const seen = new Set();
+    for (const node of graph.nodes ?? []) {
+        const nodeId = String(node.id ?? "");
+        const nodeType = String(node.type ?? "");
+        if (!nodeType || !registry.has(nodeType))
+            continue;
+        const meta = registry.getMetadata(nodeType);
+        for (const key of meta?.required_settings ?? []) {
+            if (!isNonEmptyString(key))
+                continue;
+            const dedupeKey = `${nodeId}\u0000${key}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            sites.push({ nodeId, nodeType, key, source: "required_setting" });
+        }
+        if (!isJsCodeNodeType(nodeType))
+            continue;
+        const declaredSecrets = readProperties(node).secrets;
+        if (!Array.isArray(declaredSecrets))
+            continue;
+        for (const value of declaredSecrets) {
+            if (!isNonEmptyString(value))
+                continue;
+            const dedupeKey = `${nodeId}\u0000${value}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            sites.push({ nodeId, nodeType, key: value, source: "code_secret" });
+        }
+    }
+    return sites;
+}
+/**
+ * Nodes whose declared credentials the supplied set cannot resolve.
+ *
+ * Both sources warn rather than error. A `required_settings` entry reaches
+ * `process()` as an empty string when absent, and some nodes treat that as
+ * optional at call time (a HuggingFace token widens the model catalog but is
+ * not the only way in), so absence does not prove a failed run. The Code
+ * node's list scopes reads rather than requiring them, for the same reason.
+ * The certain failure — a provider constructed without the credential its
+ * registration requires — is checked where the answer is certain, in the
+ * run preflight (`@nodetool-ai/execution`), against the provider registry.
+ *
+ * Fails toward silence like every catalog here: no set, nothing reported.
+ */
+export function collectMissingSecretIssues(graph, registry, availableSecrets) {
+    if (!availableSecrets)
+        return [];
+    const issues = [];
+    for (const site of collectSecretRequirementSites(graph, registry)) {
+        if (availableSecrets.has(site.key))
+            continue;
+        issues.push({
+            severity: "warning",
+            code: "missing_secret",
+            nodeId: site.nodeId,
+            nodeType: site.nodeType,
+            message: site.source === "code_secret"
+                ? `Node "${site.nodeId}" declares secret "${site.key}", which this ` +
+                    "install cannot resolve — the body's reads of it will fail."
+                : `Node "${site.nodeId}" (${site.nodeType}) needs "${site.key}", ` +
+                    "which this install cannot resolve. Set it in Settings → " +
+                    "Credentials, or the node may fail when it runs."
+        });
+    }
+    return issues;
+}
+/**
+ * Distinct provider ids across every model reference in the graph, in walk
+ * order. The run preflight resolves each against the provider registry to
+ * refuse a graph whose credentials are missing before anything executes.
+ */
+export function collectModelProviders(graph) {
+    const providers = new Set();
+    const connectedInputs = new Set((graph.edges ?? [])
+        .map(normalizeEdge)
+        .filter((edge) => !edge.isControl && edge.target && edge.targetHandle)
+        .map((edge) => `${edge.target}\u0000${edge.targetHandle}`));
+    for (const node of graph.nodes ?? []) {
+        const nodeId = String(node.id ?? "");
+        for (const { propertyName, ref } of collectNodeModelRefs(node)) {
+            if (connectedInputs.has(`${nodeId}\u0000${propertyName}`))
+                continue;
+            const provider = modelProviderOf(ref);
+            if (provider !== undefined)
+                providers.add(provider);
+        }
+    }
+    return [...providers];
+}
+/**
+ * Every pinned script link a graph's Code nodes carry, deduplicated. A host
+ * that wants the linked-script checks loads these first and hands
+ * {@link validateGraph} a lookup over the result.
+ */
+export function collectJsScriptLinks(graph) {
+    const seen = new Map();
+    for (const node of graph.nodes ?? []) {
+        if (!isJsCodeNodeType(String(node.type ?? "")))
+            continue;
+        const link = readJsScriptLink(readProperties(node));
+        if (!link)
+            continue;
+        seen.set(`${link.id}@${link.version}`, link);
+    }
+    return [...seen.values()];
+}
+/**
+ * DSL wiring handles stored as property values. The builders mint these to
+ * wire an edge; one that survives into a bag means the connection was never
+ * made, so the input is unconnected and the node producing it may be missing
+ * from the graph entirely. Runs before the registry guard: the marker is
+ * shape-level, not type-level.
+ */
+function collectLeftoverWiringHandleIssues(nodeId, nodeType, node) {
+    const issues = [];
+    for (const [propName, value] of Object.entries(readProperties(node))) {
+        const handlePaths = [];
+        collectWiringHandlePaths(value, propName, handlePaths);
+        for (const path of handlePaths) {
+            issues.push({
+                severity: "error",
+                code: "leftover_wiring_handle",
+                nodeId,
+                nodeType,
+                message: `Property "${path}" on node "${nodeId}" still holds a wiring ` +
+                    "handle — the connection was never created, so the node " +
+                    "producing this output may be missing from the graph. Re-wire " +
+                    "it as an edge."
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Properties the node does not have. A misspelled name is dead data: the value
+ * sits in the graph, the real property keeps its default, and nothing reports
+ * it. A required property left unset is already an error elsewhere, so what
+ * reaches here is an optional one silently ignored — a warning, not a refusal.
+ * Nodes taking dynamic properties are exempt: an undeclared name is the
+ * feature there.
+ */
+function collectUnknownPropertyIssues(nodeId, nodeType, node, meta) {
+    if (meta.supports_dynamic_inputs === true)
+        return [];
+    const declaredNames = new Set(meta.properties.map((prop) => prop.name));
+    const dynamic = readDynamicProperties(node);
+    const unknown = Object.keys(readProperties(node)).filter((name) => !declaredNames.has(name) &&
+        !isReservedHandle(name) &&
+        dynamic[name] === undefined);
+    if (unknown.length === 0)
+        return [];
+    const plural = unknown.length > 1;
+    const named = unknown.map((name) => `"${name}"`).join(", ");
+    const known = [...declaredNames].sort().join(", ");
+    return [
+        {
+            severity: "warning",
+            code: "unknown_property",
+            nodeId,
+            nodeType,
+            message: `${named} ${plural ? "are" : "is"} not a property of ${nodeType}, so ${plural ? "they are" : "it is"} ignored at run time.${known ? ` It takes: ${known}.` : ""}`
+        }
+    ];
+}
+/**
+ * Dynamic slot types: a JSON-Schema/TypeScript spelling of a type NodeTool
+ * already has passes the transport schema, then silently refuses to connect.
+ * Custom names stay legal — only known aliases are flagged. Inputs are
+ * reported before outputs.
+ */
+function collectSlotTypeAliasIssues(nodeId, nodeType, node) {
+    const issues = [];
+    const check = (direction, slotName, slotType) => {
+        for (const alias of portTypeAliases(slotType)) {
+            issues.push({
+                severity: "error",
+                code: "slot_type_alias",
+                nodeId,
+                nodeType,
+                message: `Dynamic ${direction} "${slotName}" is typed "${alias.used}", which is not a ` +
+                    `NodeTool type — use "${alias.canonical}". A handle typed with an unknown ` +
+                    "name will not connect."
+            });
+        }
+    };
+    for (const [slotName, slot] of Object.entries(readDynamicInputs(node))) {
+        check("input", slotName, slot?.type);
+    }
+    for (const [slotName, slotType] of Object.entries(readDynamicOutputs(node))) {
+        check("output", slotName, slotType);
+    }
+    return issues;
+}
+/**
+ * A Code node's linked script: the node carries a *copy* of the pinned
+ * script's body, so the body itself is checked exactly like an inline one.
+ * What the link adds is a freshness question — does the node's shape still
+ * match the script it came from? Nothing here blocks a run, because a run no
+ * longer reads the script row.
+ */
+function collectJsScriptLinkIssues(nodeId, nodeType, node, link, connectedInputs, lookup) {
+    const resolved = lookup ? lookup(link) : undefined;
+    if (!resolved) {
+        return [
+            {
+                severity: "warning",
+                code: lookup ? "js_script_missing" : "js_script_unverified",
+                nodeId,
+                nodeType,
+                message: `Node "${nodeId}" is linked to JS script ${link.id} v${link.version}, ` +
+                    (lookup
+                        ? "which no longer exists, so the link's freshness cannot be " +
+                            "verified. The node runs the body it copied at link time."
+                        : "whose freshness cannot be verified here — no script store is " +
+                            "available. The node runs the body it copied at link time.")
+            }
+        ];
+    }
+    // Compare the script to slots the node actually stores. Names the body reads
+    // are implicit handles for the editor; they must not hide a missing stored
+    // slot on a linked node.
+    const nodeInputs = [
+        ...Object.keys(readDynamicInputs(node)),
+        ...Object.keys(readDynamicProperties(node)),
+        ...connectedInputs
+    ].filter((name) => !isReservedHandle(name));
+    return jsScriptPortMismatches({
+        scriptInputs: resolved.document.inputs.map((port) => port.name),
+        scriptOutputs: resolved.document.outputs.map((port) => port.name),
+        nodeInputs,
+        nodeOutputs: Object.keys(readDynamicOutputs(node))
+    }).map((mismatch) => ({
+        severity: "error",
+        code: "js_script_ports",
+        nodeId,
+        nodeType,
+        message: `Node "${nodeId}": ${mismatch}.`
+    }));
+}
+/**
+ * Code nodes: the body is only checked by running it, and a run costs the
+ * whole graph. Everything decidable from the graph is decided here.
+ */
+function collectCodeNodeIssues(nodeId, nodeType, node, connectedHandles, consumedHandles, sandboxModuleCatalog, jsScriptLookup) {
+    const props = readProperties(node);
+    const code = String(props.code ?? "");
+    const connectedInputs = [...connectedHandles].filter((name) => !isReservedHandle(name));
+    // A named `inputs.foo` / `stream("foo")` read is a handle. The editor shows
+    // it; an agent can connect to it. Count it as declared so the body is not
+    // rejected for a slot the code itself just created.
+    const availableInputs = new Set([
+        ...Object.keys(readDynamicInputs(node)),
+        ...Object.keys(readDynamicProperties(node)),
+        ...connectedInputs,
+        ...inferredCodeInputNames(code)
+    ]);
+    const link = readJsScriptLink(props);
+    const issues = link
+        ? collectJsScriptLinkIssues(nodeId, nodeType, node, link, connectedInputs, jsScriptLookup)
+        : [];
+    for (const codeIssue of validateCodeNodeBody({
+        code: props.code,
+        availableInputs: [...availableInputs].filter((name) => !isReservedHandle(name)),
+        connectedInputs,
+        declaredOutputs: [
+            ...new Set([
+                ...Object.keys(readDynamicOutputs(node)),
+                ...inferredCodeOutputNames(code)
+            ])
+        ],
+        connectedOutputs: [...consumedHandles],
+        sandboxModuleCatalog
+    })) {
+        issues.push({
+            severity: codeIssue.severity,
+            code: codeIssue.code,
+            nodeId,
+            nodeType,
+            message: `Node "${nodeId}": ${codeIssue.message}`
+        });
+    }
+    return issues;
+}
+export function validateGraph(rawGraph, registry, options = {}) {
+    // Validate what the runner will execute. `Graph.loadFromDict` rewrites
+    // removed node types through NODE_TYPE_MIGRATIONS on every load, so a saved
+    // graph carrying one runs fine — but validating the raw graph reported the
+    // migrated-away type as `unknown_node` and refused it. Two shipped examples
+    // (text_transforms_cli, text_regex_parse_cli) sat in exactly that gap.
+    const graph = migrateGraphNodeTypes(rawGraph);
+    const sandboxModuleCatalog = options.sandboxModuleCatalog !== undefined
+        ? options.sandboxModuleCatalog
+        : getProcessSandboxModuleCatalog();
+    const issues = [];
+    const nodes = graphMembers(graph.nodes, "nodes", issues);
+    const edges = graphMembers(graph.edges, "edges", issues);
+    // ── Nodes: ids, types, properties ────────────────────────────────────────
+    const byId = new Map();
+    const seenIds = new Set();
+    for (const node of nodes) {
+        const id = String(node.id ?? "");
+        const type = String(node.type ?? "");
+        if (!id) {
+            // Nothing can address this node: no edge can name it, and the runner
+            // keys every message by node id.
+            issues.push({
+                severity: "error",
+                code: "missing_id",
+                nodeType: type,
+                message: `Node of type "${type || "(no type)"}" has no id`
+            });
+        }
+        if (id && seenIds.has(id)) {
+            issues.push({
+                severity: "error",
+                code: "duplicate_id",
+                nodeId: id,
+                nodeType: type,
+                message: `Duplicate node id "${id}"`
+            });
+        }
+        else if (id) {
+            seenIds.add(id);
+            byId.set(id, node);
+        }
+        if (!type) {
+            issues.push({
+                severity: "error",
+                code: "unknown_node",
+                nodeId: id,
+                message: `Node "${id}" has no type`
+            });
+        }
+        else if (!registry.has(type) && !isEditorOnlyType(type)) {
+            issues.push({
+                severity: "error",
+                code: "unknown_node",
+                nodeId: id,
+                nodeType: type,
+                message: legacyGameNodeDiagnostic(type) ?? `Unknown node type "${type}" (not in the registry; Python-only nodes are not validated statically)`
+            });
+        }
+    }
+    // Handles fed by an incoming edge get their value at runtime — don't flag
+    // them as missing required properties.
+    const connectedByNode = new Map();
+    // Source handles other nodes read — the output handles that have to exist.
+    const consumedByNode = new Map();
+    const normEdges = edges.map(normalizeEdge);
+    const addHandle = (map, nodeId, handle) => {
+        const set = map.get(nodeId);
+        if (set) {
+            set.add(handle);
+        }
+        else {
+            map.set(nodeId, new Set([handle]));
+        }
+    };
+    for (const e of normEdges) {
+        if (e.target && e.targetHandle) {
+            addHandle(connectedByNode, e.target, e.targetHandle);
+        }
+        if (e.source && e.sourceHandle && !isReservedHandle(e.sourceHandle)) {
+            addHandle(consumedByNode, e.source, e.sourceHandle);
+        }
+    }
+    // `byId` holds one node per id — a duplicate id is already an error, and
+    // validating the shadowed copy's properties would report everything twice.
+    for (const [id, node] of byId) {
+        const type = String(node.type ?? "");
+        const connected = connectedByNode.get(id) ?? new Set();
+        issues.push(...collectLeftoverWiringHandleIssues(id, type, node));
+        if (!type || !registry.has(type))
+            continue;
+        const propIssues = registry.validateNode({
+            id,
+            type,
+            properties: readProperties(node),
+            // Without these the registry cannot reach validateDynamicSlots, so a
+            // slot declared `required` is never checked.
+            dynamic_inputs: readDynamicInputs(node),
+            dynamic_properties: readDynamicProperties(node)
+        }, connected);
+        for (const pi of propIssues) {
+            issues.push({
+                severity: "error",
+                code: "property",
+                nodeId: id,
+                nodeType: type,
+                message: pi.message
+            });
+        }
+        const meta = registry.getMetadata(type);
+        if (meta) {
+            // Properties blank that the selected model declares required. The
+            // registry's own check above knows which properties this node requires;
+            // it cannot know which ones the model behind `model` requires.
+            issues.push(...collectRequiredModelInputIssues(id, type, node, new Set(meta.properties.map((prop) => prop.name)), connected, registry), ...collectUnknownPropertyIssues(id, type, node, meta));
+        }
+        issues.push(...collectSlotTypeAliasIssues(id, type, node));
+        // A `code` handle fed by an edge carries a body nothing here can see.
+        if (isJsCodeNodeType(type) && !connected.has("code")) {
+            issues.push(...collectCodeNodeIssues(id, type, node, connected, consumedByNode.get(id) ?? new Set(), sandboxModuleCatalog, options.jsScriptLookup));
+        }
+    }
+    // A model property naming a provider the runtime cannot construct, or an id
+    // that provider does not offer, fails only once the node runs — after the
+    // rest of the graph has already been paid for. Both are right there in the
+    // saved properties.
+    issues.push(...collectModelSelectionIssues({ nodes: [...byId.values()] }, registry));
+    // Declared credentials the supplied availability set cannot resolve — a
+    // warning per site, and nothing at all when no set was supplied.
+    issues.push(...collectMissingSecretIssues({ nodes: [...byId.values()] }, registry, options.availableSecrets));
+    // ── Fan-in: >1 edge into a handle is only legal when the handle's declared
+    // type is a list. Mirrors the kernel's correlation-analysis rule so an
+    // example that validates cannot die at run time on exactly this.
+    const fanIn = new Map();
+    for (const e of normEdges) {
+        // Control edges carry no data — `analyzeCorrelation` filters them out
+        // before counting, so counting them here would invent errors.
+        if (e.isControl)
+            continue;
+        if (!e.target || !e.targetHandle)
+            continue;
+        const key = `${e.target}\u0000${e.targetHandle}`;
+        fanIn.set(key, (fanIn.get(key) ?? 0) + 1);
+    }
+    for (const [key, count] of fanIn) {
+        if (count < 2)
+            continue;
+        const [targetId, handle] = key.split("\u0000");
+        const node = byId.get(targetId);
+        const type = String(node?.type ?? "");
+        if (!type || !registry.has(type))
+            continue;
+        const propType = registry
+            .getMetadata(type)
+            ?.properties?.find((prop) => prop.name === handle)?.type;
+        // A dynamic slot is not a static property. The kernel merges declared slot
+        // types into `propertyTypes` (Graph.loadFromDict), so a slot declared
+        // `list[...]` is a legal fan-in target — resolve it the same way here.
+        const typeStr = typeMetaToString(propType) ||
+            slotTypeToString(node ? readDynamicInputs(node)[handle] : undefined);
+        if (!(typeStr === "list" || typeStr.startsWith("list["))) {
+            issues.push({
+                severity: "error",
+                code: "fan_in",
+                nodeId: targetId,
+                nodeType: type,
+                message: `Handle "${handle}" on node "${targetId}" receives ${count} edges but its ` +
+                    `type "${typeStr || "unknown"}" is not a list; the kernel's correlation ` +
+                    `analysis rejects this at run time`
+            });
+        }
+    }
+    // ── Cycles: only Loop feedback edges may close one ───────────────────────
+    issues.push(...detectCycles(byId, normEdges));
+    // ── Edges: endpoints, handles, type compatibility ────────────────────────
+    for (const e of normEdges) {
+        const sourceNode = byId.get(e.source);
+        const targetNode = byId.get(e.target);
+        if (!sourceNode) {
+            issues.push({
+                severity: "error",
+                code: "dangling_edge",
+                edgeId: e.id,
+                message: `Edge "${e.id}" source node "${e.source}" does not exist`
+            });
+        }
+        if (!targetNode) {
+            issues.push({
+                severity: "error",
+                code: "dangling_edge",
+                edgeId: e.id,
+                message: `Edge "${e.id}" target node "${e.target}" does not exist`
+            });
+        }
+        if (!sourceNode || !targetNode)
+            continue;
+        // Both endpoints exist but the edge names no handle: the kernel routes
+        // messages by `${source}:${sourceHandle}`, so an empty handle matches
+        // nothing and the edge silently carries no data. The handle checks below
+        // are all gated on a non-empty handle, so without this the edge would
+        // validate clean.
+        if (!e.sourceHandle) {
+            issues.push({
+                severity: "error",
+                code: "missing_handle",
+                edgeId: e.id,
+                nodeId: e.source,
+                nodeType: String(sourceNode.type ?? ""),
+                message: `Edge "${e.id}" names no source handle on node "${e.source}" — it cannot be routed`
+            });
+        }
+        if (!e.targetHandle) {
+            issues.push({
+                severity: "error",
+                code: "missing_handle",
+                edgeId: e.id,
+                nodeId: e.target,
+                nodeType: String(targetNode.type ?? ""),
+                message: `Edge "${e.id}" names no target handle on node "${e.target}" — it cannot be routed`
+            });
+        }
+        const sourceType = resolveSourceHandleType(e, sourceNode, registry.getMetadata(String(sourceNode.type ?? "")), issues);
+        const target = resolveTargetHandleType(e, targetNode, registry.getMetadata(String(targetNode.type ?? "")), issues);
+        if (typesIncompatible(sourceType, target.type)) {
+            issues.push({
+                severity: target.typedDynamicSlot ? "error" : "warning",
+                code: "type_mismatch",
+                edgeId: e.id,
+                nodeId: e.target,
+                nodeType: String(targetNode.type ?? ""),
+                message: target.typedDynamicSlot
+                    ? `Edge "${e.id}" connects ${String(sourceNode.type)}.${e.sourceHandle} (${sourceType}) → dynamic input ${String(targetNode.type)}.${e.targetHandle}, declared as ${target.type}`
+                    : `Edge "${e.id}" connects ${String(sourceNode.type)}.${e.sourceHandle} (${sourceType}) → ${String(targetNode.type)}.${e.targetHandle} (${target.type}) — types may be incompatible`
+            });
+        }
+    }
+    // ── Inline dynamic values against their declared slot types ──────────────
+    for (const node of nodes) {
+        const slots = readDynamicInputs(node);
+        const slotNames = Object.keys(slots);
+        if (slotNames.length === 0)
+            continue;
+        const id = String(node.id ?? "");
+        const values = readDynamicProperties(node);
+        const connected = connectedByNode.get(id);
+        for (const name of slotNames) {
+            if (connected?.has(name))
+                continue;
+            const typeStr = slotTypeToString(slots[name]);
+            if (valueIncompatibleWithType(values[name], typeStr)) {
+                issues.push({
+                    severity: "warning",
+                    code: "dynamic_type_mismatch",
+                    nodeId: id,
+                    nodeType: String(node.type ?? ""),
+                    message: `Dynamic input "${name}" on node "${id}" is declared as ${typeStr} but holds a ${typeof values[name]}`
+                });
+            }
+        }
+    }
+    let errors = 0;
+    let warnings = 0;
+    let info = 0;
+    for (const i of issues) {
+        if (i.severity === "error")
+            errors++;
+        else if (i.severity === "warning")
+            warnings++;
+        else if (i.severity === "info")
+            info++;
+    }
+    return {
+        ok: errors === 0,
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+        counts: { errors, warnings, info },
+        issues
+    };
+}
+/** One-line summary headline for human output. */
+export function validationHeadline(report) {
+    if (report.ok && report.counts.warnings === 0) {
+        return `Workflow is valid — ${report.nodeCount} node(s), ${report.edgeCount} edge(s).`;
+    }
+    if (report.ok) {
+        return `Workflow is valid with ${report.counts.warnings} warning(s).`;
+    }
+    return `Workflow has ${report.counts.errors} error(s)${report.counts.warnings ? ` and ${report.counts.warnings} warning(s)` : ""}.`;
+}
+//# sourceMappingURL=graph-validation.js.map