@oxygen-agent/cli 1.365.3 → 1.575.19

package/node_modules/@oxygen/workflows/dist/graph/lint.js

@@ -0,0 +1,812 @@
+// The oxygen-workflows-v2 linter — the v2 sibling of lintWorkflowManifest, with
+// the same shape (`{ ok, issues[] }`), the same `$.`-rooted JSON paths, and the
+// same snake_case issue codes wherever a v1 rule carries over.
+//
+// NOT BROWSER-SAFE, deliberately: it reuses v1's validatePureFunctionSource and
+// validateTrigger from ../index.js, which pulls node:vm and node:crypto. This is
+// why ./index.ts (the "@oxygen/workflows/graph" entry) does not re-export this
+// module — the editor lints through the API, not in the bundle.
+import { validateFormulaExpression } from "@oxygen/formula";
+import { isWorkflowToolRejected, validateOptionalMaxCredits, validatePureFunctionSource, validateTrigger, } from "../index.js";
+import { UNARY_COMPARE_OPS, WORKFLOW_COMPARE_OPS, compileConditionPattern, parseScopePath, SCOPE_PATH_ROOTS, } from "./expression.js";
+import { missingToolParams, unknownToolParams } from "./params.js";
+import { danglingEdges, findIllegalCycles, loopBodyNodeIds, reachableNodeIds } from "./topology.js";
+import { MAX_WORKFLOW_LOOP_ITERATIONS, MAX_WORKFLOW_NODE_RETRY_ATTEMPTS, MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS, RESERVED_EDGE_HANDLES, RESERVED_NODE_IDS, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, LOOP_BODY_HANDLE, LOOP_DONE_HANDLE, } from "./types.js";
+const NODE_KINDS = new Set([
+    "trigger",
+    "tool",
+    "filter",
+    "switch",
+    "loop",
+    "merge",
+    "set",
+    "wait",
+    "approval",
+    "code",
+    "workflow",
+]);
+const MERGE_STRATEGIES = new Set(["append", "first", "wait_all"]);
+const STEP_EFFECTS = new Set(["none", "external_read", "external_write"]);
+const STEP_MODES = new Set(["dry_run", "live", "smoke_test"]);
+// A condition tree is authored in a UI; anything deeper than this is either a
+// generator gone wrong or an attempt to make the linter recurse forever.
+const MAX_CONDITION_DEPTH = 12;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** Array.isArray narrows `unknown` to `any[]`; this keeps the elements `unknown`. */
+function asArray(value) {
+    return Array.isArray(value) ? value : null;
+}
+function isCompareOp(value) {
+    return typeof value === "string" && WORKFLOW_COMPARE_OPS.has(value);
+}
+function isUnaryCompareOp(value) {
+    return UNARY_COMPARE_OPS.has(value);
+}
+export function lintWorkflowGraphManifest(value, options = {}) {
+    const issues = [];
+    const add = (path, code, message) => issues.push({ path, code, message });
+    if (!isRecord(value)) {
+        add("$", "invalid_manifest", "Workflow graph manifest must be an object.");
+        return { ok: false, issues };
+    }
+    if (value.manifest_version !== WORKFLOW_GRAPH_MANIFEST_VERSION) {
+        add("$.manifest_version", "invalid_manifest_version", `Workflow graph manifest version must be ${WORKFLOW_GRAPH_MANIFEST_VERSION}.`);
+    }
+    if (value.compiler_version !== WORKFLOW_GRAPH_COMPILER_VERSION) {
+        add("$.compiler_version", "invalid_compiler_version", `Workflow graph compiler_version must be '${WORKFLOW_GRAPH_COMPILER_VERSION}'.`);
+    }
+    lintWorkflowMetadata(value.workflow, add);
+    if (value.trigger !== undefined)
+        validateTrigger(value.trigger, "$.trigger", add);
+    validateOptionalMaxCredits(value.max_credits, "$.max_credits", add);
+    if (!isNonEmptyString(value.source_hash)) {
+        add("$.source_hash", "missing_source_hash", "Manifest source_hash is required.");
+    }
+    const nodesSound = lintNodes(value.nodes, add, options);
+    const edgesSound = lintEdges(value.edges, value.nodes, add);
+    // Graph-level analysis dereferences every node and edge, so it only runs once
+    // the element shapes are known good. Reporting "unreachable" on a manifest
+    // whose nodes are half-formed would bury the real error under cascades.
+    if (nodesSound && edgesSound) {
+        lintGraphTopology(value, add);
+    }
+    return { ok: issues.length === 0, issues };
+}
+export function assertWorkflowGraphManifest(value, options = {}) {
+    const result = lintWorkflowGraphManifest(value, options);
+    if (result.ok)
+        return;
+    const first = result.issues[0];
+    throw new Error(first ? `${first.code}: ${first.message}` : "Invalid workflow graph manifest.");
+}
+// ---------------------------------------------------------------------------
+// Manifest metadata
+// ---------------------------------------------------------------------------
+function lintWorkflowMetadata(workflow, add) {
+    if (!isRecord(workflow)) {
+        add("$.workflow", "missing_workflow", "Workflow metadata is required.");
+        return;
+    }
+    if (!isNonEmptyString(workflow.id)) {
+        add("$.workflow.id", "invalid_workflow_id", "Workflow id is required.");
+    }
+    if (!isNonEmptyString(workflow.name)) {
+        add("$.workflow.name", "invalid_workflow_name", "Workflow name is required.");
+    }
+    if (workflow.status !== undefined
+        && workflow.status !== "active"
+        && workflow.status !== "disabled") {
+        add("$.workflow.status", "invalid_workflow_status", "Workflow status must be active or disabled.");
+    }
+}
+// ---------------------------------------------------------------------------
+// Nodes
+// ---------------------------------------------------------------------------
+/** Returns true when every node is shaped well enough for topology analysis. */
+function lintNodes(// skipcq: JS-R1005
+value, add, options) {
+    const nodes = asArray(value);
+    if (!nodes || nodes.length === 0) {
+        add("$.nodes", "missing_nodes", "At least one workflow node is required.");
+        return false;
+    }
+    const seenIds = new Set();
+    let triggerCount = 0;
+    let sound = true;
+    nodes.forEach((node, index) => {
+        const path = `$.nodes.${index}`;
+        if (!isRecord(node)) {
+            add(path, "invalid_node", "Workflow node must be an object.");
+            sound = false;
+            return;
+        }
+        if (!lintNodeIdentity(node, path, seenIds, add))
+            sound = false;
+        if (node.kind === "trigger")
+            triggerCount += 1;
+        if (typeof node.kind !== "string" || !NODE_KINDS.has(node.kind)) {
+            add(`${path}.kind`, "invalid_node_kind", `Node kind must be one of ${[...NODE_KINDS].join(", ")}.`);
+            return;
+        }
+        lintNodeByKind(node, path, add, options);
+    });
+    if (triggerCount === 0) {
+        add("$.nodes", "missing_trigger_node", "A workflow graph requires exactly one trigger node.");
+    }
+    else if (triggerCount > 1) {
+        add("$.nodes", "multiple_trigger_nodes", `A workflow graph must declare exactly one trigger node (found ${triggerCount}).`);
+    }
+    return sound;
+}
+function lintNodeIdentity(node, path, seenIds, add) {
+    let sound = true;
+    if (!isNonEmptyString(node.id)) {
+        add(`${path}.id`, "invalid_node_id", "Node id is required.");
+        sound = false;
+    }
+    else if (RESERVED_NODE_IDS.has(node.id)) {
+        // Node ids become keys on the run scope's `steps` object. "__proto__" and
+        // friends hit JavaScript's own object internals, so the node's output would
+        // be silently dropped and unreadable downstream while the run still reports
+        // success. Reject at authoring time instead.
+        add(`${path}.id`, "reserved_node_id", `Node id '${node.id}' is reserved (it collides with a JavaScript object key and would be dropped from node outputs). Choose another id.`);
+        sound = false;
+    }
+    else if (seenIds.has(node.id)) {
+        add(`${path}.id`, "duplicate_node_id", `Node id '${node.id}' is duplicated.`);
+    }
+    else {
+        seenIds.add(node.id);
+    }
+    if (!isNonEmptyString(node.name)) {
+        add(`${path}.name`, "invalid_node_name", "Node name is required.");
+    }
+    if (!isRecord(node.ui)
+        || typeof node.ui.x !== "number"
+        || typeof node.ui.y !== "number"
+        || !Number.isFinite(node.ui.x)
+        || !Number.isFinite(node.ui.y)) {
+        add(`${path}.ui`, "invalid_node_ui", "Node ui must be { x: number, y: number }.");
+    }
+    lintNodeRetry(node, path, add);
+    return sound;
+}
+/**
+ * A node's own retry budget.
+ *
+ * Bounded on both axes because both are a run's wall-clock: attempts multiply a
+ * provider call and the wait parks the run. Note what is NOT checked here —
+ * whether this node's effect may be retried at all. That decision belongs to the
+ * worker's isRetryableWorkflowStepError, which the budget is consulted after; a
+ * lint rule refusing `retry` on a live external write would only be a second,
+ * drifting opinion about the same safety rule.
+ */
+function lintNodeRetry(node, path, add) {
+    if (node.retry === undefined)
+        return;
+    if (!isRecord(node.retry)) {
+        add(`${path}.retry`, "invalid_node_retry", "Node retry must be { max_attempts: number, wait_seconds?: number }.");
+        return;
+    }
+    const { max_attempts: attempts, wait_seconds: wait } = node.retry;
+    if (!isPositiveInteger(attempts)) {
+        add(`${path}.retry.max_attempts`, "invalid_node_retry", "Retry max_attempts must be a positive integer.");
+    }
+    else if (attempts > MAX_WORKFLOW_NODE_RETRY_ATTEMPTS) {
+        add(`${path}.retry.max_attempts`, "invalid_node_retry", `Retry max_attempts cannot exceed ${MAX_WORKFLOW_NODE_RETRY_ATTEMPTS}.`);
+    }
+    if (wait === undefined)
+        return;
+    if (typeof wait !== "number" || !Number.isFinite(wait) || wait < 0) {
+        add(`${path}.retry.wait_seconds`, "invalid_node_retry", "Retry wait_seconds must be a non-negative number.");
+    }
+    else if (wait > MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS) {
+        add(`${path}.retry.wait_seconds`, "invalid_node_retry", `Retry wait_seconds cannot exceed ${MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS}.`);
+    }
+}
+function lintNodeByKind(// skipcq: JS-R1005
+node, path, add, options) {
+    switch (node.kind) {
+        case "trigger":
+            return;
+        case "tool":
+            lintToolNode(node, path, add, options);
+            return;
+        case "filter":
+            validateCondition(node.when, `${path}.when`, add);
+            return;
+        case "switch":
+            lintSwitchNode(node, path, add);
+            return;
+        case "loop":
+            lintLoopNode(node, path, add);
+            return;
+        case "merge":
+            if (typeof node.strategy !== "string" || !MERGE_STRATEGIES.has(node.strategy)) {
+                add(`${path}.strategy`, "invalid_merge_strategy", `Merge strategy must be one of ${[...MERGE_STRATEGIES].join(", ")}.`);
+            }
+            return;
+        case "set":
+            lintSetNode(node, path, add);
+            return;
+        case "wait":
+            lintWaitNode(node, path, add);
+            return;
+        case "approval":
+            lintApprovalNode(node, path, add);
+            return;
+        case "code":
+            // v2 `code` nodes run through the same sandbox as v1 transform steps, so
+            // they clear the same purity scan; every issue it raises is re-labelled to
+            // the v2 code so callers match on one code for "this source is not safe".
+            if (typeof node.run_source !== "string") {
+                add(`${path}.run_source`, "unsafe_code_source", "Code node run_source is required.");
+                return;
+            }
+            validatePureFunctionSource(node.run_source, `${path}.run_source`, (issuePath, _code, message) => add(issuePath, "unsafe_code_source", message));
+            return;
+        case "workflow":
+            if (!isNonEmptyString(node.workflow_id)) {
+                add(`${path}.workflow_id`, "invalid_workflow_ref", "Workflow node workflow_id is required.");
+            }
+            validateValueRefRecord(node.input, `${path}.input`, add);
+            // Authoring-time refusal, not just a runtime one. A sub-workflow needs its
+            // own durable run, lease, spend ceiling and cancellation semantics, none of
+            // which exist yet — so the worker rejects the node terminally. Without this
+            // rule a user could save the graph, arm a cron trigger on it, and discover
+            // the refusal at 03:00 on every delivery instead of at `workflows apply`.
+            // Remove BOTH refusals together when child runs ship.
+            add(`${path}.kind`, "unsupported_node_kind", "Sub-workflow nodes cannot run yet. Inline the child workflow's nodes for now.");
+            return;
+        default:
+            return;
+    }
+}
+function lintToolNode(node, path, add, options) {
+    if (!isNonEmptyString(node.tool)) {
+        add(`${path}.tool`, "missing_tool", "Tool node tool id is required.");
+    }
+    else if (isWorkflowToolRejected(node.tool)) {
+        add(`${path}.tool`, "unsupported_workflow_tool", `Tool '${node.tool}' is not allowed in workflow automations.`);
+    }
+    else if (options.isToolAllowed && !options.isToolAllowed(node.tool)) {
+        add(`${path}.tool`, "tool_not_allowed", `Tool '${node.tool}' is not available for workflow automations.`);
+    }
+    // Is the node actually filled in? Same injection contract as resolveToolEffect
+    // and for the same reason: the field list lives in the server tool registry,
+    // which the CLI and the browser bundle cannot carry. Without this the EDITOR
+    // refused an unconfigured node while apply accepted the identical manifest, and
+    // a CLI-authored one was never checked at all — a guarantee the GUI enforces
+    // alone is not a guarantee.
+    if (isNonEmptyString(node.tool) && options.resolveToolParamFields) {
+        const resolved = options.resolveToolParamFields(node.tool);
+        // Array.isArray does not narrow a `readonly T[]` union, so normalize once.
+        const bag = resolved == null
+            ? null
+            : Array.isArray(resolved)
+                ? { fields: resolved }
+                : resolved;
+        const fields = bag?.fields;
+        const closed = bag?.closed;
+        if (fields) {
+            const params = isRecord(node.params) ? node.params : {};
+            const shared = {
+                toolId: node.tool,
+                fields,
+                params,
+                ...(closed === undefined ? {} : { closed }),
+            };
+            // Its own code and its own sentence. Folding this into "still needs X" read
+            // as "oxygen_tables_list still needs 'limit' — oxygen_tables_list has no such
+            // input": the tool named twice, and "needs" saying the opposite of the truth.
+            for (const unknown of unknownToolParams(shared)) {
+                add(`${path}.params.${unknown}`, "unknown_tool_param", `${node.tool} has no input called '${unknown}'. Remove it or check the spelling.`);
+            }
+            for (const missing of missingToolParams(shared)) {
+                add(`${path}.params`, "incomplete_tool_params", `${node.tool} still needs ${missing}.`);
+            }
+        }
+    }
+    if (typeof node.effect !== "string" || !STEP_EFFECTS.has(node.effect)) {
+        add(`${path}.effect`, "invalid_step_effect", "Node effect is invalid.");
+    }
+    else if (typeof node.tool === "string" && node.tool.length > 0) {
+        // Shape alone is not enough: a node declaring a write as a read would pass
+        // the check above and then be refused by apply and the runtime, which both
+        // resolve the effect canonically. The v1 linter has always checked this;
+        // omitting it here would recreate the exact "lint approves, apply rejects"
+        // divergence one compiler version later.
+        // No resolver: skip, do not refuse. See the matching note in ../index.ts —
+        // the CLI compiles manifests locally and cannot classify effects, while apply
+        // and the runtime both refuse what they cannot classify.
+        const resolveEffect = options.resolveToolEffect;
+        if (resolveEffect) {
+            const canonicalEffect = resolveEffect(node.tool);
+            if (canonicalEffect !== null && node.effect !== canonicalEffect) {
+                add(`${path}.effect`, "tool_effect_mismatch", `Tool '${node.tool}' has canonical effect '${canonicalEffect}', not '${String(node.effect)}'.`);
+            }
+        }
+    }
+    if (node.mode !== undefined && (typeof node.mode !== "string" || !STEP_MODES.has(node.mode))) {
+        add(`${path}.mode`, "invalid_step_mode", "Node mode is invalid.");
+    }
+    validateOptionalMaxCredits(node.max_credits, `${path}.max_credits`, add);
+    validateValueRefRecord(node.params, `${path}.params`, add);
+}
+function lintSwitchNode(node, path, add) {
+    const cases = asArray(node.cases);
+    if (!cases || cases.length === 0) {
+        add(`${path}.cases`, "invalid_switch_case", "Switch node requires at least one case.");
+        return;
+    }
+    if (node.fallthrough !== undefined && typeof node.fallthrough !== "boolean") {
+        add(`${path}.fallthrough`, "invalid_switch_case", "Switch fallthrough must be a boolean.");
+    }
+    const seenCaseIds = new Set();
+    cases.forEach((entry, index) => {
+        const casePath = `${path}.cases.${index}`;
+        if (!isRecord(entry)) {
+            add(casePath, "invalid_switch_case", "Switch case must be an object.");
+            return;
+        }
+        if (!isNonEmptyString(entry.id)) {
+            add(`${casePath}.id`, "invalid_switch_case", "Switch case id is required.");
+        }
+        else if (RESERVED_EDGE_HANDLES.has(entry.id)) {
+            // A case id names the outgoing edge handle; colliding with a reserved
+            // handle would make the edge ambiguous between the case and the built-in.
+            add(`${casePath}.id`, "invalid_switch_case", `Switch case id '${entry.id}' is a reserved edge handle.`);
+        }
+        else if (seenCaseIds.has(entry.id)) {
+            add(`${casePath}.id`, "duplicate_switch_case_id", `Switch case id '${entry.id}' is duplicated.`);
+        }
+        else {
+            seenCaseIds.add(entry.id);
+        }
+        if (!isNonEmptyString(entry.label)) {
+            add(`${casePath}.label`, "invalid_switch_case", "Switch case label is required.");
+        }
+        validateCondition(entry.when, `${casePath}.when`, add);
+    });
+}
+function lintLoopNode(node, path, add) {
+    validateValueRef(node.over, `${path}.over`, add);
+    if (node.item_name !== undefined && !isNonEmptyString(node.item_name)) {
+        add(`${path}.item_name`, "invalid_value_ref", "Loop item_name must be a non-empty string.");
+    }
+    if (node.max_iterations !== undefined && !isPositiveInteger(node.max_iterations)) {
+        add(`${path}.max_iterations`, "invalid_loop_target", "Loop max_iterations must be a positive integer.");
+    }
+    else if (typeof node.max_iterations === "number"
+        && node.max_iterations > MAX_WORKFLOW_LOOP_ITERATIONS) {
+        // The interpreter clamps to the ceiling regardless, so accepting a larger
+        // bound would publish a number nothing honours: the usage estimator would
+        // price the run at the authored figure and refuse cron cadences over
+        // iterations that can never happen. Refusing here keeps the declared cap and
+        // the executed cap the same number.
+        add(`${path}.max_iterations`, "invalid_loop_target", `Loop max_iterations cannot exceed ${MAX_WORKFLOW_LOOP_ITERATIONS}.`);
+    }
+    if (node.concurrency !== undefined && !isPositiveInteger(node.concurrency)) {
+        add(`${path}.concurrency`, "invalid_loop_target", "Loop concurrency must be a positive integer.");
+    }
+}
+function lintSetNode(node, path, add) {
+    const fields = asArray(node.fields);
+    if (!fields || fields.length === 0) {
+        add(`${path}.fields`, "invalid_set_field", "Set node requires at least one field.");
+        return;
+    }
+    fields.forEach((field, index) => {
+        const fieldPath = `${path}.fields.${index}`;
+        if (!isRecord(field)) {
+            add(fieldPath, "invalid_set_field", "Set field must be an object.");
+            return;
+        }
+        if (!isNonEmptyString(field.key)) {
+            add(`${fieldPath}.key`, "invalid_set_field", "Set field key is required.");
+        }
+        else if (RESERVED_NODE_IDS.has(field.key)) {
+            add(`${fieldPath}.key`, "invalid_set_field", `Set field key '${field.key}' is reserved and would be dropped from the node output.`);
+        }
+        validateValueRef(field.value, `${fieldPath}.value`, add);
+    });
+}
+function lintApprovalNode(node, path, add) {
+    if (node.reason !== undefined)
+        validateValueRef(node.reason, `${path}.reason`, add);
+    if (node.request !== undefined)
+        validateValueRefRecord(node.request, `${path}.request`, add);
+}
+function lintWaitNode(node, path, add) {
+    const hasDuration = node.duration_seconds !== undefined;
+    const hasUntil = node.until !== undefined;
+    if (hasDuration === hasUntil) {
+        add(path, "invalid_wait", "Wait node requires exactly one of duration_seconds or until.");
+        return;
+    }
+    if (hasDuration) {
+        if (typeof node.duration_seconds !== "number"
+            || !Number.isFinite(node.duration_seconds)
+            || node.duration_seconds <= 0) {
+            add(`${path}.duration_seconds`, "invalid_wait", "Wait duration_seconds must be a positive number.");
+        }
+        return;
+    }
+    validateValueRef(node.until, `${path}.until`, add);
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+// ---------------------------------------------------------------------------
+// Edges
+// ---------------------------------------------------------------------------
+/** Returns true when every edge is shaped well enough for topology analysis. */
+function lintEdges(value, nodesValue, add) {
+    const edges = asArray(value);
+    if (!edges) {
+        add("$.edges", "invalid_edge", "Workflow edges must be an array.");
+        return false;
+    }
+    const nodes = indexNodesById(nodesValue);
+    const seenEdgeIds = new Set();
+    const seenConnections = new Set();
+    let sound = true;
+    edges.forEach((edge, index) => {
+        const path = `$.edges.${index}`;
+        if (!isRecord(edge)) {
+            add(path, "invalid_edge", "Workflow edge must be an object.");
+            sound = false;
+            return;
+        }
+        if (!isNonEmptyString(edge.id)) {
+            add(`${path}.id`, "invalid_edge", "Edge id is required.");
+            sound = false;
+        }
+        else if (seenEdgeIds.has(edge.id)) {
+            add(`${path}.id`, "duplicate_edge", `Edge id '${edge.id}' is duplicated.`);
+        }
+        else {
+            seenEdgeIds.add(edge.id);
+        }
+        const source = edge.source;
+        const target = edge.target;
+        if (!isNonEmptyString(source) || !isNonEmptyString(target)) {
+            add(path, "invalid_edge", "Edge source and target are required.");
+            sound = false;
+            return;
+        }
+        if (edge.source_handle !== undefined && !isNonEmptyString(edge.source_handle)) {
+            add(`${path}.source_handle`, "invalid_edge_handle", "Edge source_handle must be a string.");
+            return;
+        }
+        const connection = JSON.stringify([source, edge.source_handle ?? null, target]);
+        if (seenConnections.has(connection)) {
+            add(path, "duplicate_edge", `Edge from '${source}' to '${target}' is declared more than once.`);
+        }
+        else {
+            seenConnections.add(connection);
+        }
+        if (typeof edge.source_handle === "string") {
+            lintEdgeHandle({ source, target, handle: edge.source_handle, path, nodes }, add);
+        }
+    });
+    return sound;
+}
+function indexNodesById(value) {
+    const index = new Map();
+    for (const node of asArray(value) ?? []) {
+        // First declaration wins, matching topology.ts: duplicates are reported by
+        // lintNodes and must not change which node an edge is validated against.
+        if (isRecord(node) && isNonEmptyString(node.id) && !index.has(node.id))
+            index.set(node.id, node);
+    }
+    return index;
+}
+function lintEdgeHandle(input, add) {
+    const { handle, path } = input;
+    const sourceNode = input.nodes.get(input.source);
+    // Dangling source: reported once by lintGraphTopology, not again per handle.
+    if (!sourceNode)
+        return;
+    const sourceKind = sourceNode.kind;
+    if (handle === LOOP_BODY_HANDLE || handle === LOOP_DONE_HANDLE) {
+        if (sourceKind !== "loop") {
+            add(`${path}.source_handle`, "invalid_loop_target", `Handle '${handle}' is only valid on a loop node.`);
+        }
+        else if (handle === LOOP_BODY_HANDLE && input.source === input.target) {
+            add(`${path}.target`, "invalid_loop_target", "A loop's loop_body edge cannot target the loop node itself.");
+        }
+        return;
+    }
+    if (RESERVED_EDGE_HANDLES.has(handle))
+        return; // "error", valid on any node
+    if (sourceKind !== "switch") {
+        add(`${path}.source_handle`, "invalid_edge_handle", `Handle '${handle}' is only valid on a switch node (its case ids name its handles).`);
+        return;
+    }
+    const declaresCase = (asArray(sourceNode.cases) ?? []).some((entry) => isRecord(entry) && entry.id === handle);
+    if (!declaresCase) {
+        add(`${path}.source_handle`, "invalid_switch_case", `Edge handle '${handle}' does not name a case on switch node '${input.source}'.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Graph-level rules
+// ---------------------------------------------------------------------------
+function lintGraphTopology(graph, add) {
+    const edgeIndex = new Map();
+    graph.edges.forEach((edge, index) => {
+        if (!edgeIndex.has(edge.id))
+            edgeIndex.set(edge.id, index);
+    });
+    for (const edge of danglingEdges(graph)) {
+        add(`$.edges.${edgeIndex.get(edge.id) ?? 0}`, "dangling_edge", `Edge '${edge.id}' references a node that does not exist ('${edge.source}' → '${edge.target}').`);
+    }
+    for (const component of findIllegalCycles(graph)) {
+        add("$.edges", "illegal_cycle", `Nodes ${component.map((id) => `'${id}'`).join(", ")} form a cycle. Only a loop node's body may edge back to the loop.`);
+    }
+    // A loop that never enters its body is a loop in name only — it would run zero
+    // iterations and silently drop everything the author put after it.
+    graph.nodes.forEach((node, index) => {
+        if (node.kind !== "loop")
+            return;
+        const entersBody = graph.edges.some((edge) => edge.source === node.id && edge.source_handle === LOOP_BODY_HANDLE);
+        if (!entersBody) {
+            add(`$.nodes.${index}`, "invalid_loop_target", `Loop node '${node.id}' has no loop_body edge, so its body would never run.`);
+        }
+    });
+    // An approval inside a loop body asks once PER ITERATION: the interpreter keys
+    // approvals by step id, which inside a body is `<node_id>#<iteration_path>`, so
+    // a 200-row loop parks 200 times and needs 200 human decisions. Refused at
+    // authoring time rather than at 03:00 on the first delivery, the same way the
+    // unrunnable sub-workflow node is. Gate the batch instead: approve once before
+    // the loop, then iterate.
+    const approvalNodeIds = new Set(graph.nodes.filter((node) => node.kind === "approval").map((node) => node.id));
+    if (approvalNodeIds.size > 0) {
+        const bodies = graph.nodes
+            .filter((node) => node.kind === "loop")
+            .map((node) => ({ loopId: node.id, body: loopBodyNodeIds(graph, node.id) }));
+        graph.nodes.forEach((node, index) => {
+            if (!approvalNodeIds.has(node.id))
+                return;
+            const enclosing = bodies.find((entry) => entry.body.has(node.id));
+            if (!enclosing)
+                return;
+            add(`$.nodes.${index}`, "approval_inside_loop", `Approval node '${node.id}' sits inside loop '${enclosing.loopId}', which would request one decision per iteration. `
+                + "Move the approval before the loop so one decision covers the whole batch.");
+        });
+    }
+    const reachable = reachableNodeIds(graph);
+    graph.nodes.forEach((node, index) => {
+        if (reachable.has(node.id))
+            return;
+        add(`$.nodes.${index}`, "unreachable_node", `Node '${node.id}' cannot be reached from the trigger.`);
+    });
+}
+// ---------------------------------------------------------------------------
+// Value refs and conditions
+// ---------------------------------------------------------------------------
+function validateValueRefRecord(value, path, add) {
+    if (value === undefined) {
+        add(path, "invalid_value_ref", "Node bindings are required.");
+        return;
+    }
+    if (!isRecord(value)) {
+        add(path, "invalid_value_ref", "Node bindings must be an object of value refs.");
+        return;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        validateValueRef(entry, `${path}.${key}`, add);
+    }
+}
+function validateValueRef(value, path, add) {
+    if (!isRecord(value)) {
+        add(path, "invalid_value_ref", "Value ref must be an object.");
+        return;
+    }
+    switch (value.type) {
+        case "literal":
+            if (!("value" in value)) {
+                add(`${path}.value`, "invalid_value_ref", "Literal value ref requires a value.");
+                return;
+            }
+            // A structured literal may carry `{{ steps.x.output.y }}` tokens, which
+            // resolve at run time — so they are bindings and get the same path
+            // validation a `template` ref's tokens get. Without this the editor's one
+            // control that can express a per-row reference was also the one place a
+            // typo'd path failed silently, resolving to undefined mid-run.
+            //
+            // Only OUR tokens are checked: `{{column}}`, `{{RANDOM|a|b}}` and other
+            // foreign templating share the delimiters, travel inside these same
+            // parameters, and are none of the linter's business.
+            validateStructuredLiteralPaths(value.value, `${path}.value`, add);
+            return;
+        case "template":
+            if (typeof value.value !== "string") {
+                add(`${path}.value`, "invalid_value_ref", "Template value ref requires a string.");
+                return;
+            }
+            validateTemplatePaths(value.value, `${path}.value`, add);
+            return;
+        case "ref":
+            if (!isNonEmptyString(value.path)) {
+                add(`${path}.path`, "invalid_value_ref", "Ref value ref requires a path.");
+                return;
+            }
+            validateScopePath(value.path, `${path}.path`, add);
+            return;
+        case "formula":
+            if (!isNonEmptyString(value.expression)) {
+                add(`${path}.expression`, "invalid_value_ref", "Formula value ref requires an expression.");
+                return;
+            }
+            try {
+                // `paths: true` to match how the expression is EVALUATED. Without it the
+                // linter refused the exact formulas the runtime resolves — a graph binding
+                // `steps.enrich.output.email` failed at authoring time while being perfectly
+                // runnable, which is the worst of the two possible mismatches.
+                validateFormulaExpression(value.expression, { paths: true });
+            }
+            catch (error) {
+                add(`${path}.expression`, "invalid_formula", error instanceof Error ? error.message : "Formula expression is invalid.");
+            }
+            return;
+        case "context_profile":
+            if (value.path !== undefined)
+                validateOptionalRefPath(value.path, `${path}.path`, add);
+            return;
+        case "context_asset":
+            if (!isNonEmptyString(value.assetId)) {
+                add(`${path}.assetId`, "invalid_value_ref", "Context asset ref requires an assetId.");
+            }
+            if (value.path !== undefined)
+                validateOptionalRefPath(value.path, `${path}.path`, add);
+            return;
+        default:
+            add(`${path}.type`, "invalid_value_ref", "Value ref type is invalid.");
+    }
+}
+function validateScopePath(path, issuePath, add) {
+    const segments = parseScopePath(path);
+    if (!segments) {
+        add(issuePath, "invalid_value_ref", `Path '${path}' is not a valid scope path (it is malformed or reaches a reserved key).`);
+        return;
+    }
+    const root = segments[0] ?? "";
+    if (!SCOPE_PATH_ROOTS.has(root)) {
+        add(issuePath, "invalid_value_ref", `Path '${path}' must start with ${[...SCOPE_PATH_ROOTS].join(", ")}.`);
+    }
+}
+/** Paths inside a context value have no scope root — only syntax to check. */
+function validateOptionalRefPath(path, issuePath, add) {
+    if (!isNonEmptyString(path) || !parseScopePath(path)) {
+        add(issuePath, "invalid_value_ref", "Context path is malformed or reaches a reserved key.");
+    }
+}
+function validateTemplatePaths(template, issuePath, add) {
+    for (const match of template.matchAll(/\{\{([^{}]*)\}\}/g)) {
+        const path = (match[1] ?? "").trim();
+        // "{{}}" is literal text by design, so it is not a binding to validate.
+        if (path)
+            validateScopePath(path, issuePath, add);
+    }
+}
+/**
+ * Validate the scope tokens inside a structured literal, at any depth.
+ *
+ * Mirrors validateTemplatePaths, but walks objects and arrays and ignores a
+ * token that is not rooted at one of our scope roots — the same discriminator
+ * resolveTokensDeep uses, so what the linter checks is exactly what the
+ * evaluator will try to resolve. A top-level literal STRING is skipped for the
+ * same reason the evaluator skips it: `template` owns that shape.
+ *
+ * DELIBERATELY LESS STRICT THAN A TEMPLATE REF, and the asymmetry is not an
+ * oversight. Inside a `template` every token is ours by definition, so a bad
+ * root there is an error. Inside a structured literal a non-scope root is
+ * indistinguishable from `{{column}}` or `{{RANDOM|a|b}}` — Oxygen's own
+ * documented merge-tag syntax, which travels in exactly these parameters — so
+ * flagging it would refuse legitimate outbound copy. A misspelled root is
+ * therefore passed through verbatim rather than rejected; the evaluator does the
+ * same, so it reaches the provider as visible text instead of vanishing into an
+ * empty string. Guessing which of `{{lop.x}}` and `{{company}}` was meant to be
+ * ours is not something a linter can do correctly.
+ */
+function validateStructuredLiteralPaths(value, issuePath, add, depth = 0) {
+    if (depth > 12)
+        return;
+    if (typeof value === "string") {
+        // Depth 0 is the top-level literal string the evaluator leaves alone.
+        if (depth === 0)
+            return;
+        for (const match of value.matchAll(/\{\{([^{}]*)\}\}/g)) {
+            const path = (match[1] ?? "").trim();
+            if (!path)
+                continue;
+            const root = path.split(/[.[]/, 1)[0];
+            if (root !== undefined && SCOPE_PATH_ROOTS.has(root)) {
+                validateScopePath(path, issuePath, add);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            validateStructuredLiteralPaths(entry, issuePath, add, depth + 1);
+        return;
+    }
+    if (isRecord(value)) {
+        for (const entry of Object.values(value)) {
+            validateStructuredLiteralPaths(entry, issuePath, add, depth + 1);
+        }
+    }
+}
+function validateCondition(// skipcq: JS-R1005
+value, path, add, depth = 0) {
+    if (!isRecord(value)) {
+        add(path, "invalid_condition", "Condition must be an object.");
+        return;
+    }
+    if (depth > MAX_CONDITION_DEPTH) {
+        add(path, "invalid_condition", `Condition nesting exceeds ${MAX_CONDITION_DEPTH} levels.`);
+        return;
+    }
+    if (value.type === "group") {
+        if (value.op !== "all" && value.op !== "any") {
+            add(`${path}.op`, "invalid_condition", "Condition group op must be all or any.");
+        }
+        if (value.not !== undefined && typeof value.not !== "boolean") {
+            add(`${path}.not`, "invalid_condition", "Condition group not must be a boolean.");
+        }
+        if (!Array.isArray(value.children) || value.children.length === 0) {
+            add(`${path}.children`, "invalid_condition", "Condition group requires at least one child.");
+            return;
+        }
+        value.children.forEach((child, index) => {
+            validateCondition(child, `${path}.children.${index}`, add, depth + 1);
+        });
+        return;
+    }
+    if (value.type === "compare") {
+        validateValueRef(value.left, `${path}.left`, add);
+        if (!isCompareOp(value.op)) {
+            add(`${path}.op`, "invalid_condition", "Condition compare op is invalid.");
+            return;
+        }
+        if (isUnaryCompareOp(value.op)) {
+            if (value.right !== undefined) {
+                add(`${path}.right`, "invalid_condition", `Operator '${value.op}' takes no right operand.`);
+            }
+            return;
+        }
+        if (value.right === undefined) {
+            add(`${path}.right`, "invalid_condition", `Operator '${value.op}' requires a right operand.`);
+            return;
+        }
+        validateValueRef(value.right, `${path}.right`, add);
+        if (value.op === "matches")
+            validateMatchPattern(value.right, `${path}.right`, add);
+        return;
+    }
+    add(`${path}.type`, "invalid_condition", "Condition type must be group or compare.");
+}
+/**
+ * A literal `matches` pattern is checked at authoring time, so the author is told
+ * the pattern is unsupported instead of watching the condition quietly evaluate
+ * to false on every row. A computed pattern (template/ref/formula) is unknowable
+ * here and is guarded at run time by compileConditionPattern.
+ */
+function validateMatchPattern(right, path, add) {
+    if (!isRecord(right) || right.type !== "literal")
+        return;
+    if (typeof right.value !== "string") {
+        add(`${path}.value`, "invalid_condition", "matches requires a string pattern.");
+        return;
+    }
+    if (!compileConditionPattern(right.value)) {
+        add(`${path}.value`, "invalid_condition", "Regex pattern is invalid or unsupported (patterns are capped at 200 characters and may not use lookaround, backreferences, or nested quantifiers).");
+    }
+}