@flowget/graph-validation 0.1.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Flowget
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,71 @@
+# @flowget/graph-validation
+
+Isomorphic, zero-runtime-dependency **static validator** for Flowget workflow
+graphs.
+
+This is the **single source of validation logic** shared by the Flowget
+builder (design-time, pre-submit) and the Flowget worker (host-side,
+pre-flight). Because both call the exact same pure functions over the exact
+same `(graph, catalog)` input, the builder's verdict and the worker's verdict
+are **equal by construction** — a graph the builder accepts is a graph the
+worker accepts.
+
+> **Contingency.** "Equal by construction" holds *given both consumers feed
+> catalogs derived from the same node-definition source.* Catalog
+> `outputFields` / `triggerPayload` / `options` can be **factory functions** —
+> code, not data — so this package guarantees the validation *function* is
+> identical, not that the two sides' catalog *inputs* are. Keeping those
+> definitions in sync is the job of the shared registry and the
+> `compareFieldCoherence` boot check, not of this validator.
+
+What it does:
+
+- **Template-grammar classifier** — parses `{{ … }}` template strings into the
+  `@flowget/types` `TemplateAst` (v2-step / v1-reserved / v1-step operands,
+  `??` 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.
+- **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).
+- **Declarative field rules** — `required`, coarse type, enum membership,
+  `min` / `max` / `pattern`.
+- **`validateGraphStatic(graph, catalog)`** — the aggregator, returning a flat
+  `ValidationIssue[]`.
+
+## Install
+
+```sh
+npm install @flowget/graph-validation
+```
+
+`@flowget/types` is a peer dependency (`>=0.5.0 <1.0.0`) — install it too if it
+is not already in your tree.
+
+## Usage
+
+```ts
+import { validateGraphStatic } from "@flowget/graph-validation";
+
+const issues = validateGraphStatic(graph, catalog);
+
+const blocking = issues.filter((i) => i.severity === "error");
+if (blocking.length > 0) {
+  // builder: disable the Run button; worker: refuse the pre-flight
+}
+```
+
+`graph` is a `@flowget/types` `WorkflowGraph`; `catalog` is the list of node
+definitions (structurally a subset of `NodeMetadata<BuilderHints>`), fed
+identically by both consumers.
+
+## ⚠️ 0.x is unstable
+
+This package is on the `0.x` line. The surface may change in breaking ways
+between `0.x` minors until `1.0.0` (`0.x` semver: minor = breaking, patch =
+additive). Pin a caret range and read the `CHANGELOG` before upgrading.
+
+## Links
+
+- Docs: https://docs.flowget.io
+- Contract types: [`@flowget/types`](https://github.com/flowgethq/types)

package/dist/catalog.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The INPUT interface — the catalog half of `validateGraphStatic(graph,
+ * catalog)`. Defined so the builder and the worker feed the validator
+ * IDENTICALLY: both already hold `NodeMetadata<BuilderHints>` objects, and
+ * {@link CatalogNode} is a structural SUBSET of that shape, so each side
+ * passes its existing catalog list unchanged (structural typing → assignable).
+ * The `@flowget/types` `WorkflowGraph` is the graph half.
+ *
+ * The output-field / trigger-payload resolution below is lifted from the
+ * builder's `variables.ts` engine (the `outputVariants` → factory → static
+ * precedence) so the "referenceable set" the validator computes is
+ * byte-for-byte the set the builder's variable picker offers — reference
+ * validity is equal to picker availability BY CONSTRUCTION.
+ */
+import type { ConfigField, NodeCategory, OutputField, OutputVariants } from "@flowget/types";
+/**
+ * A single catalog entry the validator reads. STRUCTURAL SUBSET of
+ * `NodeMetadata<BuilderHints>` — every field is optional except `id`, so a
+ * consumer's richer catalog object is assignable to it without adaptation.
+ * The complete-shape compile-time proof of that assignability lives in
+ * `catalog.types-test.ts` (a tsc-only pin, not run by vitest, not published).
+ */
+export interface CatalogNode {
+    /** Registry lookup key — matched against `WorkflowNode.type`. */
+    id: string;
+    /** Walker behavior + trigger/decorator gates. `"trigger"` marks an entrypoint. */
+    category?: NodeCategory;
+    /** Declarative config-form schema — the fields whose values field-rules validate. */
+    fields?: readonly ConfigField[];
+    /**
+     * Output fields the node produces under `output.<key>` — the reference
+     * walker's producer surface. Static array OR a pure `(config)=>fields`
+     * factory (config-dependent shapes, e.g. `switch`).
+     */
+    outputFields?: readonly OutputField[] | ((config: Record<string, unknown>) => readonly OutputField[]);
+    /** Reserved `{{ trigger.<key> }}` payload — only `category: "trigger"` nodes populate it. */
+    triggerPayload?: readonly OutputField[] | ((config: Record<string, unknown>) => readonly OutputField[]);
+    /** Declarative, JSON-serializable variant output (precedence over the static forms). */
+    outputVariants?: OutputVariants;
+    /** Field keys NEVER template-resolved by the walker — skipped by reference validation. */
+    opaqueFields?: readonly string[];
+    /** Decorator-host allow-list (surfaced for completeness; not yet enforced by the walker). */
+    allowedDecorators?: readonly string[];
+}
+/** An indexed catalog: node-type id → {@link CatalogNode}. */
+export type CatalogIndex = ReadonlyMap<string, CatalogNode>;
+/**
+ * Build the type-id → node index. On a duplicate id the FIRST wins (stable,
+ * deterministic) — matches the builder's `catalog.list().find(...)` and the
+ * worker's registry "first registration wins".
+ */
+export declare function indexCatalog(catalog: readonly CatalogNode[]): CatalogIndex;
+/**
+ * The node's output fields for a given instance `config`, honoring
+ * `outputVariants` precedence over the static / factory `outputFields`.
+ * Faithful port of `variables.ts`'s `resolveOutputFields`.
+ */
+export declare function resolveNodeOutputFields(node: CatalogNode, config: Record<string, unknown>): readonly OutputField[];
+/**
+ * The node's trigger-payload fields for a given instance `config`, honoring
+ * `outputVariants` precedence. Faithful port of `variables.ts`'s
+ * `resolveTriggerPayload`.
+ */
+export declare function resolveNodeTriggerPayload(node: CatalogNode, config: Record<string, unknown>): readonly OutputField[];

package/dist/catalog.js

@@ -0,0 +1,89 @@
+/**
+ * The INPUT interface — the catalog half of `validateGraphStatic(graph,
+ * catalog)`. Defined so the builder and the worker feed the validator
+ * IDENTICALLY: both already hold `NodeMetadata<BuilderHints>` objects, and
+ * {@link CatalogNode} is a structural SUBSET of that shape, so each side
+ * passes its existing catalog list unchanged (structural typing → assignable).
+ * The `@flowget/types` `WorkflowGraph` is the graph half.
+ *
+ * The output-field / trigger-payload resolution below is lifted from the
+ * builder's `variables.ts` engine (the `outputVariants` → factory → static
+ * precedence) so the "referenceable set" the validator computes is
+ * byte-for-byte the set the builder's variable picker offers — reference
+ * validity is equal to picker availability BY CONSTRUCTION.
+ */
+/**
+ * Build the type-id → node index. On a duplicate id the FIRST wins (stable,
+ * deterministic) — matches the builder's `catalog.list().find(...)` and the
+ * worker's registry "first registration wins".
+ */
+export function indexCatalog(catalog) {
+    const index = new Map();
+    for (const node of catalog) {
+        if (!index.has(node.id))
+            index.set(node.id, node);
+    }
+    return index;
+}
+/**
+ * Resolve the active variant for a node whose output shape varies by a
+ * config field value. Reads `data[variantBy]`, matches a variant (coercing
+ * a non-string key to "no match"), else the `fallback` variant, else
+ * `undefined` (caller falls through to the static forms). Mirrors
+ * `variables.ts`'s `resolveVariant`.
+ */
+function resolveVariant(ov, config) {
+    const raw = config[ov.variantBy];
+    const key = typeof raw === "string" ? raw : undefined;
+    const matched = key !== undefined ? ov.variants[key] : undefined;
+    if (matched !== undefined)
+        return matched;
+    if (ov.fallback !== undefined)
+        return ov.variants[ov.fallback];
+    return undefined;
+}
+/**
+ * Invoke a `readonly OutputField[] | (config)=>readonly OutputField[]` slot,
+ * resolving the factory form against `config`. A throwing factory yields
+ * `[]` (treated as "unknown outputs" → permissive) — the validator must
+ * never crash on a hostile/half-edited config.
+ */
+function resolveFieldSlot(slot, config) {
+    if (slot === undefined)
+        return [];
+    if (typeof slot === "function") {
+        try {
+            return slot(config);
+        }
+        catch {
+            return [];
+        }
+    }
+    return slot;
+}
+/**
+ * The node's output fields for a given instance `config`, honoring
+ * `outputVariants` precedence over the static / factory `outputFields`.
+ * Faithful port of `variables.ts`'s `resolveOutputFields`.
+ */
+export function resolveNodeOutputFields(node, config) {
+    if (node.outputVariants !== undefined) {
+        const variant = resolveVariant(node.outputVariants, config);
+        if (variant !== undefined)
+            return variant.outputFields ?? [];
+    }
+    return resolveFieldSlot(node.outputFields, config);
+}
+/**
+ * The node's trigger-payload fields for a given instance `config`, honoring
+ * `outputVariants` precedence. Faithful port of `variables.ts`'s
+ * `resolveTriggerPayload`.
+ */
+export function resolveNodeTriggerPayload(node, config) {
+    if (node.outputVariants !== undefined) {
+        const variant = resolveVariant(node.outputVariants, config);
+        if (variant !== undefined)
+            return variant.triggerPayload ?? [];
+    }
+    return resolveFieldSlot(node.triggerPayload, config);
+}

package/dist/coherence.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Best-effort node.json ↔ schema coherence comparator — the helper the
+ * worker's boot-coherence check calls to catch a node whose declarative
+ * `node.json` fields have drifted from its runtime `zod` input
+ * schema (a field renamed in one place but not the other, a type widened on
+ * one side).
+ *
+ * **Zod-free by construction.** This package must never import `zod` (it has
+ * to run isomorphically, and staying schema-free is the honesty boundary the
+ * "valid" verdict rests on). The worker introspects its live `ZodObject` into
+ * a plain {@link SchemaProjection} — `key → { valueType, required }` — and
+ * passes THAT here. All the zod-specific reflection stays host-side in the
+ * worker; this comparator only diffs two coarse projections.
+ *
+ * **Best-effort.** Coarse value-types cannot see refinements, unions, or
+ * transforms, so every mismatch is advisory (a `warning`-grade signal for the
+ * worker's boot log), never a hard graph error.
+ */
+import type { ConfigField, FieldValueType } from "@flowget/types";
+/** One field of an introspected schema, projected onto the coarse lattice. */
+export type SchemaFieldProjection = {
+    /** Coarse value-type of the schema field, if determinable. */
+    valueType?: FieldValueType;
+    /** Whether the schema requires the field (a non-optional key). */
+    required?: boolean;
+};
+/** A whole introspected input schema, projected: field key → {@link SchemaFieldProjection}. */
+export type SchemaProjection = Record<string, SchemaFieldProjection>;
+/** The kind of coherence drift found between a node's `node.json` and its schema. */
+export type CoherenceMismatchKind = "missing-in-schema" | "missing-in-fields" | "type-drift" | "required-drift";
+/** One best-effort coherence finding. Advisory — never a hard graph error. */
+export type CoherenceMismatch = {
+    fieldKey: string;
+    kind: CoherenceMismatchKind;
+    message: string;
+};
+/**
+ * Diff a node's declarative `fields` (`node.json`) against an introspected
+ * `schema` projection, returning best-effort coherence mismatches:
+ *
+ *   - `missing-in-schema` — `node.json` declares a field the schema omits.
+ *   - `missing-in-fields` — the schema requires a field `node.json` omits
+ *     (an optional schema key is NOT flagged — a node need not surface every
+ *     optional input as an editable field).
+ *   - `type-drift` — both sides declare the field with DIFFERENT concrete
+ *     value-types (coarse lattice; wildcards never drift).
+ *   - `required-drift` — required on one side, optional on the other.
+ *
+ * Deterministic: findings are emitted in `fields` order, then in `schema`
+ * key-insertion order. No `Date` / random.
+ */
+export declare function compareFieldCoherence(fields: readonly ConfigField[], schema: SchemaProjection): CoherenceMismatch[];

package/dist/coherence.js

@@ -0,0 +1,94 @@
+/**
+ * Best-effort node.json ↔ schema coherence comparator — the helper the
+ * worker's boot-coherence check calls to catch a node whose declarative
+ * `node.json` fields have drifted from its runtime `zod` input
+ * schema (a field renamed in one place but not the other, a type widened on
+ * one side).
+ *
+ * **Zod-free by construction.** This package must never import `zod` (it has
+ * to run isomorphically, and staying schema-free is the honesty boundary the
+ * "valid" verdict rests on). The worker introspects its live `ZodObject` into
+ * a plain {@link SchemaProjection} — `key → { valueType, required }` — and
+ * passes THAT here. All the zod-specific reflection stays host-side in the
+ * worker; this comparator only diffs two coarse projections.
+ *
+ * **Best-effort.** Coarse value-types cannot see refinements, unions, or
+ * transforms, so every mismatch is advisory (a `warning`-grade signal for the
+ * worker's boot log), never a hard graph error.
+ */
+import { resolveFieldValueType } from "@flowget/types";
+import { isAssignable, isConcreteScalar } from "./value-type.js";
+/**
+ * Diff a node's declarative `fields` (`node.json`) against an introspected
+ * `schema` projection, returning best-effort coherence mismatches:
+ *
+ *   - `missing-in-schema` — `node.json` declares a field the schema omits.
+ *   - `missing-in-fields` — the schema requires a field `node.json` omits
+ *     (an optional schema key is NOT flagged — a node need not surface every
+ *     optional input as an editable field).
+ *   - `type-drift` — both sides declare the field with DIFFERENT concrete
+ *     value-types (coarse lattice; wildcards never drift).
+ *   - `required-drift` — required on one side, optional on the other.
+ *
+ * Deterministic: findings are emitted in `fields` order, then in `schema`
+ * key-insertion order. No `Date` / random.
+ */
+export function compareFieldCoherence(fields, schema) {
+    const mismatches = [];
+    const fieldKeys = new Set(fields.map((f) => f.key));
+    for (const field of fields) {
+        const projected = schema[field.key];
+        if (projected === undefined) {
+            mismatches.push({
+                fieldKey: field.key,
+                kind: "missing-in-schema",
+                message: `node.json declares field "${field.key}" but the schema has no such key.`,
+            });
+            continue;
+        }
+        // "Author-may-tighten": node.json is coherent with the schema when its
+        // value-type is EQUAL or MORE SPECIFIC — the author may narrow, not
+        // contradict. `isAssignable(nodeJson, schema)` encodes exactly that:
+        //   - `date` node.json vs `string` schema → coherent (`date ⊆ string`;
+        //     dates are JSON strings, so `z.string()` is the real date schema),
+        //   - `object` / `array` node.json vs `unknown` schema → coherent
+        //     (wildcard schema absorbs anything),
+        //   - only two DISJOINT concrete scalars (e.g. `number` vs `string`) drift.
+        const fieldType = resolveFieldValueType(field);
+        const schemaType = projected.valueType;
+        if (schemaType !== undefined &&
+            isConcreteScalar(fieldType) &&
+            isConcreteScalar(schemaType) &&
+            !isAssignable(fieldType, schemaType)) {
+            mismatches.push({
+                fieldKey: field.key,
+                kind: "type-drift",
+                message: `field "${field.key}" is ${fieldType} in node.json but ${schemaType} in the schema.`,
+            });
+        }
+        // A field required by node.json but optional in the schema (or vice
+        // versa) is a real authoring drift worth surfacing.
+        if (projected.required !== undefined &&
+            Boolean(field.required) !== projected.required) {
+            mismatches.push({
+                fieldKey: field.key,
+                kind: "required-drift",
+                message: `field "${field.key}" required=${Boolean(field.required)} in node.json but required=${projected.required} in the schema.`,
+            });
+        }
+    }
+    for (const key of Object.keys(schema)) {
+        if (fieldKeys.has(key))
+            continue;
+        // Only a REQUIRED schema key missing from node.json is a real gap — an
+        // optional input need not be an editable field.
+        if (schema[key]?.required === true) {
+            mismatches.push({
+                fieldKey: key,
+                kind: "missing-in-fields",
+                message: `the schema requires "${key}" but node.json declares no such field.`,
+            });
+        }
+    }
+    return mismatches;
+}

package/dist/field-rules.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Declarative field-rule validators — the "field layer" the strict
+ * two-layer validation epic adds ahead of each node's imperative
+ * `validate?(config)` hook. Reads the catalog `ConfigField` declarations and
+ * checks a node's `data` against them: `required`, coarse value-type, enum
+ * membership (`select`), and `min` / `max` / `pattern` bounds.
+ *
+ * CONSERVATIVE by design — every check skips template values (their runtime
+ * value is unknown), skips hidden fields (`showWhen`), and fires only on a
+ * certain, unambiguous violation. The coarse type check deliberately covers
+ * only `number` / `boolean` fields (a `string` / `date` field accepts almost
+ * any stringifiable literal, so checking it would risk false positives).
+ */
+import type { WorkflowGraph } from "@flowget/types";
+import type { CatalogIndex } from "./catalog.js";
+import { type RawIssue } from "./issues.js";
+/** Collect every field-rule issue across the graph. */
+export declare function collectFieldRuleIssues(graph: WorkflowGraph, index: CatalogIndex): RawIssue[];

package/dist/field-rules.js

@@ -0,0 +1,183 @@
+/**
+ * Declarative field-rule validators — the "field layer" the strict
+ * two-layer validation epic adds ahead of each node's imperative
+ * `validate?(config)` hook. Reads the catalog `ConfigField` declarations and
+ * checks a node's `data` against them: `required`, coarse value-type, enum
+ * membership (`select`), and `min` / `max` / `pattern` bounds.
+ *
+ * CONSERVATIVE by design — every check skips template values (their runtime
+ * value is unknown), skips hidden fields (`showWhen`), and fires only on a
+ * certain, unambiguous violation. The coarse type check deliberately covers
+ * only `number` / `boolean` fields (a `string` / `date` field accepts almost
+ * any stringifiable literal, so checking it would risk false positives).
+ */
+import { resolveFieldValueType } from "@flowget/types";
+import { ISSUE_CODES } from "./issues.js";
+import { hasTemplateExpression, parseTemplate } from "./template-ast.js";
+/**
+ * Skip a `pattern` test on values longer than this. This BOUNDS the input
+ * length a `pattern` regex scans — it does NOT prevent catastrophic
+ * backtracking (an exponential author regex like `(a+)+$` blows up at ~30
+ * chars regardless of the cap). Backtracking-safety is an author concern; see
+ * {@link compilePattern}.
+ */
+const MAX_PATTERN_VALUE_LENGTH = 10_000;
+/** Collect every field-rule issue across the graph. */
+export function collectFieldRuleIssues(graph, index) {
+    const issues = [];
+    for (const node of graph.nodes) {
+        const def = index.get(node.type);
+        if (def?.fields === undefined)
+            continue; // unknown type / no fields — nothing to check
+        const data = (node.data ?? {});
+        for (const field of def.fields) {
+            if (!isFieldVisible(field, data))
+                continue;
+            validateField(field, data, node.id, issues);
+        }
+    }
+    return issues;
+}
+function validateField(field, data, nodeId, issues) {
+    const value = data[field.key];
+    if (field.required === true && isEmpty(value)) {
+        issues.push(fieldIssue(ISSUE_CODES.FIELD_REQUIRED, nodeId, field, "is required."));
+        return; // nothing else to check on an empty value
+    }
+    if (isEmpty(value))
+        return;
+    // A template value resolves at runtime — its concrete value is unknown, so
+    // literal-value checks are skipped (reference validity is checked elsewhere).
+    if (typeof value === "string" && hasTemplateExpression(parseTemplate(value))) {
+        return;
+    }
+    const valueType = resolveFieldValueType(field);
+    // Coarse type check — only the unambiguous scalar widgets.
+    if (valueType === "number" && !isCoarseNumber(value)) {
+        issues.push(fieldIssue(ISSUE_CODES.FIELD_TYPE, nodeId, field, "expects a number value."));
+    }
+    else if (valueType === "boolean" && !isCoarseBoolean(value)) {
+        issues.push(fieldIssue(ISSUE_CODES.FIELD_TYPE, nodeId, field, "expects a boolean value."));
+    }
+    // Enum membership — `select` only (single-value). `multiselect` is skipped.
+    if (field.type === "select" && typeof value === "string") {
+        const options = resolveOptions(field, data);
+        if (options !== undefined && options.length > 0) {
+            const allowed = new Set(options.map((o) => o.value));
+            if (!allowed.has(value)) {
+                issues.push(fieldIssue(ISSUE_CODES.FIELD_ENUM, nodeId, field, `value "${value}" is not one of the allowed options.`));
+            }
+        }
+    }
+    // Range — only when the value coerces to a finite number.
+    const numeric = coerceNumber(value);
+    if (numeric !== undefined) {
+        if (field.min !== undefined && numeric < field.min) {
+            issues.push(fieldIssue(ISSUE_CODES.FIELD_MIN, nodeId, field, `value ${numeric} is below the minimum ${field.min}.`));
+        }
+        if (field.max !== undefined && numeric > field.max) {
+            issues.push(fieldIssue(ISSUE_CODES.FIELD_MAX, nodeId, field, `value ${numeric} is above the maximum ${field.max}.`));
+        }
+    }
+    // Pattern — literal string values only, length-bounded.
+    if (field.pattern !== undefined &&
+        typeof value === "string" &&
+        value.length <= MAX_PATTERN_VALUE_LENGTH) {
+        const re = compilePattern(field.pattern);
+        if (re !== undefined && !re.test(value)) {
+            issues.push(fieldIssue(ISSUE_CODES.FIELD_PATTERN, nodeId, field, `value "${value}" does not match the required pattern.`));
+        }
+    }
+}
+// ── Predicates ──────────────────────────────────────────────
+/** Empty ⟺ absent / null / empty-string / empty-array. `false` and `0` are NOT empty. */
+function isEmpty(value) {
+    return (value === undefined ||
+        value === null ||
+        value === "" ||
+        (Array.isArray(value) && value.length === 0));
+}
+/** A finite number, or a non-blank numeric string. */
+function isCoarseNumber(value) {
+    return coerceNumber(value) !== undefined;
+}
+/** A real boolean, or the literal string `"true"` / `"false"` (any case). */
+function isCoarseBoolean(value) {
+    if (typeof value === "boolean")
+        return true;
+    if (typeof value === "string") {
+        const t = value.trim().toLowerCase();
+        return t === "true" || t === "false";
+    }
+    return false;
+}
+/** Coerce a number or non-blank numeric string to a finite number; else `undefined`. */
+function coerceNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed === "")
+            return undefined;
+        const n = Number(trimmed);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+/** Evaluate a field's `showWhen` visibility condition; absent condition → visible. */
+function isFieldVisible(field, data) {
+    const cond = field.showWhen;
+    if (cond === undefined)
+        return true;
+    const other = data[cond.field];
+    if ("isSet" in cond) {
+        return other !== undefined && other !== null && other !== "";
+    }
+    return other === cond.equals;
+}
+/** Resolve a `select` field's options, invoking the factory form; `undefined` on any failure (permissive). */
+function resolveOptions(field, data) {
+    const options = field.options;
+    if (options === undefined)
+        return undefined;
+    if (typeof options === "function") {
+        try {
+            return options(data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return options;
+}
+/**
+ * Compile an author `pattern` source; `undefined` on an invalid regex
+ * (permissive).
+ *
+ * **Execution surface.** With this validator, an author `pattern` now runs
+ * host-side in the worker's pre-flight (a NEW execution surface beyond the
+ * browser builder), so catalog authors MUST keep `pattern`s linear /
+ * backtracking-safe (RE2-style — no nested quantifiers like `(a+)+`). There is
+ * deliberately NO runtime regex-safety guard here: `field.pattern` is TRUSTED
+ * catalog input (authored node.json), not customer-supplied JSON, so a guard
+ * would be over-engineering. The {@link MAX_PATTERN_VALUE_LENGTH} cap only
+ * bounds the scanned value length; it is not a backtracking defense.
+ */
+function compilePattern(pattern) {
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        return undefined;
+    }
+}
+function fieldIssue(code, nodeId, field, detail) {
+    const label = field.label ?? field.key;
+    return {
+        code,
+        severity: "error",
+        nodeId,
+        fieldKey: field.key,
+        message: `Node "${nodeId}" field "${label}" ${detail}`,
+    };
+}