@xdelivered/emberflow 0.2.0

package/dist/src/engine/types.d.ts

@@ -0,0 +1,308 @@
+export type FieldType = 'string' | 'number' | 'boolean' | 'enum' | 'datetime' | 'object' | 'array';
+export interface FieldDefinition {
+    name: string;
+    type: FieldType;
+    required?: boolean;
+    enumValues?: string[];
+    description?: string;
+}
+export interface SchemaDefinition {
+    fields: FieldDefinition[];
+}
+export interface NodeDefinition {
+    type: string;
+    label: string;
+    description?: string;
+    /**
+     * Plain-language one-liner for non-developers, shown in the simple register
+     * (runbook idle text, simple Inspector description) instead of `description`,
+     * which may lead with mechanism (PORT NOTE, file paths, implementation
+     * detail). Falls back to the first sentence of `description` when absent.
+     */
+    simpleDescription?: string;
+    category?: string;
+    inputSchema?: SchemaDefinition;
+    outputSchema?: SchemaDefinition;
+    configSchema?: SchemaDefinition;
+    icon?: string;
+    tags?: string[];
+    /**
+     * Side-effect class. 'mutation' nodes write state someone else can observe
+     * (DB writes, emails, external POSTs that create/change resources) and are
+     * dry-run under safe mode. Absent = 'read' (default).
+     */
+    effects?: 'read' | 'mutation';
+    /**
+     * What kind of work this node does, for the runbook's technical register. Pure
+     * documentation — the engine ignores it. 'db' = queries Postgres, 'http' =
+     * calls an external service over HTTP, 'llm' = calls a language model,
+     * 'compute' = pure in-process logic. Absent when unknown (an absent badge is
+     * honest; a wrong one is not).
+     */
+    traceKind?: 'db' | 'http' | 'llm' | 'compute';
+    /**
+     * A short, STATIC technical descriptor of the concrete call this node makes,
+     * for the runbook's technical register (the trace badge hover card). Pure
+     * documentation — the engine ignores it. For 'db' the query shape (e.g.
+     * 'SELECT … FROM projects JOIN users … WHERE p.id = $1'); for 'http' the
+     * method + endpoint (e.g. 'POST https://oauth2.googleapis.com/token'); for
+     * 'llm' the provider + model (e.g. 'openrouter.ai · x-ai/grok-4.3:online').
+     * Describes the mechanism, NOT runtime values. Absent on 'compute' nodes and
+     * whenever the target is dynamic enough that no honest static shape exists.
+     */
+    traceDetail?: string;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Outcome of running a child workflow synchronously via a Subflow node. */
+export interface SubflowResult {
+    status: 'succeeded' | 'failed';
+    output?: unknown;
+    error?: string;
+}
+export interface NodeExecutionContext {
+    input: Record<string, unknown>;
+    config: Record<string, unknown>;
+    /** Runner-supplied secrets; empty in browser execution. */
+    secrets: Record<string, string>;
+    /** Non-secret environment values (API base URLs, seed ids, flags). Empty in browser execution. */
+    vars: Record<string, string>;
+    /** The environment name this run targets (e.g. 'prod'); undefined in browser/in-tab runs. */
+    environment?: string;
+    /** When true, mutation nodes must dry-run their side effects instead of executing them. */
+    safeMode: boolean;
+    /** The payload this run was invoked with (emberflow.run(name, input)). */
+    runInput: Record<string, unknown>;
+    log: (level: LogLevel, message: string) => void;
+    /**
+     * Runs a child workflow to completion and returns its collected output.
+     * Provided by the host (browser store / server run registry); absent when the
+     * run has no way to look up other workflows, in which case a Subflow node
+     * fails with a clear message.
+     */
+    runSubflow?: (workflowId: string, input: Record<string, unknown>) => Promise<SubflowResult>;
+}
+export type NodeImplementation = (ctx: NodeExecutionContext) => Promise<unknown>;
+export interface FieldMapping {
+    sourceNodeId: string;
+    /** Dot path into the source node's output. '$' means the entire output. */
+    sourceField: string;
+    transform?: string;
+}
+export interface WorkflowNode {
+    id: string;
+    type: string;
+    label: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    config: Record<string, unknown>;
+    inputMap?: Record<string, FieldMapping>;
+    /**
+     * Fail-soft flag. When true, this node throwing marks it `failed` but does
+     * NOT abort the run: the cursor continues, so independent branches still run
+     * and the run can finish `succeeded`. The failed node produces no output, so
+     * its downstream consumers become unreachable (dead edges) and skip — exactly
+     * like a live "mirror" step whose failure must not break the deterministic
+     * path beside it. A non-optional node's failure still aborts the run.
+     *
+     * Applies to standard node execution. A ForEach region's own setup failure is
+     * NOT fail-soft (the flag is ignored there); mark ordinary/Subflow nodes.
+     */
+    optional?: boolean;
+    /**
+     * Retry the implementation call on throw. `maxTries` is the total number of
+     * attempts including the first (so `maxTries: 3` means up to 2 retries).
+     * `waitMs` (default 0) is a fixed delay between attempts. Only the
+     * `implementation({...})` call is retried — config/input resolution runs
+     * once, and only the final attempt's outcome is recorded (state, trace,
+     * fail-soft). A non-object value or `maxTries < 1` is treated as absent.
+     */
+    retry?: {
+        maxTries: number;
+        waitMs?: number;
+    };
+    /** Builder-owned extras (e.g. pinnedOutput). The engine never reads this. */
+    metadata?: Record<string, unknown>;
+}
+export interface WorkflowEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    label?: string;
+}
+export interface ScenarioDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    /** Run payload, same shape as StartRunOptions.input. For an operation (a flow
+     *  with `http`), this is the request shape `{ params?, query?, body?, headers? }`
+     *  — an in-studio "Run" of a scenario passes this object as `input` through the
+     *  same `RunRegistry.create` path a live HTTP request builds and passes, so the
+     *  two are parity-equivalent (see server/httpOperations.test.ts). For a non-HTTP
+     *  (internal) flow, `input` is used as-is — unchanged behavior. */
+    input: Record<string, unknown>;
+    /** Optional assertion the scenario's run must satisfy. Consumed by `emberflow
+     *  test` (evaluateExpectation in server/scenarioTest.ts) and mock mode; a
+     *  scenario without `expect` is a fixture only (not assertable). */
+    expect?: ScenarioExpectation;
+    /** nodeId -> canned output (verbatim, same shape the implementation would return).
+     *  Consulted only when the run has `mockRun: true`; merges over the operation-level
+     *  mocks map (scenario wins per nodeId). Plumbing (reading/merging these into a run)
+     *  is a later increment — this is type-only for now. */
+    mocks?: Record<string, unknown>;
+}
+/** Assertion checked against a scenario's run + its flow's response mapping.
+ *  `body` is a deep-subset match (see evaluateExpectation): every expected key
+ *  must match recursively, arrays compare index-wise on the expected prefix,
+ *  extra actual keys are fine, and `null` matches only `null`. */
+export interface ScenarioExpectation {
+    /** Expected HTTP status of the extracted response (default response is 200). */
+    status?: number;
+    /** Expected response body, matched as a deep subset of the actual body. */
+    body?: unknown;
+    /** Node ids expected to have run to `succeeded`. */
+    executedNodes?: string[];
+}
+/** An inheritable auth policy: scheme + secret ref + optional named verifier.
+ *  Set at the API/folder level via `_meta.json` (inherited by descendants) or
+ *  overridden per-operation via `HttpTrigger.auth`. Lives here (not in
+ *  server/auth/types.ts) because src/ must not import from server/; server/auth/types.ts
+ *  re-exports this type. */
+export interface AuthPolicy {
+    scheme: 'bearer' | 'apiKey';
+    /** Name of the secret (in the run environment's secrets) holding the expected token/key. */
+    secretRef: string;
+    /** Optional named custom verifier; when set, overrides the built-in scheme verifier. */
+    verify?: string;
+    /** Header to read for apiKey (default 'x-api-key'); bearer always reads Authorization. */
+    header?: string;
+}
+/** HTTP trigger metadata for an operation. Routing is a later increment; this
+ *  increment only stores/round-trips it. */
+export interface HttpTrigger {
+    method: string;
+    path: string;
+    inputSchema?: unknown;
+    /** Effective auth policy for this operation. 'none' makes it explicitly
+     *  public (overriding any inherited _meta.json policy); 'inherit' (or
+     *  absent) defers to the nearest ancestor _meta.json's policy, if any. */
+    auth?: AuthPolicy | 'none' | 'inherit';
+}
+export interface WorkflowDefinition {
+    id: string;
+    name: string;
+    version: number;
+    /** Optional sidebar folder path (single level, e.g. "Anomaly Detection"). */
+    folder?: string;
+    /** Present → this flow is (or will be) an HTTP endpoint. Absent → internal sub-flow. */
+    http?: HttpTrigger;
+    /**
+     * Preferred environment name. When set and the runner offers a matching
+     * environment, opening this flow auto-selects it — so a flow that targets
+     * prod infrastructure doesn't silently run against local.
+     */
+    environment?: string;
+    nodes: WorkflowNode[];
+    edges: WorkflowEdge[];
+    /** Named test inputs ("storybook" scenarios). Dev fixtures — stripped on publish. */
+    scenarios?: ScenarioDefinition[];
+    /** Op-level nodeId -> canned output (verbatim), consulted only when a run
+     *  has `mockRun: true`. Merges under any per-scenario `mocks` (scenario
+     *  wins per nodeId — see `ScenarioDefinition.mocks`). Lives in the
+     *  `<op>.scenarios.json` sidecar alongside `scenarios`, exposed here by
+     *  the store that loads it (e.g. `ApiStore`). Dev fixture — stripped on
+     *  publish, same as `scenarios`. */
+    mocks?: Record<string, unknown>;
+    viewport?: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+export type NodeStatus = 'idle' | 'queued' | 'running' | 'succeeded' | 'failed' | 'skipped';
+export type RunStatus = 'running' | 'succeeded' | 'failed' | 'cancelled';
+/** One execution of a node within a loop region — one entry per iteration. */
+export interface ExecutionRecord {
+    iteration: {
+        index: number;
+        total: number;
+    };
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    status: 'succeeded' | 'failed';
+}
+export interface NodeRunState {
+    status: NodeStatus;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** True when this node's output came from a pin instead of execution. */
+    pinned?: boolean;
+    /** True when a mutation-declared node completed under safe mode (its writes were dry-run). */
+    mutationBlocked?: boolean;
+    /**
+     * Present on a ForEach node and its loop-body nodes while a loop region is
+     * iterating (and left at its last value once the loop completes), giving
+     * the 0-based position and total iteration count.
+     */
+    iteration?: {
+        index: number;
+        total: number;
+    };
+    /**
+     * Full per-iteration execution history, present on a ForEach node and its
+     * loop-body nodes, ordered by iteration. Absent on non-loop executions.
+     */
+    executions?: ExecutionRecord[];
+    /**
+     * Total number of implementation-call attempts (including the first),
+     * present only when the node has a `retry` and used more than one attempt
+     * to reach its final outcome (success or exhausted failure). Absent
+     * whenever a single attempt sufficed — including nodes without `retry` at
+     * all — so existing single-try consumers see no shape change.
+     */
+    attempts?: number;
+    /** True when this node's output is a canned mock value from a mock run, not the result of executing its implementation. */
+    mocked?: boolean;
+}
+export interface WorkflowRun {
+    id: string;
+    workflowId: string;
+    status: RunStatus;
+    startedAt: string;
+    completedAt?: string;
+    /** The environment this run pointed at (from StartRunOptions.environment). */
+    environment?: string;
+    /** Whether safe mode was active for this run. */
+    safeMode?: boolean;
+    nodeStates: Record<string, NodeRunState>;
+}
+export interface LogLine {
+    timestamp: string;
+    level: LogLevel;
+    runId: string;
+    nodeId?: string;
+    nodeLabel?: string;
+    message: string;
+}
+export interface NodeExecutionSample {
+    id: string;
+    workflowId: string;
+    runId: string;
+    nodeId: string;
+    nodeType: string;
+    nodeLabel: string;
+    input: unknown;
+    output?: unknown;
+    status: 'succeeded' | 'failed';
+    startedAt: string;
+    completedAt?: string;
+}

package/dist/src/engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/engine/validation.d.ts

@@ -0,0 +1,26 @@
+import type { WorkflowDefinition } from './types.js';
+import type { NodeRegistry } from './registry.js';
+export interface ValidationIssue {
+    severity: 'error' | 'warning';
+    nodeId?: string;
+    message: string;
+}
+export interface LoopRegion {
+    forEachId: string;
+    collectId: string;
+    /** Loop-body node ids: downstream(forEach) ∩ upstream(collect), excluding both. */
+    bodyIds: string[];
+}
+export declare function topoSort(flow: WorkflowDefinition): string[];
+/** All nodes upstream of nodeId (direct parents and further ancestors). */
+export declare function upstreamNodeIds(flow: WorkflowDefinition, nodeId: string): Set<string>;
+/** All nodes downstream of nodeId (direct children and further descendants). */
+export declare function downstreamNodeIds(flow: WorkflowDefinition, nodeId: string): Set<string>;
+/**
+ * Computes ForEach/Collect loop regions for a flow. Only returns regions for
+ * valid pairings (1:1 ForEach↔Collect, no leaking edges, not nested) — an
+ * invalid flow fails validateFlow and startRun already throws before this
+ * would be consulted.
+ */
+export declare function computeLoopRegions(flow: WorkflowDefinition): LoopRegion[];
+export declare function validateFlow(flow: WorkflowDefinition, registry: NodeRegistry): ValidationIssue[];

package/dist/src/engine/validation.js

@@ -0,0 +1,318 @@
+export function topoSort(flow) {
+    const indegree = new Map();
+    const adjacency = new Map();
+    for (const n of flow.nodes) {
+        indegree.set(n.id, 0);
+        adjacency.set(n.id, []);
+    }
+    for (const e of flow.edges) {
+        if (!adjacency.has(e.source) || !indegree.has(e.target))
+            continue;
+        adjacency.get(e.source).push(e.target);
+        indegree.set(e.target, indegree.get(e.target) + 1);
+    }
+    const queue = flow.nodes.filter((n) => indegree.get(n.id) === 0).map((n) => n.id);
+    const order = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        order.push(id);
+        for (const next of adjacency.get(id)) {
+            indegree.set(next, indegree.get(next) - 1);
+            if (indegree.get(next) === 0)
+                queue.push(next);
+        }
+    }
+    if (order.length !== flow.nodes.length)
+        throw new Error('Flow contains a cycle');
+    return order;
+}
+/** All nodes upstream of nodeId (direct parents and further ancestors). */
+export function upstreamNodeIds(flow, nodeId) {
+    const incoming = new Map();
+    for (const e of flow.edges) {
+        if (!incoming.has(e.target))
+            incoming.set(e.target, []);
+        incoming.get(e.target).push(e.source);
+    }
+    const seen = new Set();
+    const queue = [...(incoming.get(nodeId) ?? [])];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        queue.push(...(incoming.get(id) ?? []));
+    }
+    return seen;
+}
+/** All nodes downstream of nodeId (direct children and further descendants). */
+export function downstreamNodeIds(flow, nodeId) {
+    const outgoing = new Map();
+    for (const e of flow.edges) {
+        if (!outgoing.has(e.source))
+            outgoing.set(e.source, []);
+        outgoing.get(e.source).push(e.target);
+    }
+    const seen = new Set();
+    const queue = [...(outgoing.get(nodeId) ?? [])];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        queue.push(...(outgoing.get(id) ?? []));
+    }
+    return seen;
+}
+/**
+ * Matches ForEach nodes to a single downstream Collect (and vice versa) and
+ * computes each region's body + any edges that leak out of it. A ForEach/
+ * Collect that doesn't pair 1:1 is simply omitted here — validateFlow raises
+ * the specific "no Collect"/"multiple Collect"/etc. errors separately.
+ */
+function findLoopPairings(flow) {
+    const forEachNodes = flow.nodes.filter((n) => n.type === 'ForEach');
+    const collectNodes = flow.nodes.filter((n) => n.type === 'Collect');
+    const pairings = [];
+    for (const forEachNode of forEachNodes) {
+        const downstream = downstreamNodeIds(flow, forEachNode.id);
+        const collectsDownstream = collectNodes.filter((c) => downstream.has(c.id));
+        if (collectsDownstream.length !== 1)
+            continue;
+        const collectNode = collectsDownstream[0];
+        const upstream = upstreamNodeIds(flow, collectNode.id);
+        const forEachesUpstream = forEachNodes.filter((f) => upstream.has(f.id));
+        if (forEachesUpstream.length !== 1 || forEachesUpstream[0].id !== forEachNode.id)
+            continue;
+        const bodyIds = [...downstream].filter((id) => upstream.has(id) && id !== forEachNode.id && id !== collectNode.id);
+        const bodySet = new Set(bodyIds);
+        const leaks = flow.edges.filter((e) => bodySet.has(e.source) && !bodySet.has(e.target) && e.target !== collectNode.id);
+        pairings.push({ forEachNode, collectNode, bodyIds, leaks });
+    }
+    return pairings;
+}
+/**
+ * ForEach node ids that sit downstream of another ForEach node — i.e. one
+ * region wraps the other. Deliberately independent of findLoopPairings: a
+ * genuinely nested pair almost always also fails the "exactly one Collect
+ * descendant" check for the outer ForEach (its downstream includes both the
+ * inner and outer Collect), which would otherwise prevent a pairing — and
+ * therefore prevent detecting the nesting — from ever being computed.
+ */
+function nestedForEachIds(flow) {
+    const forEachNodes = flow.nodes.filter((n) => n.type === 'ForEach');
+    const nested = new Set();
+    for (const outer of forEachNodes) {
+        const downstream = downstreamNodeIds(flow, outer.id);
+        for (const inner of forEachNodes) {
+            if (outer === inner)
+                continue;
+            if (downstream.has(inner.id)) {
+                nested.add(outer.id);
+                nested.add(inner.id);
+            }
+        }
+    }
+    return nested;
+}
+/**
+ * Computes ForEach/Collect loop regions for a flow. Only returns regions for
+ * valid pairings (1:1 ForEach↔Collect, no leaking edges, not nested) — an
+ * invalid flow fails validateFlow and startRun already throws before this
+ * would be consulted.
+ */
+export function computeLoopRegions(flow) {
+    const pairings = findLoopPairings(flow);
+    const nested = nestedForEachIds(flow);
+    return pairings
+        .filter((p) => p.leaks.length === 0 && !nested.has(p.forEachNode.id))
+        .map((p) => ({
+        forEachId: p.forEachNode.id,
+        collectId: p.collectNode.id,
+        bodyIds: p.bodyIds,
+    }));
+}
+export function validateFlow(flow, registry) {
+    const issues = [];
+    const nodeIds = new Set(flow.nodes.map((n) => n.id));
+    for (const node of flow.nodes) {
+        if (!registry.has(node.type)) {
+            issues.push({ severity: 'error', nodeId: node.id, message: `Unknown node type: ${node.type}` });
+        }
+    }
+    for (const edge of flow.edges) {
+        for (const end of [edge.source, edge.target]) {
+            if (!nodeIds.has(end)) {
+                issues.push({ severity: 'error', message: `Edge ${edge.id} references missing node: ${end}` });
+            }
+        }
+    }
+    try {
+        topoSort(flow);
+    }
+    catch {
+        issues.push({ severity: 'error', message: 'Flow contains a cycle' });
+    }
+    const ancestorsOf = (nodeId) => upstreamNodeIds(flow, nodeId);
+    for (const node of flow.nodes) {
+        for (const [field, mapping] of Object.entries(node.inputMap ?? {})) {
+            if (!nodeIds.has(mapping.sourceNodeId)) {
+                issues.push({
+                    severity: 'error', nodeId: node.id,
+                    message: `Input "${field}" maps to missing node: ${mapping.sourceNodeId}`,
+                });
+            }
+            else if (!ancestorsOf(node.id).has(mapping.sourceNodeId)) {
+                issues.push({
+                    severity: 'warning', nodeId: node.id,
+                    message: `Input "${field}" maps to ${mapping.sourceNodeId}, which is not upstream of this node`,
+                });
+            }
+        }
+        // A Subflow that names its own containing flow would recurse forever; the
+        // runtime guard catches cross-flow cycles, but a direct self-call is a
+        // static error.
+        if (node.type === 'Subflow' && node.config.workflowId === flow.id) {
+            issues.push({
+                severity: 'error', nodeId: node.id,
+                message: 'subflow cannot call its own flow',
+            });
+        }
+        if (!registry.has(node.type))
+            continue;
+        const definition = registry.get(node.type).definition;
+        const inputSchema = definition.inputSchema;
+        // Mutation nodes write observable state — warn so they can be reviewed
+        // before running against a protected environment; safe mode dry-runs them.
+        if (definition.effects === 'mutation') {
+            issues.push({
+                severity: 'warning',
+                nodeId: node.id,
+                message: `Mutation node "${node.label}" performs writes — dry-run under safe mode`,
+            });
+        }
+        // Mappings to fields the node never declared are silently ignored by
+        // implementations — surface them.
+        const declared = new Set((inputSchema?.fields ?? []).map((f) => f.name));
+        for (const field of Object.keys(node.inputMap ?? {})) {
+            if (!declared.has(field)) {
+                issues.push({
+                    severity: 'warning', nodeId: node.id,
+                    message: `Input "${field}" is mapped but not declared in ${node.type}'s input schema`,
+                });
+            }
+        }
+        for (const field of inputSchema?.fields ?? []) {
+            if (!field.required)
+                continue;
+            const mapped = node.inputMap?.[field.name] !== undefined;
+            const configured = node.config[field.name] !== undefined;
+            if (!mapped && !configured) {
+                issues.push({
+                    severity: 'warning', nodeId: node.id,
+                    message: `Required input "${field.name}" is not mapped or configured`,
+                });
+            }
+        }
+    }
+    if (flow.scenarios && flow.scenarios.length > 0) {
+        const inputNode = flow.nodes.find((n) => n.type === 'Input');
+        if (!inputNode) {
+            issues.push({
+                severity: 'warning',
+                message: 'Flow has scenarios but no Input node — scenario input is never consumed',
+            });
+        }
+        else {
+            const rawFields = inputNode.config?.fields;
+            const fields = Array.isArray(rawFields)
+                ? rawFields.filter((f) => f !== null && typeof f === 'object' && typeof f.name === 'string')
+                : [];
+            const rawDefaults = inputNode.config?.defaults;
+            const defaults = rawDefaults !== null && typeof rawDefaults === 'object' && !Array.isArray(rawDefaults)
+                ? rawDefaults
+                : {};
+            const declaredNames = new Set(fields.map((f) => f.name));
+            for (const scenario of flow.scenarios) {
+                for (const field of fields) {
+                    if (!field.required)
+                        continue;
+                    if (Object.prototype.hasOwnProperty.call(defaults, field.name))
+                        continue;
+                    if (Object.prototype.hasOwnProperty.call(scenario.input, field.name))
+                        continue;
+                    issues.push({
+                        severity: 'warning',
+                        nodeId: inputNode.id,
+                        message: `Scenario "${scenario.name}" omits required input field "${field.name}"`,
+                    });
+                }
+                for (const key of Object.keys(scenario.input)) {
+                    if (!declaredNames.has(key)) {
+                        issues.push({
+                            severity: 'warning',
+                            nodeId: inputNode.id,
+                            message: `Scenario "${scenario.name}" provides undeclared input field "${key}"`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // ── ForEach/Collect loop regions ──────────────────────────────────
+    for (const n of flow.nodes) {
+        if (n.type !== 'ForEach')
+            continue;
+        const downstream = downstreamNodeIds(flow, n.id);
+        const collectsDownstream = flow.nodes.filter((c) => c.type === 'Collect' && downstream.has(c.id));
+        if (collectsDownstream.length === 0) {
+            issues.push({
+                severity: 'error', nodeId: n.id,
+                message: `ForEach "${n.id}" has no Collect node among its descendants`,
+            });
+        }
+        else if (collectsDownstream.length > 1) {
+            issues.push({
+                severity: 'error', nodeId: n.id,
+                message: `ForEach "${n.id}" has multiple Collect nodes among its descendants: ${collectsDownstream.map((c) => c.id).join(', ')}`,
+            });
+        }
+    }
+    for (const n of flow.nodes) {
+        if (n.type !== 'Collect')
+            continue;
+        const upstream = upstreamNodeIds(flow, n.id);
+        const forEachesUpstream = flow.nodes.filter((f) => f.type === 'ForEach' && upstream.has(f.id));
+        if (forEachesUpstream.length === 0) {
+            issues.push({
+                severity: 'error', nodeId: n.id,
+                message: `Collect "${n.id}" has no ForEach node among its ancestors`,
+            });
+        }
+        else if (forEachesUpstream.length > 1) {
+            issues.push({
+                severity: 'error', nodeId: n.id,
+                message: `Collect "${n.id}" has multiple ForEach nodes among its ancestors: ${forEachesUpstream.map((f) => f.id).join(', ')}`,
+            });
+        }
+    }
+    const pairings = findLoopPairings(flow);
+    for (const p of pairings) {
+        for (const edge of p.leaks) {
+            issues.push({
+                severity: 'error',
+                nodeId: edge.source,
+                message: `Edge "${edge.id}" leaves the ForEach/Collect region rooted at "${p.forEachNode.id}" without targeting the region or its Collect node "${p.collectNode.id}"`,
+            });
+        }
+    }
+    const nested = nestedForEachIds(flow);
+    for (const forEachId of nested) {
+        issues.push({
+            severity: 'error',
+            nodeId: forEachId,
+            message: 'Nested ForEach regions are not supported',
+        });
+    }
+    return issues;
+}

package/dist/src/flows/anomaly-flows.d.ts

@@ -0,0 +1,23 @@
+import type { WorkflowDefinition } from '../engine/index.js';
+/**
+ * Live call: whole-series detection, then branch on severity.
+ *   build → detect → summarize → cond(anomalyCount > 0?)
+ *     ├─ anomalous → composeIncident → incidentResult
+ *     └─ clean     → cleanResult
+ *
+ * Deviation from spec: the spec's Conditional has two rules (`gt 3 → P1`,
+ * `gt 0 → P2`) feeding three downstream paths, but this flow only ever had
+ * two downstream branches (anomalous/clean). Kept the original two-branch
+ * shape as a single rule `gt 0 → anomalous`, fallback `clean`, rather than
+ * inventing a third P1/P2 branch nothing here consumes.
+ */
+export declare function createDetectEntireFlow(): WorkflowDefinition;
+/** Live call: streaming-style last-point verdict. */
+export declare function createDetectLastFlow(): WorkflowDefinition;
+/** Live call: detection + Adtributor root-cause analysis. */
+export declare function createRootCauseFlow(): WorkflowDefinition;
+/** Replica of today's quota/email business logic (Clerk-gated server-side). */
+export declare function createQuotaFlow(): WorkflowDefinition;
+/** Replica of today's key issuance + 5-key limit guard. */
+export declare function createKeyLifecycleFlow(): WorkflowDefinition;
+export declare function createAnomalyFlows(): WorkflowDefinition[];