@oxygen-agent/cli 1.739.1 → 1.750.4

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

@@ -14,6 +14,69 @@
 //     only, and the segments that reach JavaScript object internals
 //     (__proto__ / constructor / prototype) are rejected outright.
 import { analyzeFormulaDependencies, evaluateFormulaInScope, formulaExpressionError, } from "@oxygen/formula";
+/** A deterministic authoring/data error; retrying the same revision cannot repair it. */
+export class WorkflowValueCoercionError extends Error {
+    coercion;
+    code = "workflow_value_coercion_failed";
+    constructor(coercion) {
+        super(`Mapped value could not be converted to ${coercion}.`);
+        this.coercion = coercion;
+        this.name = "WorkflowValueCoercionError";
+    }
+}
+/** A direct mapping named data the run does not carry; sending undefined is never intentional. */
+export class WorkflowValueRefUnresolvedError extends Error {
+    path;
+    code = "workflow_value_ref_unresolved";
+    constructor(path) {
+        super(`Mapped field '${path}' did not resolve in this run.`);
+        this.path = path;
+        this.name = "WorkflowValueRefUnresolvedError";
+    }
+}
+/** Apply one explicit scalar conversion without lossy truthiness or truncation. */
+export function coerceWorkflowValue(value, coercion) {
+    switch (coercion) {
+        case "string":
+            if (typeof value === "string")
+                return value;
+            if (typeof value === "number" && Number.isFinite(value))
+                return String(value);
+            if (typeof value === "boolean")
+                return value ? "true" : "false";
+            break;
+        case "number":
+            if (typeof value === "number" && Number.isFinite(value))
+                return value;
+            if (typeof value === "string" && value.trim() !== "") {
+                const parsed = Number(value);
+                if (Number.isFinite(parsed))
+                    return parsed;
+            }
+            break;
+        case "integer":
+            if (typeof value === "number" && Number.isInteger(value))
+                return value;
+            if (typeof value === "string" && value.trim() !== "") {
+                const parsed = Number(value);
+                if (Number.isInteger(parsed))
+                    return parsed;
+            }
+            break;
+        case "boolean":
+            if (typeof value === "boolean")
+                return value;
+            if (typeof value === "string") {
+                const normalized = value.trim().toLowerCase();
+                if (normalized === "true")
+                    return true;
+                if (normalized === "false")
+                    return false;
+            }
+            break;
+    }
+    throw new WorkflowValueCoercionError(coercion);
+}
 /** The roots a `ref` path may start from. Anything else is not a scope path. */
 export const SCOPE_PATH_ROOTS = new Set(["trigger", "steps", "loop"]);
 /**
@@ -68,71 +131,123 @@ export function parseScopePath(path) {
     if (!trimmed || trimmed.startsWith(".") || trimmed.endsWith("."))
         return null;
     const segments = [];
-    let current = "";
     let index = 0;
-    const flush = () => {
-        const segment = current.trim();
-        current = "";
-        if (!segment)
+    const push = (segment, allowEmpty = false) => {
+        if ((!allowEmpty && !segment) || BLOCKED_PATH_SEGMENTS.has(segment))
             return false;
         segments.push(segment);
         return true;
     };
+    const readBare = () => {
+        const start = index;
+        while (index < trimmed.length) {
+            const char = trimmed[index];
+            if (char === "." || char === "[")
+                break;
+            if (char === "]")
+                return false;
+            index += 1;
+        }
+        const raw = trimmed.slice(start, index);
+        return raw === raw.trim() && push(raw);
+    };
+    if (!readBare())
+        return null;
     while (index < trimmed.length) {
-        const char = trimmed[index] ?? "";
+        const char = trimmed[index];
         if (char === ".") {
-            if (!flush())
-                return null;
             index += 1;
+            if (index >= trimmed.length || trimmed[index] === "." || trimmed[index] === "[")
+                return null;
+            if (!readBare())
+                return null;
             continue;
         }
-        if (char === "[") {
-            // An index may follow a key ("items[0]") or another index ("matrix[0][1]"),
-            // but never open the expression ("[0].x" has no root).
-            if (current.trim()) {
-                if (!flush())
+        if (char !== "[")
+            return null;
+        index += 1;
+        while (trimmed[index] === " ")
+            index += 1;
+        let segment = null;
+        if (trimmed[index] === "\"") {
+            const start = index;
+            index += 1;
+            let escaped = false;
+            let closed = false;
+            while (index < trimmed.length) {
+                const next = trimmed[index] ?? "";
+                if (escaped)
+                    escaped = false;
+                else if (next === "\\")
+                    escaped = true;
+                else if (next === "\"") {
+                    index += 1;
+                    closed = true;
+                    break;
+                }
+                index += 1;
+            }
+            if (!closed)
+                return null;
+            try {
+                const decoded = JSON.parse(trimmed.slice(start, index));
+                if (typeof decoded !== "string")
                     return null;
+                segment = decoded;
             }
-            else if (segments.length === 0) {
+            catch {
                 return null;
             }
-            const close = trimmed.indexOf("]", index);
-            if (close < 0)
+        }
+        else {
+            const start = index;
+            while (index < trimmed.length && trimmed[index] !== "]")
+                index += 1;
+            const numeric = trimmed.slice(start, index).trim();
+            if (!/^(0|[1-9]\d*)$/.test(numeric))
                 return null;
-            const inner = trimmed.slice(index + 1, close).trim();
-            const quoted = readQuotedSegment(inner);
-            if (quoted !== null)
-                segments.push(quoted);
-            else if (/^\d+$/.test(inner))
-                segments.push(inner);
-            else
+            const parsed = Number(numeric);
+            // ECMAScript array indices stop before 2^32-1. Larger numeric object keys
+            // remain addressable through JSON-quoted property syntax.
+            if (!Number.isSafeInteger(parsed) || parsed >= 0xFFFF_FFFF)
                 return null;
-            index = close + 1;
-            if (trimmed[index] === ".")
-                index += 1;
-            continue;
+            segment = numeric;
         }
-        if (char === "]")
+        while (trimmed[index] === " ")
+            index += 1;
+        if (trimmed[index] !== "]" || segment === null || !push(segment, true))
             return null;
-        current += char;
         index += 1;
+        // Prevent adjacency such as `a[0]b`, which the old parser accidentally
+        // treated as another dotted segment.
+        if (index < trimmed.length && trimmed[index] !== "." && trimmed[index] !== "[")
+            return null;
     }
-    if (current.trim() && !flush())
-        return null;
     if (segments.length === 0)
         return null;
-    if (segments.some((segment) => BLOCKED_PATH_SEGMENTS.has(segment)))
-        return null;
     return segments;
 }
-function readQuotedSegment(inner) {
-    if (inner.length < 2)
-        return null;
-    const quote = inner[0];
-    if ((quote !== "\"" && quote !== "'") || !inner.endsWith(quote))
+/** Canonical path formatter: dots for simple keys, JSON brackets for every other key. */
+export function formatScopePath(segments) {
+    const [root, ...rest] = segments;
+    if (!root || /[.\[\]]/.test(root) || root !== root.trim() || BLOCKED_PATH_SEGMENTS.has(root)) {
         return null;
-    const value = inner.slice(1, -1);
-    return value.length > 0 ? value : null;
+    }
+    let path = root;
+    for (const segment of rest) {
+        if (BLOCKED_PATH_SEGMENTS.has(segment))
+            return null;
+        if (/^(0|[1-9]\d*)$/.test(segment) && Number(segment) < 0xFFFF_FFFF) {
+            path += `[${segment}]`;
+        }
+        else if (/^[A-Za-z_$][A-Za-z0-9_$-]*$/.test(segment)) {
+            path += `.${segment}`;
+        }
+        else {
+            path += `[${JSON.stringify(segment)}]`;
+        }
+    }
+    return path;
 }
 /** Read one segment off a container. Own properties only; never throws. */
 function readSegment(container, segment) {
@@ -308,8 +423,12 @@ export function resolveValueRef(ref, scope) {
                 : ref.value;
         case "template":
             return renderTemplate(ref.value, scope);
-        case "ref":
-            return resolvePath(ref.path, scope);
+        case "ref": {
+            const resolved = resolvePath(ref.path, scope);
+            return ref.coerce === undefined
+                ? resolved
+                : coerceWorkflowValue(resolved, ref.coerce);
+        }
         case "formula":
             return evaluateFormulaInScope(ref.expression, formulaScopeFor(scope), { paths: true });
         case "context_profile":
@@ -322,6 +441,73 @@ export function resolveValueRef(ref, scope) {
         }
     }
 }
+/**
+ * Resolve a binding that is about to cross an execution boundary.
+ *
+ * Conditions and optional control-flow refs deliberately keep total lookup
+ * semantics: a missing path is `undefined`, so `is_empty` remains useful. Tool
+ * requests are different — silently handing `undefined` to a provider makes a
+ * stale mapping look like a provider bug. Call this stricter adapter at that
+ * boundary so the failure names the mapped path before any provider executes.
+ */
+export function resolveRequiredValueRef(ref, scope) {
+    const missingToken = firstMissingScopeToken(ref, scope);
+    if (missingToken !== null)
+        throw new WorkflowValueRefUnresolvedError(missingToken);
+    const resolved = resolveValueRef(ref, scope);
+    if (resolved === undefined) {
+        const path = ref.type === "ref"
+            ? ref.path
+            : ref.type === "context_profile"
+                ? `company_profile${ref.path ? `.${ref.path}` : ""}`
+                : ref.type === "context_asset"
+                    ? `knowledge.${ref.assetId}${ref.path ? `.${ref.path}` : ""}`
+                    : "computed mapping";
+        throw new WorkflowValueRefUnresolvedError(path);
+    }
+    return resolved;
+}
+/** Find the first Oxygen-owned token that the current run scope cannot satisfy. */
+function firstMissingScopeToken(ref, scope) {
+    if (ref.type === "ref")
+        return resolvePath(ref.path, scope) === undefined ? ref.path : null;
+    if (ref.type === "template")
+        return firstMissingTokenInValue(ref.value, scope, 0, true);
+    if (ref.type === "literal" && isStructured(ref.value)) {
+        return firstMissingTokenInValue(ref.value, scope, 0, false);
+    }
+    return null;
+}
+function firstMissingTokenInValue(value, scope, depth, everyTokenIsOurs) {
+    if (depth > 12)
+        return null;
+    if (typeof value === "string") {
+        for (const match of value.matchAll(/\{\{([^{}]*)\}\}/g)) {
+            const path = (match[1] ?? "").trim();
+            if (!path || (!everyTokenIsOurs && !isScopeToken(path)))
+                continue;
+            if (resolvePath(path, scope) === undefined)
+                return path;
+        }
+        return null;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const missing = firstMissingTokenInValue(entry, scope, depth + 1, everyTokenIsOurs);
+            if (missing !== null)
+                return missing;
+        }
+        return null;
+    }
+    if (isStructured(value)) {
+        for (const entry of Object.values(value)) {
+            const missing = firstMissingTokenInValue(entry, scope, depth + 1, everyTokenIsOurs);
+            if (missing !== null)
+                return missing;
+        }
+    }
+    return null;
+}
 /**
  * Bind the formula language's identifiers to the run scope.
  *
@@ -643,6 +829,85 @@ export function referencedNodeIds(ref) {
     collectNodeIds(ref, ids);
     return [...new Set(ids)];
 }
+/** Exact rooted scope paths a ref/condition can read, excluding ambiguous bare formula names. */
+export function referencedScopePaths(ref) {
+    const paths = [];
+    collectScopePaths(ref, paths, 0);
+    return [...new Set(paths)];
+}
+function collectScopePaths(entry, into, depth) {
+    if (depth > 12)
+        return;
+    switch (entry.type) {
+        case "group":
+            for (const child of entry.children)
+                collectScopePaths(child, into, depth + 1);
+            return;
+        case "compare":
+            collectScopePaths(entry.left, into, depth + 1);
+            if (entry.right !== undefined)
+                collectScopePaths(entry.right, into, depth + 1);
+            return;
+        case "ref":
+            if (isRootedScopePath(entry.path))
+                into.push(entry.path);
+            return;
+        case "template":
+            collectTemplateScopePaths(entry.value, into);
+            return;
+        case "literal":
+            if (isStructured(entry.value))
+                collectStructuredScopePaths(entry.value, into, depth + 1);
+            return;
+        case "formula":
+            try {
+                for (const identifier of analyzeFormulaDependencies(entry.expression, { paths: true }).identifiers) {
+                    if ((identifier.includes(".") || identifier.includes("[")) && isRootedScopePath(identifier)) {
+                        into.push(identifier);
+                    }
+                }
+            }
+            catch {
+                // Syntax validation owns the parse error; it has no reliable paths.
+            }
+            return;
+        default:
+            return;
+    }
+}
+function isRootedScopePath(path) {
+    const segments = parseScopePath(path);
+    return segments !== null && SCOPE_PATH_ROOTS.has(segments[0] ?? "");
+}
+function collectTemplateScopePaths(value, into) {
+    for (const match of value.matchAll(/\{\{([^{}]*)\}\}/g)) {
+        const path = (match[1] ?? "").trim();
+        if (path && isRootedScopePath(path))
+            into.push(path);
+    }
+}
+function collectStructuredScopePaths(value, into, depth) {
+    if (depth > 12)
+        return;
+    if (typeof value === "string") {
+        for (const match of value.matchAll(/\{\{([^{}]*)\}\}/g)) {
+            const path = (match[1] ?? "").trim();
+            if (isScopeToken(path) && isRootedScopePath(path))
+                into.push(path);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectStructuredScopePaths(entry, into, depth + 1);
+        return;
+    }
+    if (isStructured(value)) {
+        for (const entry of Object.values(value)) {
+            collectStructuredScopePaths(entry, into, depth + 1);
+        }
+    }
+}
 function collectNodeIds(entry, into) {
     switch (entry.type) {
         case "group":

package/node_modules/@oxygen/workflows/dist/graph/index.d.ts

@@ -18,3 +18,4 @@ export * from "./expression.js";
 export * from "./params.js";
 export * from "./remap.js";
 export * from "./manifest-schema.js";
+export * from "./mapping.js";

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

@@ -18,3 +18,4 @@ export * from "./expression.js";
 export * from "./params.js";
 export * from "./remap.js";
 export * from "./manifest-schema.js";
+export * from "./mapping.js";

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

@@ -9,10 +9,10 @@
 import * as vm from "node:vm";
 import { validateFormulaExpression } from "@oxygen/formula";
 import { isWorkflowToolRejected, lintRecipeManifest, lintWorkflowCodeSourceSafety, validateOptionalMaxCredits, validatePureFunctionSource, validateTrigger, } from "../index.js";
-import { UNARY_COMPARE_OPS, WORKFLOW_COMPARE_OPS, compileConditionPattern, parseScopePath, SCOPE_PATH_ROOTS, } from "./expression.js";
+import { UNARY_COMPARE_OPS, WORKFLOW_COMPARE_OPS, compileConditionPattern, parseScopePath, referencedScopePaths, SCOPE_PATH_ROOTS, } from "./expression.js";
 import { missingToolParams, unknownToolParams } from "./params.js";
-import { danglingEdges, findIllegalCycles, loopBodyNodeIds, reachableNodeIds, workflowCodeSandboxInvocationUpperBound, } 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, isWorkflowCodeFieldName, WORKFLOW_CODE_V1_LANGUAGE, WORKFLOW_CODE_V1_MAX_INPUT_BYTES, WORKFLOW_CODE_V1_MAX_INPUTS, WORKFLOW_CODE_V1_MAX_OUTPUT_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_DEPTH, WORKFLOW_CODE_V1_MAX_SCHEMA_NODES, WORKFLOW_CODE_V1_MAX_SCHEMA_PROPERTIES, WORKFLOW_CODE_V1_MAX_SANDBOX_INVOCATIONS_PER_RUN, WORKFLOW_CODE_V1_MAX_SOURCE_BYTES, WORKFLOW_CODE_V1_MAX_TIMEOUT_MS, WORKFLOW_CODE_V1_MIN_INPUT_BYTES, WORKFLOW_CODE_V1_MIN_OUTPUT_BYTES, WORKFLOW_CODE_V1_MIN_TIMEOUT_MS, WORKFLOW_CODE_V1_RUNTIME, WORKFLOW_CODE_V1_VERSION, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, LOOP_BODY_HANDLE, LOOP_DONE_HANDLE, } from "./types.js";
+import { danglingEdges, dominatingNodeIds, findIllegalCycles, loopBodyNodeIds, reachableNodeIds, workflowCodeSandboxInvocationUpperBound, } 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, isWorkflowCodeFieldName, WORKFLOW_CODE_V1_LANGUAGE, WORKFLOW_CODE_V1_MAX_INPUT_BYTES, WORKFLOW_CODE_V1_MAX_INPUTS, WORKFLOW_CODE_V1_MAX_OUTPUT_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_DEPTH, WORKFLOW_CODE_V1_MAX_SCHEMA_NODES, WORKFLOW_CODE_V1_MAX_SCHEMA_PROPERTIES, WORKFLOW_CODE_V1_MAX_SANDBOX_INVOCATIONS_PER_RUN, WORKFLOW_CODE_V1_MAX_SOURCE_BYTES, WORKFLOW_CODE_V1_MAX_TIMEOUT_MS, WORKFLOW_CODE_V1_MIN_INPUT_BYTES, WORKFLOW_CODE_V1_MIN_OUTPUT_BYTES, WORKFLOW_CODE_V1_MIN_TIMEOUT_MS, WORKFLOW_CODE_V1_RUNTIME, WORKFLOW_CODE_V1_VERSION, WORKFLOW_VALUE_COERCIONS, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, LOOP_BODY_HANDLE, LOOP_DONE_HANDLE, } from "./types.js";
 const NODE_KINDS = new Set([
     "trigger",
     "tool",
@@ -125,7 +125,12 @@ export function lintWorkflowGraphManifest(value, options = {}) {
     // 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);
+        const graph = value;
+        // Availability dereferences typed ref-bearing fields. Run it only once the
+        // focused validators found no malformed node payload to cascade through.
+        if (issues.length === 0)
+            lintGraphReferenceAvailability(graph, add);
+        lintGraphTopology(graph, add);
     }
     return { ok: issues.length === 0, issues };
 }
@@ -265,15 +270,16 @@ function lintNodeIdentity(node, path, seenIds, add) {
  * 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.
+ * provider call and the wait parks the run. This setting can only NARROW the
+ * run's retry policy; it never grants retry authority. Tool/approval-specific
+ * rules below reject configurations the worker categorically cannot honour.
  */
 function lintNodeRetry(node, path, add) {
     if (node.retry === undefined)
         return;
+    if (node.continue_on_error === true) {
+        add(path, "ambiguous_node_resilience", "A node cannot combine continue_on_error with a retry limit. Choose one failure policy.");
+    }
     if (!isRecord(node.retry)) {
         add(`${path}.retry`, "invalid_node_retry", "Node retry must be { max_attempts: number, wait_seconds?: number }.");
         return;
@@ -769,7 +775,8 @@ function lintToolNode(node, path, add, scope, options) {
                 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}.`);
+                const exactField = fields.find((field) => (field.title ?? field.name) === missing);
+                add(exactField ? `${path}.params.${exactField.name}` : `${path}.params`, "incomplete_tool_params", `${node.tool} still needs ${missing}.`);
             }
         }
     }
@@ -796,6 +803,12 @@ function lintToolNode(node, path, add, scope, options) {
     if (node.mode !== undefined && (typeof node.mode !== "string" || !STEP_MODES.has(node.mode))) {
         add(`${path}.mode`, "invalid_step_mode", "Node mode is invalid.");
     }
+    else if (node.mode !== undefined && (node.effect !== "external_write" || node.mode !== "dry_run")) {
+        add(`${path}.mode`, "unsupported_step_mode", "A tool-node mode is only supported as 'dry_run' on an external write.");
+    }
+    if (node.effect === "external_write" && node.retry !== undefined) {
+        add(`${path}.retry`, "unsafe_external_write_retry", "External writes cannot have a node retry policy because an ambiguous failure may already have landed.");
+    }
     if (node.connection_id !== undefined && !isNonEmptyString(node.connection_id)) {
         add(`${path}.connection_id`, "invalid_connection_id", "Tool node connection_id must be a non-empty string.");
     }
@@ -896,6 +909,15 @@ function lintSetNode(node, path, add, scope) {
     });
 }
 function lintApprovalNode(node, path, add, scope) {
+    if (node.disabled === true) {
+        add(`${path}.disabled`, "unsafe_approval_behavior", "An approval gate cannot be skipped. Remove the node explicitly if the gate is no longer required.");
+    }
+    if (node.continue_on_error === true) {
+        add(`${path}.continue_on_error`, "unsafe_approval_behavior", "An approval gate cannot continue after rejection or expiry.");
+    }
+    if (node.retry !== undefined) {
+        add(`${path}.retry`, "unsafe_approval_behavior", "An approval gate cannot use a node retry policy.");
+    }
     // A blank `reason` is deliberately NOT refused here. It leaves the approver
     // guessing, but it is legal and every gate saved to date is missing one — so
     // the nudge lives in the editor's warning layer (graphWarnings in
@@ -1019,9 +1041,116 @@ function lintEdgeHandle(input, add) {
         add(`${path}.source_handle`, "invalid_switch_case", `Edge handle '${handle}' does not name a case on switch node '${input.source}'.`);
     }
 }
-// ---------------------------------------------------------------------------
-// Graph-level rules
-// ---------------------------------------------------------------------------
+function conditionValueRefs(condition, path) {
+    if (condition.type === "group") {
+        if (!Array.isArray(condition.children))
+            return [];
+        return condition.children.flatMap((child, index) => (conditionValueRefs(child, `${path}.children.${index}`)));
+    }
+    return [
+        { ref: condition.left, path: `${path}.left` },
+        ...(condition.right === undefined ? [] : [{ ref: condition.right, path: `${path}.right` }]),
+    ];
+}
+/** Every executable value binding on one structurally valid node. */
+function graphNodeValueRefs(node, path) {
+    switch (node.kind) {
+        case "tool":
+            return Object.entries(node.params).map(([name, ref]) => ({
+                ref,
+                path: `${path}.params.${name}`,
+            }));
+        case "filter":
+            return conditionValueRefs(node.when, `${path}.when`);
+        case "switch":
+            return node.cases.flatMap((branch, index) => (conditionValueRefs(branch.when, `${path}.cases.${index}.when`)));
+        case "loop":
+            return [{ ref: node.over, path: `${path}.over` }];
+        case "set":
+            return node.fields.map((field, index) => ({
+                ref: field.value,
+                path: `${path}.fields.${index}.value`,
+            }));
+        case "wait":
+            return node.until === undefined ? [] : [{ ref: node.until, path: `${path}.until` }];
+        case "approval":
+            return [
+                ...(node.reason === undefined ? [] : [{ ref: node.reason, path: `${path}.reason` }]),
+                ...Object.entries(node.request ?? {}).map(([name, ref]) => ({
+                    ref,
+                    path: `${path}.request.${name}`,
+                })),
+            ];
+        case "code":
+            if (node.code) {
+                return Object.entries(node.code.inputs).map(([name, ref]) => ({
+                    ref,
+                    path: `${path}.code.inputs.${name}`,
+                }));
+            }
+            return Object.entries(node.configuration ?? {}).map(([name, ref]) => ({
+                ref,
+                path: `${path}.configuration.${name}`,
+            }));
+        case "workflow":
+            return Object.entries(node.input).map(([name, ref]) => ({
+                ref,
+                path: `${path}.input.${name}`,
+            }));
+        default:
+            return [];
+    }
+}
+/**
+ * Ref availability is a graph invariant, not picker advice.
+ *
+ * A `steps.x` source must dominate its consumer and must not be disabled. A
+ * `loop.x.item` source exists only inside that loop's body. This rejects the
+ * two manifests that used to save successfully and then fail only on some
+ * deliveries: a downstream/conditional branch ref and a post-loop item ref.
+ */
+function lintGraphReferenceAvailability(graph, add) {
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    const reachable = reachableNodeIds(graph);
+    const loopBodies = new Map(graph.nodes
+        .filter((node) => node.kind === "loop")
+        .map((node) => [node.id, loopBodyNodeIds(graph, node.id)]));
+    graph.nodes.forEach((node, index) => {
+        // Unwired draft nodes already get one actionable topology issue. Their
+        // internal ordering becomes meaningful only after the author connects them.
+        if (!reachable.has(node.id))
+            return;
+        const dominators = dominatingNodeIds(graph, node.id);
+        dominators.delete(node.id);
+        for (const located of graphNodeValueRefs(node, `$.nodes.${index}`)) {
+            for (const scopePath of referencedScopePaths(located.ref)) {
+                const segments = parseScopePath(scopePath);
+                const root = segments?.[0];
+                const sourceId = segments?.[1];
+                if (!sourceId || (root !== "steps" && root !== "loop"))
+                    continue;
+                const source = nodes.get(sourceId);
+                if (!source)
+                    continue; // Unknown ids are reported by validateScopeNodeId.
+                if (root === "loop") {
+                    if (source.kind !== "loop")
+                        continue; // The focused ref validator reports this.
+                    if (!(loopBodies.get(sourceId)?.has(node.id) ?? false)) {
+                        add(located.path, "unavailable_loop_ref", `Path '${scopePath}' reads loop '${sourceId}' outside its body, where no current item exists.`);
+                    }
+                    continue;
+                }
+                if (source.disabled === true) {
+                    add(located.path, "disabled_node_ref", `Path '${scopePath}' reads disabled node '${sourceId}', which writes no output.`);
+                    continue;
+                }
+                if (!dominators.has(sourceId)) {
+                    add(located.path, "unavailable_node_ref", `Path '${scopePath}' reads node '${sourceId}', but that node is not guaranteed to run before '${node.id}'.`);
+                }
+            }
+        }
+    });
+}
 function lintGraphTopology(graph, add) {
     const edgeIndex = new Map();
     graph.edges.forEach((edge, index) => {
@@ -1099,6 +1228,9 @@ value, path, add, scope) {
         add(path, "invalid_value_ref", "Value ref must be an object.");
         return;
     }
+    if (value.coerce !== undefined && value.type !== "ref") {
+        add(`${path}.coerce`, "invalid_value_coercion", "Only a direct ref mapping may declare a coercion.");
+    }
     switch (value.type) {
         case "literal":
             if (!("value" in value)) {
@@ -1128,6 +1260,10 @@ value, path, add, scope) {
                 add(`${path}.path`, "invalid_value_ref", "Ref value ref requires a path.");
                 return;
             }
+            if (value.coerce !== undefined
+                && !WORKFLOW_VALUE_COERCIONS.includes(value.coerce)) {
+                add(`${path}.coerce`, "invalid_value_coercion", `Ref coercion must be one of ${WORKFLOW_VALUE_COERCIONS.join(", ")}.`);
+            }
             validateScopePath(value.path, `${path}.path`, add, scope);
             return;
         case "formula":
@@ -1192,12 +1328,10 @@ function validateScopePath(path, issuePath, add, scope) {
  * is strictly worse than the silence this rule removes. The id is the part that
  * is always knowable, and it is where a typo is unrecoverable.
  *
- * Upstream-ness is deliberately NOT checked either. A ref to a node that has not
- * run resolves to `undefined` just as surely, but "has run" is not a static
- * property of the graph: a body node's outputs survive its loop under a keyed
- * step id, a `fallthrough` switch runs several branches, and an author normally
- * configures a node before wiring it in. Every one of those is a legitimate
- * graph that a reachability rule would refuse.
+ * Availability is checked separately after nodes and edges are structurally
+ * sound. That graph-level pass uses dominators (not mere ancestry), so it can
+ * reject disabled/downstream/conditional sources without guessing here while a
+ * half-authored edge list is still being validated.
  */
 function validateScopeNodeId(path, segments, issuePath, add, scope) {
     if (scope.validateNodeIds === false)