@flowget/ai 0.1.0

package/dist/prompt.js

@@ -0,0 +1,112 @@
+/**
+ * Prompt assembly — the grounding + persona + request.
+ *
+ * The **system prompt** is a stable prefix: persona, the customer's
+ * node catalog, and a compact reference to the workflow-graph shape.
+ * Being stable across a request's repair turns (and across requests
+ * with the same catalog) makes it the natural **prompt-caching
+ * prefix** — providers that cache by leading-token prefix amortize it.
+ *
+ * The **user prompt** carries the variable part: the command, the
+ * optional `currentGraph` being edited, and the optional client-carried
+ * `context`.
+ *
+ * Grounding note: the AUTHORITATIVE emission schema rides on the
+ * `propose_workflow` tool's parameters (the model fills it directly).
+ * The schema echoed here is trimmed (verbose `markdownDescription`
+ * copy stripped) so the model understands the graph model without
+ * paying for the full annotated schema twice.
+ */
+import { loadWorkflowSchema } from "./authoring-schema.js";
+// NOTE: the decline / already-satisfied rules below shape model
+// behavior on edge commands (e.g. "clear the canvas") and are only
+// observable with a real LLM — the deterministic mock adapter in the
+// test suite scripts its own turns, so these are verified in the
+// founder's playground, not by unit tests.
+export const DEFAULT_PERSONA = `You are Flowget's workflow-authoring assistant. You turn a user's natural-language request into a valid Flowget workflow graph, using ONLY the nodes in the provided catalog.
+
+Rules:
+- Author the smallest correct workflow that satisfies the request — do not add nodes the request did not ask for.
+- A runnable workflow needs at least one node whose category is "trigger".
+- Use only node "type" values that appear in the catalog (a node's "type" equals a catalog entry's "id"). Never invent a node type.
+- Wire nodes with edges. An edge's "source"/"target" are node ids. For branch routing, set an edge "sourceHandle" to one of the source node's declared handle ids.
+- To use an upstream node's output in a downstream node's config, write a template: {{ steps.<nodeId>.output.<key> }} for a node's output or {{ trigger.<key> }} for the trigger payload. Only reference node ids that exist in the graph.
+- Node "position" is optional — omit it; the builder lays the graph out.
+- Most config fields hold a scalar, but some are COMPOUND objects. A field of type "schedule" takes: { "spec": { "cron": "0 8 * * *", "timezone": "UTC" }, "overlap": "skip" }. The cron (or "intervalSeconds": <number> instead of cron) and "timezone" nest UNDER "spec"; "spec" is required with exactly one of cron or intervalSeconds; "overlap" is optional (defaults "skip"). Do NOT emit a flat { "cron", "timezone" }.
+- When the request is ambiguous or under-specified, DO NOT guess. Reply in plain text with ONE concise clarifying question instead of calling the tool.
+- If the request is NOT an authorable runnable workflow — e.g. "clear/discard/empty the canvas", "delete everything", "start over", or anything that would require an empty or non-runnable graph — do NOT call propose_workflow. Reply in plain text explaining that you author runnable workflows and that clearing the canvas is a manual action (delete the nodes directly in the builder). NEVER echo the current graph unchanged as a no-op proposal.
+- If a current graph is provided and it ALREADY satisfies the request, reply in plain text saying the workflow already does that, instead of proposing an unchanged graph.
+- When (and only when) you have a complete, valid workflow to author or change, call the "propose_workflow" tool exactly once.`;
+export function buildSystemPrompt(input) {
+    const persona = input.persona ?? DEFAULT_PERSONA;
+    const catalog = JSON.stringify(input.catalog, null, 2);
+    const schema = JSON.stringify(stripVerbose(loadWorkflowSchema()), null, 2);
+    return [
+        persona,
+        "## Node catalog (the only node types you may use)",
+        "```json",
+        catalog,
+        "```",
+        "## Workflow graph shape",
+        "```json",
+        schema,
+        "```",
+    ].join("\n\n");
+}
+/**
+ * The EXACT default system prompt `author` sends for a given catalog
+ * — {@link DEFAULT_PERSONA} + the catalog + the workflow-graph schema
+ * (loaded from `@flowget/types`, the single source of truth). This is
+ * the un-overridden `buildSystemPrompt({ catalog })` the author loop
+ * uses when `config.persona` is unset (see `runToolLoop` in
+ * `author.ts`).
+ *
+ * A thin, intent-revealing public entry point for consumers that need
+ * the real prompt without reaching into the author loop or replicating
+ * the persona — e.g. an out-of-process evaluation harness that measures
+ * the raw model output the library's own prompt elicits. The schema is
+ * loaded internally (never injected) so the prompt can never drift from
+ * the shipped `@flowget/types` schema.
+ */
+export function getDefaultSystemPrompt(catalog) {
+    return buildSystemPrompt({ catalog });
+}
+export function buildUserPrompt(request) {
+    const parts = [`## Command\n${request.command}`];
+    if (request.currentGraph !== undefined) {
+        parts.push("## Current graph (edit this — preserve nodes the command does not touch)", "```json", safeStringify(request.currentGraph), "```");
+    }
+    if (request.context !== undefined) {
+        parts.push("## Additional context (client-provided)", "```json", safeStringify(request.context), "```");
+    }
+    return parts.join("\n\n");
+}
+export function buildInitialMessages(request, system) {
+    return [
+        { role: "system", content: buildSystemPrompt(system) },
+        { role: "user", content: buildUserPrompt(request) },
+    ];
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Recursively drop `markdownDescription` keys (the biggest token sink). */
+function stripVerbose(value) {
+    if (Array.isArray(value))
+        return value.map(stripVerbose);
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            if (key === "markdownDescription")
+                continue;
+            out[key] = stripVerbose(inner);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/ssrf.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Construct-time URL validator used by `openaiAdapter({ baseURL })`
+ * and any BYO adapter that accepts a URL from caller config.
+ *
+ * Ported verbatim (behavior-preserving) from `@flowget/engine`'s
+ * `_shared/ssrf-guard.ts` — a cross-repo-locked security primitive.
+ * Reusing the audited logic (and its `ipaddr.js` classifier) is a
+ * deliberate decision over a hand-rolled re-implementation.
+ *
+ * **Static check, not runtime.** Runs once at the call site that
+ * constructs the adapter, before the URL is captured in closure. It
+ * catches the common config-leak shape (loopback, private IPv4 ranges,
+ * cloud metadata IP, IPv6 loopback/link-local/ULA, IPv4-mapped AND
+ * IPv4-compatible IPv6 wrapping a private IPv4, `file://`, etc.). It
+ * does NOT defend against DNS rebinding (a public hostname that
+ * resolves to a private IP at request time) or open redirects — those
+ * belong to the HTTP transport / network policy.
+ *
+ * **Scope**: `http:` / `https:` only. Other schemes are rejected.
+ */
+export type AssertSafeUrlOptions = {
+    /**
+     * Hostnames that bypass the private-range / loopback checks. Use
+     * only when the caller knowingly points at a private mirror (e.g. an
+     * internal LLM proxy at `llm.corp.internal`). Case-insensitive full
+     * hostname match — no wildcards.
+     */
+    readonly allowHosts?: ReadonlyArray<string>;
+};
+export declare class UnsafeUrlError extends Error {
+    name: string;
+}
+export declare function assertSafeUrl(url: string, opts?: AssertSafeUrlOptions): void;

package/dist/ssrf.js

@@ -0,0 +1,116 @@
+/**
+ * Construct-time URL validator used by `openaiAdapter({ baseURL })`
+ * and any BYO adapter that accepts a URL from caller config.
+ *
+ * Ported verbatim (behavior-preserving) from `@flowget/engine`'s
+ * `_shared/ssrf-guard.ts` — a cross-repo-locked security primitive.
+ * Reusing the audited logic (and its `ipaddr.js` classifier) is a
+ * deliberate decision over a hand-rolled re-implementation.
+ *
+ * **Static check, not runtime.** Runs once at the call site that
+ * constructs the adapter, before the URL is captured in closure. It
+ * catches the common config-leak shape (loopback, private IPv4 ranges,
+ * cloud metadata IP, IPv6 loopback/link-local/ULA, IPv4-mapped AND
+ * IPv4-compatible IPv6 wrapping a private IPv4, `file://`, etc.). It
+ * does NOT defend against DNS rebinding (a public hostname that
+ * resolves to a private IP at request time) or open redirects — those
+ * belong to the HTTP transport / network policy.
+ *
+ * **Scope**: `http:` / `https:` only. Other schemes are rejected.
+ */
+import ipaddr from "ipaddr.js";
+/**
+ * `http:` is intentionally permitted alongside `https:`. Self-hosted
+ * tenants and dev workflows (Ollama on loopback, an LLM mirror inside
+ * a VPN) genuinely need plaintext HTTP. Operators carrying an `apiKey`
+ * over `http:` accept the MITM exposure — this guard does not enforce
+ * TLS. Other schemes stay rejected outright.
+ */
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+/** Hostnames that always indicate loopback/local even if not an IP. */
+const BLOCKED_HOSTNAMES = new Set([
+    "localhost",
+    "ip6-localhost",
+    "ip6-loopback",
+]);
+export class UnsafeUrlError extends Error {
+    name = "UnsafeUrlError";
+}
+export function assertSafeUrl(url, opts = {}) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new UnsafeUrlError(`Refusing unparseable URL passed to an adapter factory: ${truncate(url)}`);
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new UnsafeUrlError(`Refusing non-HTTP(S) URL passed to an adapter factory: ${parsed.protocol}// (only http: / https: are allowed)`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    const ipCandidate = hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+    const allowList = new Set((opts.allowHosts ?? []).map((h) => h.toLowerCase()));
+    if (allowList.has(hostname) || allowList.has(ipCandidate))
+        return;
+    if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
+        throw new UnsafeUrlError(`Refusing loopback hostname passed to an adapter factory: ${hostname}`);
+    }
+    if (!ipaddr.isValid(ipCandidate)) {
+        // Not an IP — treat as a regular hostname and allow.
+        return;
+    }
+    const ip = ipaddr.parse(ipCandidate);
+    if (ip.kind() === "ipv4") {
+        assertIPv4NotPrivateOrReserved(ip, hostname);
+        return;
+    }
+    const v6 = ip;
+    const v6Range = v6.range();
+    if (v6Range === "loopback" ||
+        v6Range === "unspecified" ||
+        v6Range === "linkLocal" ||
+        v6Range === "uniqueLocal") {
+        throw new UnsafeUrlError(`Refusing private/reserved IPv6 (${v6Range}) passed to an adapter factory: ${ipCandidate}`);
+    }
+    const embedded = embeddedIPv4(v6);
+    if (embedded) {
+        assertIPv4NotPrivateOrReserved(embedded, `${ipCandidate} (IPv4 inside IPv6)`);
+    }
+}
+function assertIPv4NotPrivateOrReserved(ip, display) {
+    const range = ip.range();
+    if (range === "unspecified" ||
+        range === "broadcast" ||
+        range === "multicast" ||
+        range === "linkLocal" ||
+        range === "loopback" ||
+        range === "carrierGradeNat" ||
+        range === "private" ||
+        range === "reserved") {
+        throw new UnsafeUrlError(`Refusing private/reserved IPv4 (${range}) passed to an adapter factory: ${display}`);
+    }
+}
+function embeddedIPv4(v6) {
+    const p = v6.parts;
+    const topClear = p[0] === 0 && p[1] === 0 && p[2] === 0 && p[3] === 0 && p[4] === 0;
+    if (!topClear)
+        return null;
+    const isMapped = p[5] === 0xffff;
+    const isCompatLike = p[5] === 0;
+    if (!isMapped && !isCompatLike)
+        return null;
+    const lo = p[6] ?? 0;
+    const hi = p[7] ?? 0;
+    const octets = [
+        (lo >> 8) & 0xff,
+        lo & 0xff,
+        (hi >> 8) & 0xff,
+        hi & 0xff,
+    ];
+    return new ipaddr.IPv4(octets);
+}
+function truncate(s) {
+    return s.length > 80 ? s.slice(0, 77) + "..." : s;
+}

package/dist/toolset.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Toolsets — actor-scoped, model-invoked tools that run in-process
+ * (host-side) against the customer's data. The marquee capability.
+ *
+ * A tool is a plain async function — no Temporal-activity ceremony.
+ * The model calls it mid-loop; `author` dispatches it with the trusted
+ * `actor` and feeds the result back to the model. The tool's RETURN
+ * value is a domain result (including "not found"); a THROW is an infra
+ * fault that aborts the request. That distinction is the whole
+ * contract: model-recoverable outcomes are return values, operational
+ * failures are exceptions.
+ *
+ * Reference example: `dbToolset` in `examples/db-toolset.ts` resolves a
+ * user from a customer DB, scoped by the actor's tenant.
+ */
+import type { Actor } from "@flowget/types";
+import type { AiToolCall, AiToolDefinition } from "./adapter.js";
+/** Runtime context handed to every tool — carries the trusted actor. */
+export type ToolContext = {
+    actor?: Actor;
+};
+export type Tool = {
+    /** Tool name (letters, digits, `_`, `-`). Namespaced on the wire. */
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments object. */
+    parameters: Record<string, unknown>;
+    /**
+     * Run the tool. Return a domain result (serialized back to the
+     * model). Throw only on an infra fault — a throw aborts the request.
+     */
+    run: (input: Record<string, unknown>, context: ToolContext) => Promise<unknown> | unknown;
+};
+export type Toolset = {
+    /**
+     * Optional namespace. When set, wire names become
+     * `${namespace}__${tool.name}` so tools from different toolsets never
+     * collide.
+     */
+    namespace?: string;
+    tools: Tool[];
+};
+/**
+ * Flattens toolsets into a wire-name-addressable registry, enforcing
+ * name validity, uniqueness, and non-collision with reserved tool
+ * names (e.g. the emit tool).
+ */
+export declare class ToolRegistry {
+    private readonly entries;
+    private readonly defs;
+    constructor(toolsets: readonly Toolset[], reservedNames?: readonly string[]);
+    /** Tool definitions to advertise to the model. */
+    definitions(): AiToolDefinition[];
+    has(wireName: string): boolean;
+    /** Dispatch a model tool call; returns the serialized tool result. */
+    dispatch(call: AiToolCall, context: ToolContext): Promise<string>;
+}

package/dist/toolset.js

@@ -0,0 +1,76 @@
+/**
+ * Toolsets — actor-scoped, model-invoked tools that run in-process
+ * (host-side) against the customer's data. The marquee capability.
+ *
+ * A tool is a plain async function — no Temporal-activity ceremony.
+ * The model calls it mid-loop; `author` dispatches it with the trusted
+ * `actor` and feeds the result back to the model. The tool's RETURN
+ * value is a domain result (including "not found"); a THROW is an infra
+ * fault that aborts the request. That distinction is the whole
+ * contract: model-recoverable outcomes are return values, operational
+ * failures are exceptions.
+ *
+ * Reference example: `dbToolset` in `examples/db-toolset.ts` resolves a
+ * user from a customer DB, scoped by the actor's tenant.
+ */
+const TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * Flattens toolsets into a wire-name-addressable registry, enforcing
+ * name validity, uniqueness, and non-collision with reserved tool
+ * names (e.g. the emit tool).
+ */
+export class ToolRegistry {
+    entries = new Map();
+    defs = [];
+    constructor(toolsets, reservedNames = []) {
+        const reserved = new Set(reservedNames);
+        for (const toolset of toolsets) {
+            for (const tool of toolset.tools) {
+                const wireName = toolset.namespace !== undefined
+                    ? `${toolset.namespace}__${tool.name}`
+                    : tool.name;
+                if (!TOOL_NAME_PATTERN.test(wireName)) {
+                    throw new Error(`Invalid tool name "${wireName}" — names (and namespaces) may use letters, digits, "_" and "-" only, up to 64 chars.`);
+                }
+                if (reserved.has(wireName)) {
+                    throw new Error(`Tool name "${wireName}" collides with a reserved tool.`);
+                }
+                if (this.entries.has(wireName)) {
+                    throw new Error(`Duplicate tool name "${wireName}".`);
+                }
+                this.entries.set(wireName, tool);
+                this.defs.push({
+                    name: wireName,
+                    description: tool.description,
+                    parameters: tool.parameters,
+                });
+            }
+        }
+    }
+    /** Tool definitions to advertise to the model. */
+    definitions() {
+        return [...this.defs];
+    }
+    has(wireName) {
+        return this.entries.has(wireName);
+    }
+    /** Dispatch a model tool call; returns the serialized tool result. */
+    async dispatch(call, context) {
+        const tool = this.entries.get(call.name);
+        if (tool === undefined) {
+            throw new Error(`Unknown tool "${call.name}".`);
+        }
+        const result = await tool.run(call.arguments, context);
+        return serializeToolResult(result);
+    }
+}
+function serializeToolResult(result) {
+    if (typeof result === "string")
+        return result;
+    try {
+        return JSON.stringify(result ?? null);
+    }
+    catch {
+        return String(result);
+    }
+}

package/dist/validator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The default workflow validator — the guard that keeps un-runnable
+ * graphs from ever reaching a proposal.
+ *
+ * Checks, all cheap and dependency-free:
+ *   1. **Schema conformance** — AJV against the position-optional
+ *      authoring schema (structural shape of nodes + edges).
+ *   2. **Unique node ids** — duplicate ids make edge/template routing
+ *      ambiguous.
+ *   3. **Catalog cross-reference** — every `node.type` must be a node
+ *      id present in the loaded catalog.
+ *   4. **Edge endpoints exist** — every edge `source`/`target` must
+ *      reference a node in the graph (no dangling edges).
+ *   5. **Trigger presence** — the graph must contain at least one node
+ *      whose catalog category is `"trigger"` (the engine's runnability
+ *      gate). Enforced only when the catalog actually ships a trigger
+ *      node, so a trigger-less catalog can't make authoring impossible.
+ *   6. **Dangling template-ref** — every `{{ steps.<id>.… }}` must
+ *      reference a node id that exists in the graph.
+ *   7. **Compound field shape (schedule)** — catalog-driven: for any
+ *      field a node declares with `type: "schedule"`, its emitted
+ *      `data[key]` must be the canonical
+ *      `{ spec: { cron | intervalSeconds, timezone? }, overlap? }`
+ *      shape (not a flat `{ cron, timezone }`). The catalog carries the
+ *      field's editor config but NOT its `node.data` shape, so without
+ *      this the model guesses wrong for compound fields. This is the
+ *      schedule-field BRIDGE — a general "catalog conveys node.data
+ *      shapes for every compound field" contract is tracked separately.
+ *
+ * A failing result carries human-readable error strings; the author
+ * loop feeds them back to the model as a bounded repair prompt.
+ *
+ * Swappable: `config.validator` accepts a factory `(catalog) =>
+ * WorkflowValidator`. `createWorkflowValidator` is the default.
+ */
+import type { CatalogNode } from "./catalog.js";
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Validate an untrusted candidate graph (whatever the model emitted). */
+export type WorkflowValidator = (graph: unknown) => ValidationResult;
+/** Builds a validator bound to a specific catalog. */
+export type WorkflowValidatorFactory = (catalog: readonly CatalogNode[]) => WorkflowValidator;
+/**
+ * The default validator factory. Public note: compound-field VALUE
+ * validation currently covers only `type: "schedule"` fields — other
+ * compound field kinds are shape-checked by the JSON schema but not yet
+ * value-validated against their catalog declaration (a general
+ * compound-field contract is tracked separately).
+ */
+export declare const createWorkflowValidator: WorkflowValidatorFactory;

package/dist/validator.js

@@ -0,0 +1,196 @@
+/**
+ * The default workflow validator — the guard that keeps un-runnable
+ * graphs from ever reaching a proposal.
+ *
+ * Checks, all cheap and dependency-free:
+ *   1. **Schema conformance** — AJV against the position-optional
+ *      authoring schema (structural shape of nodes + edges).
+ *   2. **Unique node ids** — duplicate ids make edge/template routing
+ *      ambiguous.
+ *   3. **Catalog cross-reference** — every `node.type` must be a node
+ *      id present in the loaded catalog.
+ *   4. **Edge endpoints exist** — every edge `source`/`target` must
+ *      reference a node in the graph (no dangling edges).
+ *   5. **Trigger presence** — the graph must contain at least one node
+ *      whose catalog category is `"trigger"` (the engine's runnability
+ *      gate). Enforced only when the catalog actually ships a trigger
+ *      node, so a trigger-less catalog can't make authoring impossible.
+ *   6. **Dangling template-ref** — every `{{ steps.<id>.… }}` must
+ *      reference a node id that exists in the graph.
+ *   7. **Compound field shape (schedule)** — catalog-driven: for any
+ *      field a node declares with `type: "schedule"`, its emitted
+ *      `data[key]` must be the canonical
+ *      `{ spec: { cron | intervalSeconds, timezone? }, overlap? }`
+ *      shape (not a flat `{ cron, timezone }`). The catalog carries the
+ *      field's editor config but NOT its `node.data` shape, so without
+ *      this the model guesses wrong for compound fields. This is the
+ *      schedule-field BRIDGE — a general "catalog conveys node.data
+ *      shapes for every compound field" contract is tracked separately.
+ *
+ * A failing result carries human-readable error strings; the author
+ * loop feeds them back to the model as a bounded repair prompt.
+ *
+ * Swappable: `config.validator` accepts a factory `(catalog) =>
+ * WorkflowValidator`. `createWorkflowValidator` is the default.
+ */
+import Ajv2020 from "ajv/dist/2020.js";
+import { buildAuthoringSchema } from "./authoring-schema.js";
+import { isRecord } from "./guards.js";
+/**
+ * The default validator factory. Public note: compound-field VALUE
+ * validation currently covers only `type: "schedule"` fields — other
+ * compound field kinds are shape-checked by the JSON schema but not yet
+ * value-validated against their catalog declaration (a general
+ * compound-field contract is tracked separately).
+ */
+export const createWorkflowValidator = (catalog) => {
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    const validateSchema = ajv.compile(buildAuthoringSchema());
+    const knownTypes = new Set(catalog.map((node) => node.id));
+    const triggerTypes = new Set(catalog.filter((node) => node.category === "trigger").map((node) => node.id));
+    // node type id → keys of its `type: "schedule"` fields, read from the
+    // catalog (never hardcoded to a node id). `fields` is typed on
+    // `CatalogNode` (`BuilderHints.fields?: ConfigField[]`).
+    const scheduleFieldsByType = new Map();
+    for (const entry of catalog) {
+        if (entry.fields === undefined)
+            continue;
+        const keys = entry.fields
+            .filter((field) => field.type === "schedule")
+            .map((field) => field.key);
+        if (keys.length > 0)
+            scheduleFieldsByType.set(entry.id, keys);
+    }
+    return (graph) => {
+        const errors = [];
+        if (!validateSchema(graph)) {
+            for (const err of validateSchema.errors ?? []) {
+                const where = err.instancePath.length > 0 ? err.instancePath : "/";
+                errors.push(`schema: ${where} ${err.message ?? "is invalid"}`);
+            }
+        }
+        // Semantic checks run whenever the graph is structurally a
+        // node-bearing object, even if AJV flagged other issues — the more
+        // errors the repair prompt sees at once, the fewer round trips.
+        if (isRecord(graph) && Array.isArray(graph["nodes"])) {
+            const nodes = graph["nodes"];
+            // Pre-pass: collect the COMPLETE set of node ids (and detect
+            // duplicates) BEFORE any reference check. `nodes[]` order is not
+            // topological — a node may reference (via `{{ steps.X }}` or an
+            // edge) another node defined later in the array — so the id set
+            // must be fully populated first, or a valid forward reference is
+            // wrongly flagged as dangling.
+            const nodeIds = new Set();
+            const duplicateIds = new Set();
+            for (const node of nodes) {
+                if (isRecord(node) && typeof node["id"] === "string") {
+                    if (nodeIds.has(node["id"]))
+                        duplicateIds.add(node["id"]);
+                    nodeIds.add(node["id"]);
+                }
+            }
+            for (const dup of duplicateIds) {
+                errors.push(`duplicate node id "${dup}" — node ids must be unique`);
+            }
+            // Second pass: catalog cross-ref, trigger presence, and dangling
+            // template refs — all against the fully-populated id set.
+            let hasTrigger = false;
+            for (const node of nodes) {
+                if (!isRecord(node))
+                    continue;
+                const id = typeof node["id"] === "string" ? node["id"] : "?";
+                const type = node["type"];
+                if (typeof type === "string") {
+                    if (!knownTypes.has(type)) {
+                        errors.push(`unknown node type "${type}" (node "${id}") — not in the catalog`);
+                    }
+                    if (triggerTypes.has(type))
+                        hasTrigger = true;
+                    const scheduleKeys = scheduleFieldsByType.get(type);
+                    if (scheduleKeys !== undefined && isRecord(node["data"])) {
+                        const data = node["data"];
+                        for (const key of scheduleKeys) {
+                            if (!(key in data))
+                                continue; // shape-check only when emitted
+                            const problem = validateScheduleShape(data[key]);
+                            if (problem !== null) {
+                                errors.push(`schedule field "${key}" on node "${id}" ${problem}`);
+                            }
+                        }
+                    }
+                }
+                collectDanglingRefs(node["data"], nodeIds, id, errors);
+            }
+            if (Array.isArray(graph["edges"])) {
+                for (const edge of graph["edges"]) {
+                    if (!isRecord(edge))
+                        continue;
+                    const edgeId = typeof edge["id"] === "string" ? edge["id"] : "?";
+                    for (const end of ["source", "target"]) {
+                        const ref = edge[end];
+                        if (typeof ref === "string" && !nodeIds.has(ref)) {
+                            errors.push(`edge "${edgeId}" ${end} "${ref}" references no node in the graph`);
+                        }
+                    }
+                }
+            }
+            // The engine requires >=1 trigger node to run a workflow. Only
+            // enforce when the catalog ships a trigger — a trigger-less
+            // catalog can't produce one, so blocking would be un-authorable.
+            if (triggerTypes.size > 0 && !hasTrigger) {
+                errors.push('the workflow has no trigger node — it needs at least one node whose category is "trigger" to be runnable');
+            }
+        }
+        return errors.length === 0 ? { ok: true } : { ok: false, errors };
+    };
+};
+/**
+ * Validate an emitted `type: "schedule"` field value. Returns a repair
+ * message that NAMES the expected shape (so the bounded repair loop
+ * converges), or null when the shape is canonical:
+ * `{ spec: { cron | intervalSeconds, timezone? }, overlap? }`.
+ */
+function validateScheduleShape(value) {
+    if (!isRecord(value)) {
+        return "must be an object `{ spec: { cron|intervalSeconds, timezone? }, overlap? }`";
+    }
+    const spec = value["spec"];
+    if (!isRecord(spec)) {
+        if ("cron" in value || "intervalSeconds" in value || "timezone" in value) {
+            return "must nest cron/interval under `spec`: `{ spec: { cron|intervalSeconds, timezone? }, overlap? }` — you emitted a flat `{ cron, timezone }`";
+        }
+        return "must have a `spec` object: `{ spec: { cron|intervalSeconds, timezone? }, overlap? }`";
+    }
+    const hasCron = typeof spec["cron"] === "string";
+    const hasInterval = typeof spec["intervalSeconds"] === "number";
+    if (hasCron === hasInterval) {
+        return "`spec` must have exactly one of `cron` (string) or `intervalSeconds` (number)";
+    }
+    return null;
+}
+function collectDanglingRefs(value, nodeIds, nodeId, out) {
+    // Fresh regex per traversal — no shared `lastIndex` across calls.
+    const stepsRef = /\{\{\s*steps\.([A-Za-z0-9_-]+)/g;
+    walk(value);
+    function walk(inner) {
+        if (typeof inner === "string") {
+            let match;
+            while ((match = stepsRef.exec(inner)) !== null) {
+                const referenced = match[1];
+                if (referenced !== undefined && !nodeIds.has(referenced)) {
+                    out.push(`dangling template ref "{{ steps.${referenced}.… }}" in node "${nodeId}" — no node has id "${referenced}"`);
+                }
+            }
+            return;
+        }
+        if (Array.isArray(inner)) {
+            for (const item of inner)
+                walk(item);
+            return;
+        }
+        if (isRecord(inner)) {
+            for (const item of Object.values(inner))
+                walk(item);
+        }
+    }
+}