@flowget/graph-validation 0.1.0 → 0.3.0

package/README.md

@@ -25,6 +25,13 @@ What it does:
   `??` fallback chains). ReDoS-safe on untrusted input.
 - **Reference existence + reachability** — every `{{ steps.<id>.output.<key> }}`
   token must name a real upstream node and a declared output.
+- **Nested fields via dotted keys** — a `.` in an `OutputField` / trigger-payload
+  `key` is the path separator (matching the template grammar, which has no
+  bracket form). A flat list of `payment.id` / `payment.amount` reconstructs a
+  `payment` object so `{{ trigger.payment.amount }}` resolves at leaf
+  granularity. An undeclared nested child is an advisory **warning** (the
+  runtime payload may still carry it); a key declared as both a scalar and an
+  object parent is a hard error.
 - **Coarse value-type lattice** — `isAssignable(producer, consumer)` over the
   `FieldValueType` set; permissive on `unknown` / `object` / `array` so a
   "valid" verdict never lies (zero false positives).
@@ -32,6 +39,12 @@ What it does:
   `min` / `max` / `pattern`.
 - **`validateGraphStatic(graph, catalog)`** — the aggregator, returning a flat
   `ValidationIssue[]`.
+- **`validateTriggerInputs(graph, catalog, input)`** — a run-input gate: flags
+  every `{{ trigger.<path> }}` the graph references that the run input (the
+  builder's test input, or the worker's real event payload) does not provide,
+  path-aware and false-positive-free. Config traversal is bounded (a
+  stack-overflow-DoS guard); a reference nested deeper than the bound is left to
+  the runtime resolver's non-retryable throw rather than pre-checked.
 
 ## Install
 

package/dist/field-tree.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Dotted-key-as-path resolution for `OutputField` / `triggerPayload` keys.
+ *
+ * The template grammar uses `.` as its ONLY path separator — there is no
+ * `{{ trigger["payment.id"] }}` bracket form (see `template-ast.ts`'s
+ * `PATH_RE`). So a runtime object key that literally contains a `.` is
+ * unreachable through any template, and the only sound reading of a `.` in a
+ * declared field key is "nested path". This module treats it as such: a flat
+ * list like
+ *
+ *   [ { key: "payment.id", type: "string" },
+ *     { key: "payment.amount", type: "number" } ]
+ *
+ * reconstructs the tree
+ *
+ *   payment (implied object)
+ *     ├─ id     : string
+ *     └─ amount : number
+ *
+ * so `{{ trigger.payment.amount }}` resolves against it. This is a TOTAL,
+ * collision-free interpretation, not a heuristic — nothing legitimate is lost,
+ * so migration is zero.
+ *
+ * ## Resolution posture (zero false positives)
+ *
+ *   - **Known path** — a reference that names a declared leaf OR a prefix of
+ *     one (an intermediate object) resolves cleanly. No issue.
+ *   - **Unknown top-level segment** — the top-level declared key set is the
+ *     node's authoritative contract; an unknown top-level key is a hard error
+ *     (unchanged pre-nesting behavior).
+ *   - **Undeclared child of a known enumerated parent** — a WARNING, not an
+ *     error: the runtime payload may legitimately carry a child the author did
+ *     not enumerate, so blocking it could reject a run that would succeed.
+ *   - **Drill-in past a leaf** (bare `object` / scalar / wildcard with no
+ *     enumerated children) — permissive, no issue (unchanged).
+ *   - **Contradiction** — a key that is both a concrete-scalar leaf and a
+ *     path prefix is an authoring error, surfaced at the declaration.
+ */
+import type { FieldValueType, OutputField } from "@flowget/types";
+/** One node in a declared-field prefix tree. */
+export interface FieldTreeNode {
+    /**
+     * The value-type declared for the field at EXACTLY this path, when a field
+     * key terminates here (`undefined` for a purely-implied intermediate node
+     * that only appears as a prefix of deeper dotted keys).
+     */
+    declaredType?: FieldValueType;
+    /** Child segments — non-empty iff this key appears as a non-terminal path prefix. */
+    children: Map<string, FieldTreeNode>;
+}
+/** A declared-field prefix tree plus the contradictions found building it. */
+export interface FieldTree {
+    /** Top-level segment → node. */
+    root: Map<string, FieldTreeNode>;
+    /** Keys that are both a concrete-scalar leaf and a nested-object parent. */
+    contradictions: FieldPathConflict[];
+}
+/** A single declared key used both as a concrete-scalar leaf and a path prefix. */
+export interface FieldPathConflict {
+    /** The dotted path of the conflicting node (e.g. `"payment"`). */
+    path: string;
+    /** The concrete-scalar type it was declared as. */
+    scalarType: FieldValueType;
+}
+/** How a reference path resolves against a {@link FieldTree}. */
+export type PathResolution = 
+/** No declared fields at all → nothing to check (permissive). */
+{
+    kind: "no-declarations";
+}
+/** Names a declared leaf or a prefix of one → valid. */
+ | {
+    kind: "known";
+}
+/** Drills past a leaf with no enumerated children → permissive (unchanged). */
+ | {
+    kind: "drill-through-leaf";
+}
+/** Unknown top-level segment against a non-empty declared set → error. */
+ | {
+    kind: "unknown-root";
+    rootKey: string;
+}
+/** Undeclared child of a known enumerated parent → warning. */
+ | {
+    kind: "undeclared-child";
+    parentPath: string;
+    childKey: string;
+    declaredSiblings: string[];
+};
+/**
+ * Build the prefix tree for one flat `OutputField[]` list, splitting each key
+ * on `.`. Non-terminal segments imply an intermediate object; the terminal
+ * segment carries the declared `type`.
+ *
+ * Contradictions (a concrete-scalar leaf that also has children — either order
+ * of declaration) are collected, deduplicated by path. A redundant-consistent
+ * pair (`payment: object` + `payment.id`) is NOT a contradiction: the explicit
+ * `object` parent is legal and keeps carrying its own group-level metadata.
+ */
+export declare function buildFieldTree(fields: readonly OutputField[]): FieldTree;
+/**
+ * Resolve a reference's path segments (those AFTER the `trigger` /
+ * `steps.<id>.output` prefix) against a declared-field tree.
+ *
+ * `pathSegments` is the drill-in path, e.g. `["payment", "amount"]` for
+ * `{{ trigger.payment.amount }}`. An empty `pathSegments` (a bare
+ * `{{ trigger }}`) resolves as `known` — the namespace itself exists.
+ */
+export declare function resolvePath(tree: FieldTree, pathSegments: readonly string[]): PathResolution;

package/dist/field-tree.js

@@ -0,0 +1,147 @@
+/**
+ * Dotted-key-as-path resolution for `OutputField` / `triggerPayload` keys.
+ *
+ * The template grammar uses `.` as its ONLY path separator — there is no
+ * `{{ trigger["payment.id"] }}` bracket form (see `template-ast.ts`'s
+ * `PATH_RE`). So a runtime object key that literally contains a `.` is
+ * unreachable through any template, and the only sound reading of a `.` in a
+ * declared field key is "nested path". This module treats it as such: a flat
+ * list like
+ *
+ *   [ { key: "payment.id", type: "string" },
+ *     { key: "payment.amount", type: "number" } ]
+ *
+ * reconstructs the tree
+ *
+ *   payment (implied object)
+ *     ├─ id     : string
+ *     └─ amount : number
+ *
+ * so `{{ trigger.payment.amount }}` resolves against it. This is a TOTAL,
+ * collision-free interpretation, not a heuristic — nothing legitimate is lost,
+ * so migration is zero.
+ *
+ * ## Resolution posture (zero false positives)
+ *
+ *   - **Known path** — a reference that names a declared leaf OR a prefix of
+ *     one (an intermediate object) resolves cleanly. No issue.
+ *   - **Unknown top-level segment** — the top-level declared key set is the
+ *     node's authoritative contract; an unknown top-level key is a hard error
+ *     (unchanged pre-nesting behavior).
+ *   - **Undeclared child of a known enumerated parent** — a WARNING, not an
+ *     error: the runtime payload may legitimately carry a child the author did
+ *     not enumerate, so blocking it could reject a run that would succeed.
+ *   - **Drill-in past a leaf** (bare `object` / scalar / wildcard with no
+ *     enumerated children) — permissive, no issue (unchanged).
+ *   - **Contradiction** — a key that is both a concrete-scalar leaf and a
+ *     path prefix is an authoring error, surfaced at the declaration.
+ */
+import { isConcreteScalar } from "./value-type.js";
+/**
+ * Build the prefix tree for one flat `OutputField[]` list, splitting each key
+ * on `.`. Non-terminal segments imply an intermediate object; the terminal
+ * segment carries the declared `type`.
+ *
+ * Contradictions (a concrete-scalar leaf that also has children — either order
+ * of declaration) are collected, deduplicated by path. A redundant-consistent
+ * pair (`payment: object` + `payment.id`) is NOT a contradiction: the explicit
+ * `object` parent is legal and keeps carrying its own group-level metadata.
+ */
+export function buildFieldTree(fields) {
+    const root = new Map();
+    const conflicts = new Map();
+    for (const field of fields) {
+        const segments = field.key.split(".");
+        let level = root;
+        const pathSoFar = [];
+        for (let i = 0; i < segments.length; i++) {
+            const seg = segments[i];
+            if (seg === undefined)
+                break;
+            pathSoFar.push(seg);
+            let node = level.get(seg);
+            if (node === undefined) {
+                node = { children: new Map() };
+                level.set(seg, node);
+            }
+            const isTerminal = i === segments.length - 1;
+            if (isTerminal) {
+                // A concrete-scalar terminal on a node that already has children is a
+                // conflict (the dotted siblings made it an object).
+                if (node.children.size > 0 && isConcreteScalar(field.type)) {
+                    conflicts.set(pathSoFar.join("."), field.type);
+                }
+                // Prefer an explicit container declaration over an implied one; keep a
+                // scalar only if nothing container-shaped was declared here.
+                if (node.declaredType === undefined || isConcreteScalar(node.declaredType)) {
+                    node.declaredType = field.type;
+                }
+            }
+            else {
+                // Intermediate segment: if this node was declared a concrete scalar
+                // leaf, giving it children is a conflict.
+                if (node.declaredType !== undefined &&
+                    isConcreteScalar(node.declaredType)) {
+                    conflicts.set(pathSoFar.join("."), node.declaredType);
+                }
+                level = node.children;
+            }
+        }
+    }
+    const contradictions = [];
+    for (const [path, scalarType] of conflicts) {
+        contradictions.push({ path, scalarType });
+    }
+    return { root, contradictions };
+}
+/**
+ * Resolve a reference's path segments (those AFTER the `trigger` /
+ * `steps.<id>.output` prefix) against a declared-field tree.
+ *
+ * `pathSegments` is the drill-in path, e.g. `["payment", "amount"]` for
+ * `{{ trigger.payment.amount }}`. An empty `pathSegments` (a bare
+ * `{{ trigger }}`) resolves as `known` — the namespace itself exists.
+ */
+export function resolvePath(tree, pathSegments) {
+    if (tree.root.size === 0)
+        return { kind: "no-declarations" };
+    if (pathSegments.length === 0)
+        return { kind: "known" };
+    // A malformed drill-in with an empty segment (a trailing/interior dot, e.g.
+    // `{{ trigger. }}` / `{{ a..b }}`) is permissive HERE — resolvePath is pure
+    // declaration resolution. The empty segment is a grammar-level error that the
+    // reference walker flags upstream (`hasEmptyPathSegment` →
+    // TEMPLATE_EMPTY_SEGMENT, single-operand-only), mirroring the engine's
+    // unconditional runtime throw; resolvePath must not also mis-resolve it here.
+    if (pathSegments.some((s) => s === ""))
+        return { kind: "known" };
+    let level = tree.root;
+    let current;
+    for (let i = 0; i < pathSegments.length; i++) {
+        const seg = pathSegments[i];
+        if (seg === undefined)
+            return { kind: "known" };
+        const next = level.get(seg);
+        if (next === undefined) {
+            // Segment not enumerated at this level.
+            if (i === 0)
+                return { kind: "unknown-root", rootKey: seg };
+            // `current` is the resolved parent (a known path). If it enumerates
+            // children, this is an undeclared sibling → warning; otherwise it's a
+            // bare leaf (object/scalar/wildcard) → permissive drill-through.
+            if (current !== undefined && current.children.size > 0) {
+                return {
+                    kind: "undeclared-child",
+                    parentPath: pathSegments.slice(0, i).join("."),
+                    childKey: seg,
+                    declaredSiblings: [...current.children.keys()],
+                };
+            }
+            return { kind: "drill-through-leaf" };
+        }
+        current = next;
+        level = next.children;
+    }
+    // Consumed every segment → an exact declared path (leaf or prefix).
+    return { kind: "known" };
+}

package/dist/index.d.ts

@@ -13,9 +13,11 @@
  * classifier) can compose them directly.
  */
 export { validateGraphStatic } from "./validate-graph.js";
+export { collectReferencedTriggerPaths, validateTriggerInputs, } from "./trigger-inputs.js";
+export { buildFieldTree, type FieldPathConflict, type FieldTree, type FieldTreeNode, type PathResolution, resolvePath, } from "./field-tree.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 { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasEmptyPathSegment, 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

@@ -14,12 +14,16 @@
  */
 // ── Primary aggregator ──────────────────────────────────────
 export { validateGraphStatic } from "./validate-graph.js";
+// ── Run-input gate (builder RunTestDialog + worker pre-flight) ─
+export { collectReferencedTriggerPaths, validateTriggerInputs, } from "./trigger-inputs.js";
+// ── Dotted-key-as-path resolution (nested OutputField / payload) ─
+export { buildFieldTree, resolvePath, } from "./field-tree.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";
+export { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasEmptyPathSegment, 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 ────────────────────────────────────────────

package/dist/issues.d.ts

@@ -54,8 +54,38 @@ export declare const ISSUE_CODES: {
     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";
+    /**
+     * WARNING (advisory, non-blocking). A template drills into a child of a
+     * KNOWN nested-object field whose child set is enumerated (via dotted
+     * sibling keys) but does not list this child. The runtime payload MAY still
+     * carry it, so this is a likely-typo hint, not a hard error — see the
+     * zero-false-positive posture for nested drill-in.
+     */
+    readonly TEMPLATE_UNDECLARED_CHILD: "validation/template-undeclared-child";
+    /**
+     * A single declared field key is BOTH a concrete scalar leaf AND a
+     * nested-object parent (a dotted sibling implies it holds children). E.g.
+     * `payment: string` alongside `payment.id: string`. Unresolvable — the
+     * dotted-key-as-path grammar cannot honor both. Reject at the declaration.
+     */
+    readonly FIELD_PATH_CONFLICT: "validation/field-path-conflict";
+    /**
+     * A `{{ trigger.<path> }}` the graph REFERENCES is absent from the run
+     * input (test input at builder Run, real event payload at worker pre-flight).
+     * The strict resolver throws `missing_path` on it at run time.
+     */
+    readonly RUN_INPUT_MISSING: "validation/run-input-missing";
     /** A template path uses a forbidden prototype-chain token. */
     readonly TEMPLATE_FORBIDDEN_TOKEN: "validation/template-forbidden-token";
+    /**
+     * A template path has an empty/blank segment — a leading, trailing, or
+     * doubled dot (`{{ trigger. }}`, `{{ steps.x.output. }}`, `{{ a..b }}`). The
+     * engine resolver throws `missing_path` / `missing_step` on an empty token
+     * UNCONDITIONALLY (input-independent), so the static verdict flags it too.
+     * Checked per-operand for a single-operand expression only — a `??` chain
+     * rescues the throw, so flagging inside a chain would be a false positive.
+     */
+    readonly TEMPLATE_EMPTY_SEGMENT: "validation/template-empty-segment";
     /** 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. */

package/dist/issues.js

@@ -31,8 +31,38 @@ export const ISSUE_CODES = {
     TEMPLATE_UNREACHABLE: "validation/template-unreachable",
     /** A template references an output/payload key the producer does not declare. */
     TEMPLATE_UNKNOWN_OUTPUT: "validation/template-unknown-output",
+    /**
+     * WARNING (advisory, non-blocking). A template drills into a child of a
+     * KNOWN nested-object field whose child set is enumerated (via dotted
+     * sibling keys) but does not list this child. The runtime payload MAY still
+     * carry it, so this is a likely-typo hint, not a hard error — see the
+     * zero-false-positive posture for nested drill-in.
+     */
+    TEMPLATE_UNDECLARED_CHILD: "validation/template-undeclared-child",
+    /**
+     * A single declared field key is BOTH a concrete scalar leaf AND a
+     * nested-object parent (a dotted sibling implies it holds children). E.g.
+     * `payment: string` alongside `payment.id: string`. Unresolvable — the
+     * dotted-key-as-path grammar cannot honor both. Reject at the declaration.
+     */
+    FIELD_PATH_CONFLICT: "validation/field-path-conflict",
+    /**
+     * A `{{ trigger.<path> }}` the graph REFERENCES is absent from the run
+     * input (test input at builder Run, real event payload at worker pre-flight).
+     * The strict resolver throws `missing_path` on it at run time.
+     */
+    RUN_INPUT_MISSING: "validation/run-input-missing",
     /** A template path uses a forbidden prototype-chain token. */
     TEMPLATE_FORBIDDEN_TOKEN: "validation/template-forbidden-token",
+    /**
+     * A template path has an empty/blank segment — a leading, trailing, or
+     * doubled dot (`{{ trigger. }}`, `{{ steps.x.output. }}`, `{{ a..b }}`). The
+     * engine resolver throws `missing_path` / `missing_step` on an empty token
+     * UNCONDITIONALLY (input-independent), so the static verdict flags it too.
+     * Checked per-operand for a single-operand expression only — a `??` chain
+     * rescues the throw, so flagging inside a chain would be a false positive.
+     */
+    TEMPLATE_EMPTY_SEGMENT: "validation/template-empty-segment",
     /** A whole-string template resolves to a value-type incompatible with the consumer field. */
     TYPE_MISMATCH: "validation/type-mismatch",
     /** A required field is empty. */

package/dist/references.js

@@ -25,9 +25,10 @@
  */
 import { resolveFieldValueType } from "@flowget/types";
 import { resolveNodeOutputFields, resolveNodeTriggerPayload, } from "./catalog.js";
+import { buildFieldTree, resolvePath, } from "./field-tree.js";
 import { ISSUE_CODES } from "./issues.js";
 import { buildReversedAdjacency, collectUpstreamFrom } from "./reachability.js";
-import { hasForbiddenPathToken, hasTemplateExpression, isWholeStringTemplate, parseTemplate, templateExpressions, } from "./template-ast.js";
+import { hasEmptyPathSegment, 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;
@@ -39,8 +40,13 @@ export function collectReferenceIssues(graph, index) {
         triggerInfo: computeTriggerInfo(graph, index),
         adjacency: buildReversedAdjacency(graph.edges),
         upstreamCache: new Map(),
+        outputTreeCache: new Map(),
     };
     const issues = [];
+    // 0. Declaration conflicts (dotted-key contradictions) — surfaced for EVERY
+    //    node that declares them, independent of whether anything references the
+    //    field, since a contradictory declaration cannot be resolved at all.
+    collectDeclarationConflicts(graph, ctx, issues);
     for (const node of graph.nodes) {
         const def = index.get(node.type);
         const opaque = new Set(def?.opaqueFields ?? []);
@@ -138,6 +144,22 @@ function validateTemplateString(raw, isTopLevel, site, ctx, issues) {
 }
 /** Validate one operand's producer existence + reachability + declared-output. */
 function validateOperandExistence(path, tokenRaw, site, ctx, upstream, issues) {
+    // An empty/blank path segment (`trigger.`, `steps.x.output.`, `a..b`) — the
+    // engine resolver throws `missing_path` / `missing_step` on it UNCONDITIONALLY
+    // (input-independent), so mirror that with a hard error. Grammar-level, like
+    // the forbidden-token guard, so it fires independent of catalog declarations
+    // and BEFORE the namespace/existence logic. Reached only for a single-operand
+    // expression (a `??` chain rescues the throw → flagging inside one is an FP).
+    if (hasEmptyPathSegment(path)) {
+        issues.push({
+            code: ISSUE_CODES.TEMPLATE_EMPTY_SEGMENT,
+            severity: "error",
+            nodeId: site.node.id,
+            fieldKey: site.fieldKey,
+            message: `Node "${site.node.id}" template "${tokenRaw}" has an empty path segment (a leading, trailing, or doubled dot) and will be rejected at runtime.`,
+        });
+        return;
+    }
     if (path.kind === "v1-reserved") {
         const ns = path.segments[0];
         // `workflow.*` / `input.*` are opaque execution primitives — permissive.
@@ -154,18 +176,19 @@ function validateOperandExistence(path, tokenRaw, site, ctx, upstream, issues) {
         issues.push(reachIssue);
         return;
     }
-    // Declared-output check on the canonical envelope only.
-    //  - v2-step: `steps.<id>.output.<key>` (segments[2] === "output").
+    // Declared-output check on the canonical envelope only, resolving the WHOLE
+    // drill-in path (dotted output keys are nested paths — see `field-tree.ts`).
+    //  - v2-step: `steps.<id>.output.<path…>` (segments[2] === "output").
     //             `steps.<id>.decorators.…` and other shapes are permissive.
-    //  - v1-step: `<id>.<field>` maps to `output.<field>`.
+    //  - v1-step: `<id>.<path…>` maps to `output.<path…>`.
     if (path.kind === "v2-step") {
         if (path.segments[2] === "output" && path.segments.length >= 4) {
-            checkOutputKey(producerId, path.segments[3], tokenRaw, site, ctx, issues);
+            checkOutputPath(producerId, path.segments.slice(3), tokenRaw, site, ctx, issues);
         }
         return;
     }
     if (path.segments.length >= 2) {
-        checkOutputKey(producerId, path.segments[1], tokenRaw, site, ctx, issues);
+        checkOutputPath(producerId, path.segments.slice(1), tokenRaw, site, ctx, issues);
     }
 }
 function checkProducerReachable(producerId, tokenRaw, site, ctx, upstream) {
@@ -189,9 +212,14 @@ function checkProducerReachable(producerId, tokenRaw, site, ctx, upstream) {
     }
     return null;
 }
-function checkOutputKey(producerId, key, tokenRaw, site, ctx, issues) {
-    if (key === undefined || key === "")
-        return;
+/**
+ * Resolve a drill-in path against a producer's declared-output tree and emit
+ * the reference verdict: an unknown TOP-LEVEL output key is a hard error
+ * (unchanged pre-nesting behavior); an undeclared CHILD of a known
+ * nested-object output is an advisory warning (the value may still exist at
+ * run time); a known path / drill-through-a-leaf / no-declarations is silent.
+ */
+function checkOutputPath(producerId, pathSegments, tokenRaw, site, ctx, issues) {
     const producer = ctx.nodeById.get(producerId);
     if (producer === undefined)
         return;
@@ -200,35 +228,96 @@ function checkOutputKey(producerId, key, tokenRaw, site, ctx, issues) {
     // 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}".`,
-        });
-    }
+    const tree = getOutputTree(producerId, ctx);
+    const resolution = resolvePath(tree, pathSegments);
+    emitResolutionIssue(resolution, site, issues, (topKey) => `Node "${site.node.id}" references "${tokenRaw}", but "${producerId}" declares no output "${topKey}".`, (childPath, siblings) => `Node "${site.node.id}" references "${tokenRaw}", but "${producerId}" output declares no "${childPath}" (declared: ${siblings}). It may still resolve if the value carries it.`);
 }
 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)) {
+    const resolution = resolvePath(info.tree, path.segments.slice(1));
+    emitResolutionIssue(resolution, site, issues, (topKey) => `Node "${site.node.id}" references "${tokenRaw}", but no trigger declares a payload field "${topKey}".`, (childPath, siblings) => `Node "${site.node.id}" references "${tokenRaw}", but no trigger payload declares "${childPath}" (declared: ${siblings}). It may still resolve if the event payload carries it.`);
+}
+/**
+ * Turn a {@link PathResolution} into an issue (or nothing). `unknown-root` →
+ * hard error via `unknownRootMessage`; `undeclared-child` → advisory warning
+ * via `undeclaredChildMessage`; everything else is silent.
+ */
+function emitResolutionIssue(resolution, site, issues, unknownRootMessage, undeclaredChildMessage) {
+    if (resolution.kind === "unknown-root") {
         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}".`,
+            message: unknownRootMessage(resolution.rootKey),
+        });
+        return;
+    }
+    if (resolution.kind === "undeclared-child") {
+        const childPath = `${resolution.parentPath}.${resolution.childKey}`;
+        const siblings = [...resolution.declaredSiblings].sort().join(", ");
+        issues.push({
+            code: ISSUE_CODES.TEMPLATE_UNDECLARED_CHILD,
+            severity: "warning",
+            nodeId: site.node.id,
+            fieldKey: site.fieldKey,
+            message: undeclaredChildMessage(childPath, siblings),
+        });
+    }
+}
+/** Get (building + caching once) a producer's declared-output prefix tree. */
+function getOutputTree(producerId, ctx) {
+    let tree = ctx.outputTreeCache.get(producerId);
+    if (tree === undefined) {
+        tree = buildFieldTree(resolveProducerOutputs(producerId, ctx));
+        ctx.outputTreeCache.set(producerId, tree);
+    }
+    return tree;
+}
+/** A producer node's resolved output fields (`[]` for unknown / decorator). */
+function resolveProducerOutputs(producerId, ctx) {
+    const producer = ctx.nodeById.get(producerId);
+    if (producer === undefined)
+        return [];
+    const def = ctx.index.get(producer.type);
+    if (def === undefined || def.category === "decorator")
+        return [];
+    return resolveNodeOutputFields(def, producer.data ?? {});
+}
+/**
+ * Emit a {@link ISSUE_CODES.FIELD_PATH_CONFLICT} error for every node whose
+ * declared output / trigger-payload keys contain a dotted-key contradiction (a
+ * key that is both a concrete scalar and a nested-object parent). Reported
+ * independent of any reference, because such a declaration cannot be resolved.
+ */
+function collectDeclarationConflicts(graph, ctx, issues) {
+    for (const node of graph.nodes) {
+        const def = ctx.index.get(node.type);
+        if (def === undefined)
+            continue;
+        // Output surface — reuse the cached per-producer tree.
+        if (def.category !== "decorator") {
+            pushConflicts(getOutputTree(node.id, ctx), node.id, "output", issues);
+        }
+        // Trigger-payload surface — a distinct declared list from `output`.
+        if (def.category === "trigger") {
+            const payload = resolveNodeTriggerPayload(def, node.data ?? {});
+            pushConflicts(buildFieldTree(payload), node.id, "trigger payload", issues);
+        }
+    }
+}
+function pushConflicts(tree, nodeId, surface, issues) {
+    for (const conflict of tree.contradictions) {
+        issues.push({
+            code: ISSUE_CODES.FIELD_PATH_CONFLICT,
+            severity: "error",
+            nodeId,
+            fieldKey: conflict.path,
+            message: `Node "${nodeId}" declares ${surface} "${conflict.path}" as ${conflict.scalarType}, but a dotted sibling key uses it as a nested object — a field key cannot be both a ${conflict.scalarType} and an object.`,
         });
     }
 }
@@ -282,8 +371,8 @@ function getUpstream(nodeId, ctx) {
 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 mergedFields = [];
+    // `null` marks a TOP-LEVEL key whose type is ambiguous across triggers.
     const keyTypes = new Map();
     for (const node of graph.nodes) {
         const def = index.get(node.type);
@@ -296,7 +385,11 @@ function computeTriggerInfo(graph, index) {
             continue;
         }
         for (const f of payload) {
-            keys.add(f.key);
+            mergedFields.push(f);
+            // Only FLAT (dot-free) keys feed the whole-string type-compat lattice —
+            // nested-leaf type-compat is deferred (see `producerValueType`).
+            if (f.key.includes("."))
+                continue;
             if (!keyTypes.has(f.key))
                 keyTypes.set(f.key, f.type);
             else if (keyTypes.get(f.key) !== f.type)
@@ -308,5 +401,12 @@ function computeTriggerInfo(graph, index) {
         if (v !== null)
             finalTypes.set(k, v);
     }
-    return { hasTrigger, allKnown, keys, keyTypes: finalTypes };
+    // The merged tree is for reference resolution only; per-node contradictions
+    // are reported separately (see `collectDeclarationConflicts`).
+    return {
+        hasTrigger,
+        allKnown,
+        tree: buildFieldTree(mergedFields),
+        keyTypes: finalTypes,
+    };
 }

package/dist/template-ast.d.ts

@@ -43,6 +43,16 @@ export declare function isReservedNamespace(token: string): boolean;
 export declare const FORBIDDEN_PATH_TOKENS: ReadonlySet<string>;
 /** `true` iff any segment of `path` is a forbidden prototype-chain token. */
 export declare function hasForbiddenPathToken(path: TemplatePath): boolean;
+/**
+ * `true` iff `path` has an empty/blank segment — a leading, trailing, or
+ * doubled dot (`trigger.`, `.foo`, `a..b`, `steps.x.output.`). `PATH_RE`
+ * (`^[\w.-]+$`) admits these, but the engine resolver throws
+ * `missing_path` / `missing_step` on an empty token unconditionally
+ * (input-independent), so a static verdict treats them as invalid. This is a
+ * grammar-level property (like {@link hasForbiddenPathToken}), independent of
+ * any catalog declaration.
+ */
+export declare function hasEmptyPathSegment(path: TemplatePath): boolean;
 /**
  * Defensive upper bound on a template-bearing string. Beyond this the
  * string is treated as a single literal (no token scan) — a belt-and-

package/dist/template-ast.js

@@ -54,6 +54,18 @@ export const FORBIDDEN_PATH_TOKENS = new Set([
 export function hasForbiddenPathToken(path) {
     return path.segments.some((s) => FORBIDDEN_PATH_TOKENS.has(s));
 }
+/**
+ * `true` iff `path` has an empty/blank segment — a leading, trailing, or
+ * doubled dot (`trigger.`, `.foo`, `a..b`, `steps.x.output.`). `PATH_RE`
+ * (`^[\w.-]+$`) admits these, but the engine resolver throws
+ * `missing_path` / `missing_step` on an empty token unconditionally
+ * (input-independent), so a static verdict treats them as invalid. This is a
+ * grammar-level property (like {@link hasForbiddenPathToken}), independent of
+ * any catalog declaration.
+ */
+export function hasEmptyPathSegment(path) {
+    return path.segments.some((s) => s === "");
+}
 /**
  * Defensive upper bound on a template-bearing string. Beyond this the
  * string is treated as a single literal (no token scan) — a belt-and-

package/dist/trigger-inputs.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Run-input validation — the SHARED, path-aware "does the run input carry every
+ * `{{ trigger.<path> }}` the graph references?" gate.
+ *
+ * Both consumers feed the SAME graph + catalog + input into
+ * {@link validateTriggerInputs}, so their verdict is equal by construction:
+ *
+ *   - the **builder** passes the `<RunTestDialog>` test-input JSON;
+ *   - the **worker** passes the real event payload at pre-flight.
+ *
+ * Under the strict runtime resolver a `{{ trigger.<path> }}` whose value is
+ * absent from the payload throws a nonRetryable `missing_path` — so catching it
+ * here refuses the run up front instead of failing mid-execution.
+ *
+ * ## Zero false positives (matches the reference walker's discipline)
+ *
+ *   - **Reference-driven** — only a field the graph actually references is
+ *     checked. An unreferenced declared payload field is harmless and never
+ *     flagged.
+ *   - **Single-operand only** — a `{{ a ?? b }}` fallback chain RESCUES a
+ *     missing operand at run time (the engine falls through), so only a lone
+ *     `{{ trigger.<path> }}` operand can be "required".
+ *   - **Opaque fields skipped** — never template-resolved by the engine.
+ *   - **Forbidden tokens skipped** — a `__proto__` / `constructor` / `prototype`
+ *     path is a separate graph error, not a missing-input.
+ *   - **Own-key presence, path-aware** — presence is decided by `Object.hasOwn`
+ *     at EACH segment of the dotted path (`payment.amount` checks
+ *     `input.payment` then `.amount`). A provided-but-`null` value is present
+ *     (not flagged); a path that cannot descend (a non-object mid-path) is
+ *     missing, exactly as the resolver would throw.
+ *
+ * This is `input`-shape-agnostic: it never inspects declared payload types, so
+ * the identical function serves a seeded test object and a live event payload.
+ * (Leaf type-compat on nested paths is deferred — this gate is existence only.)
+ *
+ * **Depth boundary.** Config traversal stops at {@link MAX_DATA_DEPTH} (a
+ * deliberate stack-overflow-DoS guard on untrusted input). A `{{ trigger.… }}`
+ * nested deeper than that in `node.data` is not pre-checked here; it stays
+ * backstopped by the runtime resolver's non-retryable `missing_path` throw.
+ */
+import type { WorkflowGraph } from "@flowget/types";
+import { type CatalogNode } from "./catalog.js";
+import { type ValidationIssue } from "./issues.js";
+/**
+ * Flag every `{{ trigger.<path> }}` the graph references that the run `input`
+ * does not provide.
+ *
+ * @param graph   The `@flowget/types` `WorkflowGraph`.
+ * @param catalog The node definitions (a `readonly CatalogNode[]`, the same
+ *                structural subset {@link validateGraphStatic} accepts) — read
+ *                only for each node's `opaqueFields`.
+ * @param input   The run input: the builder's test-input object, or the
+ *                worker's real event payload. A genuinely nested object
+ *                (`{ payment: { amount } }`), never flat dotted keys.
+ * @returns       One `error` per referenced-but-absent trigger path, ordered
+ *                deterministically, with stable ids.
+ */
+export declare function validateTriggerInputs(graph: WorkflowGraph, catalog: readonly CatalogNode[], input: Readonly<Record<string, unknown>>): ValidationIssue[];
+/**
+ * The set of trigger-payload PATHS (dotted, e.g. `"payment.amount"`) the graph
+ * references via a single-operand `{{ trigger.<path> }}` template — the refs
+ * that genuinely throw `missing_path` at run time when the path is absent from
+ * the payload. This is the shared home for the walk the builder previously
+ * re-implemented; the worker consumes it too.
+ */
+export declare function collectReferencedTriggerPaths(graph: WorkflowGraph, catalog: readonly CatalogNode[]): ReadonlySet<string>;

package/dist/trigger-inputs.js

@@ -0,0 +1,178 @@
+/**
+ * Run-input validation — the SHARED, path-aware "does the run input carry every
+ * `{{ trigger.<path> }}` the graph references?" gate.
+ *
+ * Both consumers feed the SAME graph + catalog + input into
+ * {@link validateTriggerInputs}, so their verdict is equal by construction:
+ *
+ *   - the **builder** passes the `<RunTestDialog>` test-input JSON;
+ *   - the **worker** passes the real event payload at pre-flight.
+ *
+ * Under the strict runtime resolver a `{{ trigger.<path> }}` whose value is
+ * absent from the payload throws a nonRetryable `missing_path` — so catching it
+ * here refuses the run up front instead of failing mid-execution.
+ *
+ * ## Zero false positives (matches the reference walker's discipline)
+ *
+ *   - **Reference-driven** — only a field the graph actually references is
+ *     checked. An unreferenced declared payload field is harmless and never
+ *     flagged.
+ *   - **Single-operand only** — a `{{ a ?? b }}` fallback chain RESCUES a
+ *     missing operand at run time (the engine falls through), so only a lone
+ *     `{{ trigger.<path> }}` operand can be "required".
+ *   - **Opaque fields skipped** — never template-resolved by the engine.
+ *   - **Forbidden tokens skipped** — a `__proto__` / `constructor` / `prototype`
+ *     path is a separate graph error, not a missing-input.
+ *   - **Own-key presence, path-aware** — presence is decided by `Object.hasOwn`
+ *     at EACH segment of the dotted path (`payment.amount` checks
+ *     `input.payment` then `.amount`). A provided-but-`null` value is present
+ *     (not flagged); a path that cannot descend (a non-object mid-path) is
+ *     missing, exactly as the resolver would throw.
+ *
+ * This is `input`-shape-agnostic: it never inspects declared payload types, so
+ * the identical function serves a seeded test object and a live event payload.
+ * (Leaf type-compat on nested paths is deferred — this gate is existence only.)
+ *
+ * **Depth boundary.** Config traversal stops at {@link MAX_DATA_DEPTH} (a
+ * deliberate stack-overflow-DoS guard on untrusted input). A `{{ trigger.… }}`
+ * nested deeper than that in `node.data` is not pre-checked here; it stays
+ * backstopped by the runtime resolver's non-retryable `missing_path` throw.
+ */
+import { indexCatalog } from "./catalog.js";
+import { finalizeIssues, ISSUE_CODES, } from "./issues.js";
+import { hasForbiddenPathToken, hasTemplateExpression, parseTemplate, templateExpressions, } from "./template-ast.js";
+/**
+ * Bound on nested-config recursion — mirrors the reference walker's deliberate
+ * stack-overflow-DoS guard (config values arrive from untrusted input).
+ *
+ * **Parity boundary (intentional, stated):** the engine's runtime template walk
+ * is UNcapped, so a `{{ trigger.<path> }}` buried in `node.data` nested deeper
+ * than this is not collected here and its input is not pre-checked. That
+ * reference is backstopped by the runtime resolver's non-retryable
+ * `missing_path` throw — so a genuinely-missing deep input still fails the run
+ * safely, just at execution rather than pre-flight. Matching the engine's
+ * uncapped walk (removing this guard) would re-expose the DoS and is a separate
+ * cross-repo decision, not this gate's.
+ */
+const MAX_DATA_DEPTH = 64;
+/**
+ * Flag every `{{ trigger.<path> }}` the graph references that the run `input`
+ * does not provide.
+ *
+ * @param graph   The `@flowget/types` `WorkflowGraph`.
+ * @param catalog The node definitions (a `readonly CatalogNode[]`, the same
+ *                structural subset {@link validateGraphStatic} accepts) — read
+ *                only for each node's `opaqueFields`.
+ * @param input   The run input: the builder's test-input object, or the
+ *                worker's real event payload. A genuinely nested object
+ *                (`{ payment: { amount } }`), never flat dotted keys.
+ * @returns       One `error` per referenced-but-absent trigger path, ordered
+ *                deterministically, with stable ids.
+ */
+export function validateTriggerInputs(graph, catalog, input) {
+    const referenced = collectReferencedTriggerPaths(graph, catalog);
+    const raw = [];
+    // Sorted for a deterministic, stable issue order across runs.
+    for (const path of [...referenced].sort()) {
+        if (inputHasPath(input, path.split(".")))
+            continue;
+        raw.push({
+            code: ISSUE_CODES.RUN_INPUT_MISSING,
+            severity: "error",
+            fieldKey: path,
+            message: `This workflow references \`trigger.${path}\`, but the run input doesn't provide it.`,
+        });
+    }
+    return finalizeIssues(raw);
+}
+/**
+ * The set of trigger-payload PATHS (dotted, e.g. `"payment.amount"`) the graph
+ * references via a single-operand `{{ trigger.<path> }}` template — the refs
+ * that genuinely throw `missing_path` at run time when the path is absent from
+ * the payload. This is the shared home for the walk the builder previously
+ * re-implemented; the worker consumes it too.
+ */
+export function collectReferencedTriggerPaths(graph, catalog) {
+    const index = indexCatalog(catalog);
+    const paths = new Set();
+    for (const node of graph.nodes) {
+        const def = index.get(node.type);
+        const opaque = new Set(def?.opaqueFields ?? []);
+        for (const [fieldKey, value] of Object.entries(node.data ?? {})) {
+            if (opaque.has(fieldKey))
+                continue;
+            collectFromValue(value, 0, paths);
+        }
+    }
+    return paths;
+}
+/** Recursively descend a config value, harvesting trigger paths at string leaves. */
+function collectFromValue(value, depth, paths) {
+    if (typeof value === "string") {
+        collectFromString(value, paths);
+        return;
+    }
+    if (depth >= MAX_DATA_DEPTH)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectFromValue(item, depth + 1, paths);
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value)) {
+            collectFromValue(child, depth + 1, paths);
+        }
+    }
+}
+/** Harvest single-operand `{{ trigger.<path> }}` dotted paths from one string. */
+function collectFromString(raw, paths) {
+    const ast = parseTemplate(raw);
+    if (!hasTemplateExpression(ast))
+        return;
+    for (const { expression } of templateExpressions(ast)) {
+        // A `??` chain RESCUES a missing operand at run time — only a lone operand
+        // can be genuinely required. Checking one inside a chain is a false positive.
+        if (expression.operands.length !== 1)
+            continue;
+        const operand = expression.operands[0];
+        if (operand === undefined)
+            continue;
+        if (operand.kind !== "v1-reserved" || operand.segments[0] !== "trigger") {
+            continue;
+        }
+        if (hasForbiddenPathToken(operand))
+            continue; // separate graph error
+        // The drill-in path AFTER `trigger` — the full dotted path, so nested
+        // leaves (`payment.amount`) are checked at leaf granularity.
+        const pathSegments = operand.segments.slice(1);
+        if (pathSegments.length === 0)
+            continue;
+        // An empty segment (a malformed leading/trailing/doubled dot,
+        // `{{ trigger. }}`) is NOT the run-input gate's concern — a malformed path
+        // names no input key, so `validateGraphStatic`'s reference walker owns
+        // flagging it (TEMPLATE_EMPTY_SEGMENT), and the runtime throws on it
+        // unconditionally regardless. Skipping keeps this gate purely about
+        // referenced-vs-provided.
+        if (pathSegments.some((s) => s === ""))
+            continue;
+        paths.add(pathSegments.join("."));
+    }
+}
+/**
+ * `true` iff `input` carries the whole dotted path by own-key membership at
+ * each level. A present-but-`null` LEAF counts as present (its value was
+ * supplied); a non-object encountered MID-path means the deeper segment cannot
+ * resolve → absent, exactly as the strict resolver would throw.
+ */
+function inputHasPath(input, segments) {
+    let current = input;
+    for (const seg of segments) {
+        if (current === null || typeof current !== "object")
+            return false;
+        if (!Object.hasOwn(current, seg))
+            return false;
+        current = current[seg];
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowget/graph-validation",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Isomorphic, zero-runtime-dependency static validator for Flowget workflow graphs — the single source of validation logic so the builder's pre-submit verdict and the worker's pre-flight verdict are equal by construction. Template-grammar classifier, reference/reachability walker, coarse value-type lattice, and declarative field rules.",
   "keywords": [
     "flowget",