@flowget/graph-validation 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@flowget/graph-validation` — the single source of static workflow-graph
+ * validation logic, shared by the builder (design-time, pre-submit) and the
+ * worker (host-side, pre-flight) so their verdicts are EQUAL BY CONSTRUCTION.
+ *
+ * Pure, isomorphic, zero-runtime-dependency (peer `@flowget/types` only). No
+ * `zod`, no `react`, no Node built-ins, no `Date` / `Math.random` — the
+ * identical bundle runs in the browser and host-side.
+ *
+ * Primary entry point: {@link validateGraphStatic}. The grammar classifier,
+ * value-type lattice, reachability walker, and coherence comparator are all
+ * exported standalone so consumers (and the engine, which will adopt the
+ * classifier) can compose them directly.
+ */
+export { validateGraphStatic } from "./validate-graph.js";
+export { ISSUE_CODES, type IssueCode, type ValidationIssue, type ValidationSeverity, } from "./issues.js";
+export { type CatalogIndex, type CatalogNode, indexCatalog, resolveNodeOutputFields, resolveNodeTriggerPayload, } from "./catalog.js";
+export { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasForbiddenPathToken, hasTemplateExpression, isReservedNamespace, isWholeStringTemplate, MAX_TEMPLATE_LENGTH, parseTemplate, parseTemplateExpression, RESERVED_NAMESPACES, templateExpressions, } from "./template-ast.js";
+export { isAssignable, isConcreteScalar, isWildcardValueType, jsValueType, } from "./value-type.js";
+export { buildReversedAdjacency, collectUpstream, collectUpstreamFrom, } from "./reachability.js";
+export { compareFieldCoherence, type CoherenceMismatch, type CoherenceMismatchKind, type SchemaFieldProjection, type SchemaProjection, } from "./coherence.js";

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@flowget/graph-validation` — the single source of static workflow-graph
+ * validation logic, shared by the builder (design-time, pre-submit) and the
+ * worker (host-side, pre-flight) so their verdicts are EQUAL BY CONSTRUCTION.
+ *
+ * Pure, isomorphic, zero-runtime-dependency (peer `@flowget/types` only). No
+ * `zod`, no `react`, no Node built-ins, no `Date` / `Math.random` — the
+ * identical bundle runs in the browser and host-side.
+ *
+ * Primary entry point: {@link validateGraphStatic}. The grammar classifier,
+ * value-type lattice, reachability walker, and coherence comparator are all
+ * exported standalone so consumers (and the engine, which will adopt the
+ * classifier) can compose them directly.
+ */
+// ── Primary aggregator ──────────────────────────────────────
+export { validateGraphStatic } from "./validate-graph.js";
+// ── Public output contract ──────────────────────────────────
+export { ISSUE_CODES, } from "./issues.js";
+// ── Input interface (catalog + output resolution) ───────────
+export { indexCatalog, resolveNodeOutputFields, resolveNodeTriggerPayload, } from "./catalog.js";
+// ── Template-grammar classifier → @flowget/types TemplateAst ─
+export { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasForbiddenPathToken, hasTemplateExpression, isReservedNamespace, isWholeStringTemplate, MAX_TEMPLATE_LENGTH, parseTemplate, parseTemplateExpression, RESERVED_NAMESPACES, templateExpressions, } from "./template-ast.js";
+// ── Coarse value-type lattice ───────────────────────────────
+export { isAssignable, isConcreteScalar, isWildcardValueType, jsValueType, } from "./value-type.js";
+// ── Reachability ────────────────────────────────────────────
+export { buildReversedAdjacency, collectUpstream, collectUpstreamFrom, } from "./reachability.js";
+// ── node.json ↔ schema coherence (worker boot-coherence) ────
+export { compareFieldCoherence, } from "./coherence.js";

package/dist/issues.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The package's PUBLIC OUTPUT contract — {@link ValidationIssue} — plus the
+ * stable machine {@link ISSUE_CODES} and a deterministic id-assigning
+ * collector.
+ *
+ * The shape mirrors the builder's existing `ValidationIssue`
+ * (`id`/`severity`/`message` + optional `nodeId`/`edgeId`/`fieldKey`/`code`)
+ * so the builder can spread these issues straight into its
+ * `validationIssues` array, and the worker adopts the same shape — one
+ * output vocabulary across both consumers.
+ *
+ * **Recommendation (flagged for the chain review): promote
+ * {@link ValidationIssue} to `@flowget/types`.** It is a cross-repo output
+ * vocabulary consumed by builder + worker (and surfaced by the engine),
+ * exactly the role `@flowget/types` already fills for `TemplateAst`,
+ * `WorkflowGraph`, and `NodeValidationIssue`. It lives here for 0.1.0 only
+ * because `@flowget/types@0.5.0` is already published and out of scope for
+ * this ticket; the next types minor (0.6.0) should host it and this package
+ * should re-export it, so all three consumers converge on one type identity.
+ */
+/** Blocking (`error`) vs advisory (`warning` / `info`). Matches the builder's `ValidationSeverity`. */
+export type ValidationSeverity = "error" | "warning" | "info";
+/**
+ * One validation finding. `nodeId` / `edgeId` / `fieldKey` scope it to a
+ * graph instance so a consumer's renderer resolves back to the exact node /
+ * edge / field. `code` is the stable machine code (see {@link ISSUE_CODES});
+ * `id` is a deterministic, per-run-unique key suitable for a render list.
+ */
+export type ValidationIssue = {
+    /** Deterministic, unique-within-a-run key (stable for a given graph+catalog). */
+    id: string;
+    severity: ValidationSeverity;
+    /** Human-readable message; reference/type issues name BOTH endpoints. */
+    message: string;
+    /** Issue scoped to a specific node. */
+    nodeId?: string;
+    /** Issue scoped to a specific edge. */
+    edgeId?: string;
+    /** Config field key within a node, when the issue is field-scoped. */
+    fieldKey?: string;
+    /** Stable machine code for telemetry / translation (see {@link ISSUE_CODES}). */
+    code?: string;
+};
+/**
+ * Stable machine codes. Consumers switch/telemetry on these; the human
+ * `message` may change wording without a code change.
+ */
+export declare const ISSUE_CODES: {
+    /** `WorkflowNode.type` is absent from the catalog. */
+    readonly UNKNOWN_NODE_TYPE: "validation/unknown-node-type";
+    /** A template references a node id that does not exist in the graph. */
+    readonly TEMPLATE_UNKNOWN_NODE: "validation/template-unknown-node";
+    /** A template references a node that is not an upstream ancestor of the consumer. */
+    readonly TEMPLATE_UNREACHABLE: "validation/template-unreachable";
+    /** A template references an output/payload key the producer does not declare. */
+    readonly TEMPLATE_UNKNOWN_OUTPUT: "validation/template-unknown-output";
+    /** A template path uses a forbidden prototype-chain token. */
+    readonly TEMPLATE_FORBIDDEN_TOKEN: "validation/template-forbidden-token";
+    /** A whole-string template resolves to a value-type incompatible with the consumer field. */
+    readonly TYPE_MISMATCH: "validation/type-mismatch";
+    /** A required field is empty. */
+    readonly FIELD_REQUIRED: "validation/field-required";
+    /** A literal field value's coarse type mismatches the field's declared value type. */
+    readonly FIELD_TYPE: "validation/field-type";
+    /** A `select` field value is not one of the declared options. */
+    readonly FIELD_ENUM: "validation/field-enum";
+    /** A numeric field value is below `min`. */
+    readonly FIELD_MIN: "validation/field-min";
+    /** A numeric field value is above `max`. */
+    readonly FIELD_MAX: "validation/field-max";
+    /** A string field value fails the field's `pattern`. */
+    readonly FIELD_PATTERN: "validation/field-pattern";
+};
+export type IssueCode = (typeof ISSUE_CODES)[keyof typeof ISSUE_CODES];
+/** An issue before its deterministic `id` is assigned. */
+export type RawIssue = Omit<ValidationIssue, "id">;
+/**
+ * Assign each raw issue a deterministic, per-run-unique `id`. The id is a
+ * composite of `code` + scope + an occurrence ordinal (so two issues
+ * sharing a code/node/field — e.g. two dangling refs in one field — still
+ * get distinct ids). Order-dependent only, hence fully deterministic for a
+ * given `(graph, catalog)`. No `Date` / random.
+ */
+export declare function finalizeIssues(raw: readonly RawIssue[]): ValidationIssue[];

package/dist/issues.js

@@ -0,0 +1,66 @@
+/**
+ * The package's PUBLIC OUTPUT contract — {@link ValidationIssue} — plus the
+ * stable machine {@link ISSUE_CODES} and a deterministic id-assigning
+ * collector.
+ *
+ * The shape mirrors the builder's existing `ValidationIssue`
+ * (`id`/`severity`/`message` + optional `nodeId`/`edgeId`/`fieldKey`/`code`)
+ * so the builder can spread these issues straight into its
+ * `validationIssues` array, and the worker adopts the same shape — one
+ * output vocabulary across both consumers.
+ *
+ * **Recommendation (flagged for the chain review): promote
+ * {@link ValidationIssue} to `@flowget/types`.** It is a cross-repo output
+ * vocabulary consumed by builder + worker (and surfaced by the engine),
+ * exactly the role `@flowget/types` already fills for `TemplateAst`,
+ * `WorkflowGraph`, and `NodeValidationIssue`. It lives here for 0.1.0 only
+ * because `@flowget/types@0.5.0` is already published and out of scope for
+ * this ticket; the next types minor (0.6.0) should host it and this package
+ * should re-export it, so all three consumers converge on one type identity.
+ */
+/**
+ * Stable machine codes. Consumers switch/telemetry on these; the human
+ * `message` may change wording without a code change.
+ */
+export const ISSUE_CODES = {
+    /** `WorkflowNode.type` is absent from the catalog. */
+    UNKNOWN_NODE_TYPE: "validation/unknown-node-type",
+    /** A template references a node id that does not exist in the graph. */
+    TEMPLATE_UNKNOWN_NODE: "validation/template-unknown-node",
+    /** A template references a node that is not an upstream ancestor of the consumer. */
+    TEMPLATE_UNREACHABLE: "validation/template-unreachable",
+    /** A template references an output/payload key the producer does not declare. */
+    TEMPLATE_UNKNOWN_OUTPUT: "validation/template-unknown-output",
+    /** A template path uses a forbidden prototype-chain token. */
+    TEMPLATE_FORBIDDEN_TOKEN: "validation/template-forbidden-token",
+    /** A whole-string template resolves to a value-type incompatible with the consumer field. */
+    TYPE_MISMATCH: "validation/type-mismatch",
+    /** A required field is empty. */
+    FIELD_REQUIRED: "validation/field-required",
+    /** A literal field value's coarse type mismatches the field's declared value type. */
+    FIELD_TYPE: "validation/field-type",
+    /** A `select` field value is not one of the declared options. */
+    FIELD_ENUM: "validation/field-enum",
+    /** A numeric field value is below `min`. */
+    FIELD_MIN: "validation/field-min",
+    /** A numeric field value is above `max`. */
+    FIELD_MAX: "validation/field-max",
+    /** A string field value fails the field's `pattern`. */
+    FIELD_PATTERN: "validation/field-pattern",
+};
+/**
+ * Assign each raw issue a deterministic, per-run-unique `id`. The id is a
+ * composite of `code` + scope + an occurrence ordinal (so two issues
+ * sharing a code/node/field — e.g. two dangling refs in one field — still
+ * get distinct ids). Order-dependent only, hence fully deterministic for a
+ * given `(graph, catalog)`. No `Date` / random.
+ */
+export function finalizeIssues(raw) {
+    const ordinals = new Map();
+    return raw.map((issue) => {
+        const key = `${issue.code ?? ""}#${issue.nodeId ?? ""}#${issue.edgeId ?? ""}#${issue.fieldKey ?? ""}`;
+        const n = ordinals.get(key) ?? 0;
+        ordinals.set(key, n + 1);
+        return { ...issue, id: `${key}#${n}` };
+    });
+}

package/dist/reachability.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Graph reachability — "which nodes ran before node X". A `{{ steps.P.… }}`
+ * reference resolves at runtime only if P's output is already in scope, i.e.
+ * P is an UPSTREAM ANCESTOR of the consumer. Lifted from the builder's
+ * `variables.ts` `collectUpstream`, so the reachable set the validator
+ * computes is identical to the set the builder's variable picker walks.
+ *
+ * The reversed adjacency is built ONCE ({@link buildReversedAdjacency}) and
+ * reused across every {@link collectUpstreamFrom} walk. This is the hot path —
+ * the validator runs on every builder submit and every worker pre-flight —
+ * so rebuilding the map per consumer node (O(V·(V+E))) is avoided.
+ */
+import type { WorkflowEdge } from "@flowget/types";
+/**
+ * Reversed adjacency: node id → its DIRECT predecessor (edge `source`) ids.
+ * Built once from the full edge list in O(E); reused by every
+ * {@link collectUpstreamFrom} call over the same graph.
+ */
+export declare function buildReversedAdjacency(edges: readonly WorkflowEdge[]): ReadonlyMap<string, string[]>;
+/**
+ * Every node id transitively upstream of `nodeId`, walking a PREBUILT reversed
+ * adjacency. Iterative DFS with a visited set — handles diamonds and tolerates
+ * cycles. `nodeId` itself is NOT included (a node is not its own ancestor — a
+ * self-reference is correctly unreachable). O(V+E) per call over the prebuilt
+ * map.
+ */
+export declare function collectUpstreamFrom(nodeId: string, adjacency: ReadonlyMap<string, string[]>): Set<string>;
+/**
+ * Convenience wrapper — {@link buildReversedAdjacency} + a single
+ * {@link collectUpstreamFrom} walk. Kept as the stable public entry point.
+ *
+ * When resolving upstream sets for MANY nodes over the same edge list (the
+ * validator's own hot path), build the adjacency ONCE with
+ * {@link buildReversedAdjacency} and call {@link collectUpstreamFrom} per node
+ * instead — this wrapper rebuilds the map on every call.
+ */
+export declare function collectUpstream(nodeId: string, edges: readonly WorkflowEdge[]): Set<string>;

package/dist/reachability.js

@@ -0,0 +1,60 @@
+/**
+ * Graph reachability — "which nodes ran before node X". A `{{ steps.P.… }}`
+ * reference resolves at runtime only if P's output is already in scope, i.e.
+ * P is an UPSTREAM ANCESTOR of the consumer. Lifted from the builder's
+ * `variables.ts` `collectUpstream`, so the reachable set the validator
+ * computes is identical to the set the builder's variable picker walks.
+ *
+ * The reversed adjacency is built ONCE ({@link buildReversedAdjacency}) and
+ * reused across every {@link collectUpstreamFrom} walk. This is the hot path —
+ * the validator runs on every builder submit and every worker pre-flight —
+ * so rebuilding the map per consumer node (O(V·(V+E))) is avoided.
+ */
+/**
+ * Reversed adjacency: node id → its DIRECT predecessor (edge `source`) ids.
+ * Built once from the full edge list in O(E); reused by every
+ * {@link collectUpstreamFrom} call over the same graph.
+ */
+export function buildReversedAdjacency(edges) {
+    const adjacency = new Map();
+    for (const e of edges) {
+        const bucket = adjacency.get(e.target);
+        if (bucket)
+            bucket.push(e.source);
+        else
+            adjacency.set(e.target, [e.source]);
+    }
+    return adjacency;
+}
+/**
+ * Every node id transitively upstream of `nodeId`, walking a PREBUILT reversed
+ * adjacency. Iterative DFS with a visited set — handles diamonds and tolerates
+ * cycles. `nodeId` itself is NOT included (a node is not its own ancestor — a
+ * self-reference is correctly unreachable). O(V+E) per call over the prebuilt
+ * map.
+ */
+export function collectUpstreamFrom(nodeId, adjacency) {
+    const visited = new Set();
+    const stack = [...(adjacency.get(nodeId) ?? [])];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (id === undefined || visited.has(id))
+            continue;
+        visited.add(id);
+        for (const up of adjacency.get(id) ?? [])
+            stack.push(up);
+    }
+    return visited;
+}
+/**
+ * Convenience wrapper — {@link buildReversedAdjacency} + a single
+ * {@link collectUpstreamFrom} walk. Kept as the stable public entry point.
+ *
+ * When resolving upstream sets for MANY nodes over the same edge list (the
+ * validator's own hot path), build the adjacency ONCE with
+ * {@link buildReversedAdjacency} and call {@link collectUpstreamFrom} per node
+ * instead — this wrapper rebuilds the map on every call.
+ */
+export function collectUpstream(nodeId, edges) {
+    return collectUpstreamFrom(nodeId, buildReversedAdjacency(edges));
+}

package/dist/references.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Reference-existence + reachability + whole-string type-compat walker.
+ *
+ * For every non-opaque config value on every node, parse its `{{ … }}`
+ * templates and check each operand against the runtime resolver's rules:
+ *
+ *   1. **Existence** — a `steps.<id>` / bare `<id>` token must name a real
+ *      graph node; a `steps.<id>.output.<key>` / `<id>.<field>` /
+ *      `trigger.<key>` token must name a DECLARED output / trigger-payload
+ *      field.
+ *   2. **Reachability** — the producer node must be an upstream ANCESTOR of
+ *      the consumer (its output is only in scope if it ran first). A
+ *      self-reference is correctly unreachable.
+ *   3. **Type-compat** — when the whole field value is a single
+ *      `{{ … }}` token, compare the producer's declared value-type against
+ *      the consumer field's via the coarse {@link isAssignable} lattice.
+ *
+ * Every rule is CONSERVATIVE: it fires only when the producer, its output,
+ * and the consumer field are all statically KNOWN and the mismatch is
+ * certain — permissive on unknown/undeclared/opaque, for zero false
+ * positives. `workflow.*` / `input.*` are opaque execution primitives
+ * (never flagged); `trigger.*` is checked only against declared trigger
+ * payloads and is NOT reachability-gated (the worker populates the reserved
+ * `trigger` namespace globally at runtime, independent of topology).
+ */
+import type { WorkflowGraph } from "@flowget/types";
+import { type CatalogIndex } from "./catalog.js";
+import { type RawIssue } from "./issues.js";
+/** Collect every reference/reachability/type-compat issue across the graph. */
+export declare function collectReferenceIssues(graph: WorkflowGraph, index: CatalogIndex): RawIssue[];

package/dist/references.js

@@ -0,0 +1,312 @@
+/**
+ * Reference-existence + reachability + whole-string type-compat walker.
+ *
+ * For every non-opaque config value on every node, parse its `{{ … }}`
+ * templates and check each operand against the runtime resolver's rules:
+ *
+ *   1. **Existence** — a `steps.<id>` / bare `<id>` token must name a real
+ *      graph node; a `steps.<id>.output.<key>` / `<id>.<field>` /
+ *      `trigger.<key>` token must name a DECLARED output / trigger-payload
+ *      field.
+ *   2. **Reachability** — the producer node must be an upstream ANCESTOR of
+ *      the consumer (its output is only in scope if it ran first). A
+ *      self-reference is correctly unreachable.
+ *   3. **Type-compat** — when the whole field value is a single
+ *      `{{ … }}` token, compare the producer's declared value-type against
+ *      the consumer field's via the coarse {@link isAssignable} lattice.
+ *
+ * Every rule is CONSERVATIVE: it fires only when the producer, its output,
+ * and the consumer field are all statically KNOWN and the mismatch is
+ * certain — permissive on unknown/undeclared/opaque, for zero false
+ * positives. `workflow.*` / `input.*` are opaque execution primitives
+ * (never flagged); `trigger.*` is checked only against declared trigger
+ * payloads and is NOT reachability-gated (the worker populates the reserved
+ * `trigger` namespace globally at runtime, independent of topology).
+ */
+import { resolveFieldValueType } from "@flowget/types";
+import { resolveNodeOutputFields, resolveNodeTriggerPayload, } from "./catalog.js";
+import { ISSUE_CODES } from "./issues.js";
+import { buildReversedAdjacency, collectUpstreamFrom } from "./reachability.js";
+import { hasForbiddenPathToken, hasTemplateExpression, isWholeStringTemplate, parseTemplate, templateExpressions, } from "./template-ast.js";
+import { isAssignable, isConcreteScalar } from "./value-type.js";
+/** Bound on nested-data recursion (rows / key-value / nested objects). */
+const MAX_DATA_DEPTH = 64;
+/** Collect every reference/reachability/type-compat issue across the graph. */
+export function collectReferenceIssues(graph, index) {
+    const ctx = {
+        index,
+        nodeById: new Map(graph.nodes.map((n) => [n.id, n])),
+        triggerInfo: computeTriggerInfo(graph, index),
+        adjacency: buildReversedAdjacency(graph.edges),
+        upstreamCache: new Map(),
+    };
+    const issues = [];
+    for (const node of graph.nodes) {
+        const def = index.get(node.type);
+        const opaque = new Set(def?.opaqueFields ?? []);
+        const fieldsByKey = new Map((def?.fields ?? []).map((f) => [f.key, f]));
+        for (const [key, value] of Object.entries(node.data ?? {})) {
+            if (opaque.has(key))
+                continue;
+            const field = fieldsByKey.get(key);
+            const site = {
+                node,
+                fieldKey: key,
+                consumerType: field ? resolveFieldValueType(field) : undefined,
+            };
+            walkValue(value, true, 0, site, ctx, issues);
+        }
+    }
+    return issues;
+}
+/** Recursively descend config values, validating template strings at the leaves. */
+function walkValue(value, isTopLevel, depth, site, ctx, issues) {
+    if (typeof value === "string") {
+        validateTemplateString(value, isTopLevel, site, ctx, issues);
+        return;
+    }
+    if (depth >= MAX_DATA_DEPTH)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            walkValue(item, false, depth + 1, site, ctx, issues);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value)) {
+            walkValue(child, false, depth + 1, site, ctx, issues);
+        }
+    }
+}
+function validateTemplateString(raw, isTopLevel, site, ctx, issues) {
+    const ast = parseTemplate(raw);
+    if (!hasTemplateExpression(ast))
+        return;
+    const upstream = getUpstream(site.node.id, ctx);
+    const wholeString = isWholeStringTemplate(ast);
+    for (const { raw: tokenRaw, expression } of templateExpressions(ast)) {
+        // A `??` fallback chain RESCUES a missing operand at runtime (the engine
+        // swallows missing_step / missing_path and falls through to the next
+        // operand; only the whole chain going empty yields undefined/"" — it
+        // never throws). So existence / reachability / unknown-output are checked
+        // ONLY for a single-operand expression, where a miss genuinely throws.
+        // Flagging an operand inside a `??` chain would be a false positive: the
+        // chain resolves fine. The forbidden-path-token guard is the exception —
+        // the engine throws it even under `??`, so it is checked on every operand.
+        const singleOperand = expression.operands.length === 1;
+        for (const path of expression.operands) {
+            if (hasForbiddenPathToken(path)) {
+                issues.push({
+                    code: ISSUE_CODES.TEMPLATE_FORBIDDEN_TOKEN,
+                    severity: "error",
+                    nodeId: site.node.id,
+                    fieldKey: site.fieldKey,
+                    message: `Node "${site.node.id}" template "${tokenRaw}" uses a forbidden path token (\`__proto__\` / \`constructor\` / \`prototype\`) and will be rejected at runtime.`,
+                });
+                continue;
+            }
+            if (singleOperand) {
+                validateOperandExistence(path, tokenRaw, site, ctx, upstream, issues);
+            }
+        }
+        // Type-compat: only for a whole-string, single-operand template into a
+        // concrete-scalar consumer field. Multi-operand `??` chains and
+        // interpolation are intentionally not type-checked (zero false positives).
+        if (wholeString &&
+            isTopLevel &&
+            site.consumerType !== undefined &&
+            isConcreteScalar(site.consumerType) &&
+            expression.operands.length === 1) {
+            const operand = expression.operands[0];
+            if (operand !== undefined) {
+                const producerType = producerValueType(operand, ctx, upstream);
+                if (producerType !== undefined &&
+                    isConcreteScalar(producerType) &&
+                    !isAssignable(producerType, site.consumerType)) {
+                    issues.push({
+                        code: ISSUE_CODES.TYPE_MISMATCH,
+                        severity: "error",
+                        nodeId: site.node.id,
+                        fieldKey: site.fieldKey,
+                        message: `Node "${site.node.id}" field "${site.fieldKey}" expects ${site.consumerType} but "${tokenRaw}" resolves to ${producerType}.`,
+                    });
+                }
+            }
+        }
+    }
+}
+/** Validate one operand's producer existence + reachability + declared-output. */
+function validateOperandExistence(path, tokenRaw, site, ctx, upstream, issues) {
+    if (path.kind === "v1-reserved") {
+        const ns = path.segments[0];
+        // `workflow.*` / `input.*` are opaque execution primitives — permissive.
+        if (ns === "trigger")
+            validateTriggerKey(path, tokenRaw, site, ctx, issues);
+        return;
+    }
+    // Resolve the producer node id per grammar: `steps.<id>.…` vs bare `<id>.…`.
+    const producerId = path.kind === "v2-step" ? path.segments[1] : path.segments[0];
+    if (producerId === undefined || producerId === "")
+        return;
+    const reachIssue = checkProducerReachable(producerId, tokenRaw, site, ctx, upstream);
+    if (reachIssue !== null) {
+        issues.push(reachIssue);
+        return;
+    }
+    // Declared-output check on the canonical envelope only.
+    //  - v2-step: `steps.<id>.output.<key>` (segments[2] === "output").
+    //             `steps.<id>.decorators.…` and other shapes are permissive.
+    //  - v1-step: `<id>.<field>` maps to `output.<field>`.
+    if (path.kind === "v2-step") {
+        if (path.segments[2] === "output" && path.segments.length >= 4) {
+            checkOutputKey(producerId, path.segments[3], tokenRaw, site, ctx, issues);
+        }
+        return;
+    }
+    if (path.segments.length >= 2) {
+        checkOutputKey(producerId, path.segments[1], tokenRaw, site, ctx, issues);
+    }
+}
+function checkProducerReachable(producerId, tokenRaw, site, ctx, upstream) {
+    if (!ctx.nodeById.has(producerId)) {
+        return {
+            code: ISSUE_CODES.TEMPLATE_UNKNOWN_NODE,
+            severity: "error",
+            nodeId: site.node.id,
+            fieldKey: site.fieldKey,
+            message: `Node "${site.node.id}" references "${tokenRaw}" but no node "${producerId}" exists in the workflow.`,
+        };
+    }
+    if (producerId === site.node.id || !upstream.has(producerId)) {
+        return {
+            code: ISSUE_CODES.TEMPLATE_UNREACHABLE,
+            severity: "error",
+            nodeId: site.node.id,
+            fieldKey: site.fieldKey,
+            message: `Node "${site.node.id}" references "${tokenRaw}" but "${producerId}" is not upstream of "${site.node.id}" — its output is not available here.`,
+        };
+    }
+    return null;
+}
+function checkOutputKey(producerId, key, tokenRaw, site, ctx, issues) {
+    if (key === undefined || key === "")
+        return;
+    const producer = ctx.nodeById.get(producerId);
+    if (producer === undefined)
+        return;
+    const def = ctx.index.get(producer.type);
+    // Unknown node type is reported by the aggregator; decorators produce no
+    // step scope. Both permissive here.
+    if (def === undefined || def.category === "decorator")
+        return;
+    const outputs = resolveNodeOutputFields(def, producer.data ?? {});
+    if (outputs.length === 0)
+        return; // undeclared/unknown outputs → permissive
+    if (!outputs.some((f) => f.key === key)) {
+        issues.push({
+            code: ISSUE_CODES.TEMPLATE_UNKNOWN_OUTPUT,
+            severity: "error",
+            nodeId: site.node.id,
+            fieldKey: site.fieldKey,
+            message: `Node "${site.node.id}" references "${tokenRaw}", but "${producerId}" declares no output "${key}".`,
+        });
+    }
+}
+function validateTriggerKey(path, tokenRaw, site, ctx, issues) {
+    const key = path.segments[1];
+    if (key === undefined || key === "")
+        return;
+    const info = ctx.triggerInfo;
+    // No trigger at all → the missing-trigger rule covers it; some trigger
+    // payload unknown → permissive.
+    if (!info.hasTrigger || !info.allKnown)
+        return;
+    if (!info.keys.has(key)) {
+        issues.push({
+            code: ISSUE_CODES.TEMPLATE_UNKNOWN_OUTPUT,
+            severity: "error",
+            nodeId: site.node.id,
+            fieldKey: site.fieldKey,
+            message: `Node "${site.node.id}" references "${tokenRaw}", but no trigger declares a payload field "${key}".`,
+        });
+    }
+}
+/**
+ * The concrete value-type a fully-resolving reference produces, or
+ * `undefined` when it cannot be pinned down statically (drill-in, unknown
+ * node, unreachable, undeclared output, opaque namespace) — in which case
+ * type-compat is skipped.
+ */
+function producerValueType(path, ctx, upstream) {
+    if (path.kind === "v1-reserved") {
+        if (path.segments[0] !== "trigger" || path.segments.length !== 2) {
+            return undefined;
+        }
+        const key = path.segments[1];
+        return key !== undefined ? ctx.triggerInfo.keyTypes.get(key) : undefined;
+    }
+    if (path.kind === "v2-step") {
+        if (path.segments.length !== 4 || path.segments[2] !== "output") {
+            return undefined;
+        }
+        return outputFieldType(path.segments[1], path.segments[3], ctx, upstream);
+    }
+    // v1-step: exactly `<id>.<field>`.
+    if (path.segments.length !== 2)
+        return undefined;
+    return outputFieldType(path.segments[0], path.segments[1], ctx, upstream);
+}
+function outputFieldType(producerId, key, ctx, upstream) {
+    if (producerId === undefined || key === undefined)
+        return undefined;
+    if (!upstream.has(producerId))
+        return undefined;
+    const producer = ctx.nodeById.get(producerId);
+    if (producer === undefined)
+        return undefined;
+    const def = ctx.index.get(producer.type);
+    if (def === undefined || def.category === "decorator")
+        return undefined;
+    const outputs = resolveNodeOutputFields(def, producer.data ?? {});
+    return outputs.find((f) => f.key === key)?.type;
+}
+function getUpstream(nodeId, ctx) {
+    let upstream = ctx.upstreamCache.get(nodeId);
+    if (upstream === undefined) {
+        upstream = collectUpstreamFrom(nodeId, ctx.adjacency);
+        ctx.upstreamCache.set(nodeId, upstream);
+    }
+    return upstream;
+}
+function computeTriggerInfo(graph, index) {
+    let hasTrigger = false;
+    let allKnown = true;
+    const keys = new Set();
+    // `null` marks a key whose type is ambiguous across triggers.
+    const keyTypes = new Map();
+    for (const node of graph.nodes) {
+        const def = index.get(node.type);
+        if (def?.category !== "trigger")
+            continue;
+        hasTrigger = true;
+        const payload = resolveNodeTriggerPayload(def, node.data ?? {});
+        if (payload.length === 0) {
+            allKnown = false;
+            continue;
+        }
+        for (const f of payload) {
+            keys.add(f.key);
+            if (!keyTypes.has(f.key))
+                keyTypes.set(f.key, f.type);
+            else if (keyTypes.get(f.key) !== f.type)
+                keyTypes.set(f.key, null);
+        }
+    }
+    const finalTypes = new Map();
+    for (const [k, v] of keyTypes) {
+        if (v !== null)
+            finalTypes.set(k, v);
+    }
+    return { hasTrigger, allKnown, keys, keyTypes: finalTypes };
+}