@xdelivered/emberflow 0.2.0

package/src/engine/validation.ts

@@ -0,0 +1,354 @@
+import type { FieldDefinition, WorkflowDefinition, WorkflowEdge, WorkflowNode } from './types';
+import type { NodeRegistry } from './registry';
+
+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 function topoSort(flow: WorkflowDefinition): string[] {
+  const indegree = new Map<string, number>();
+  const adjacency = new Map<string, string[]>();
+  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: string[] = [];
+  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: WorkflowDefinition, nodeId: string): Set<string> {
+  const incoming = new Map<string, string[]>();
+  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<string>();
+  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: WorkflowDefinition, nodeId: string): Set<string> {
+  const outgoing = new Map<string, string[]>();
+  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<string>();
+  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;
+}
+
+interface LoopPairing {
+  forEachNode: WorkflowNode;
+  collectNode: WorkflowNode;
+  bodyIds: string[];
+  leaks: WorkflowEdge[];
+}
+
+/**
+ * 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: WorkflowDefinition): LoopPairing[] {
+  const forEachNodes = flow.nodes.filter((n) => n.type === 'ForEach');
+  const collectNodes = flow.nodes.filter((n) => n.type === 'Collect');
+  const pairings: LoopPairing[] = [];
+
+  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: WorkflowDefinition): Set<string> {
+  const forEachNodes = flow.nodes.filter((n) => n.type === 'ForEach');
+  const nested = new Set<string>();
+  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: WorkflowDefinition): LoopRegion[] {
+  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: WorkflowDefinition, registry: NodeRegistry): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  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: string): Set<string> => 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: FieldDefinition[] = Array.isArray(rawFields)
+        ? rawFields.filter(
+            (f): f is FieldDefinition =>
+              f !== null && typeof f === 'object' && typeof (f as { name?: unknown }).name === 'string',
+          )
+        : [];
+      const rawDefaults = inputNode.config?.defaults;
+      const defaults: Record<string, unknown> =
+        rawDefaults !== null && typeof rawDefaults === 'object' && !Array.isArray(rawDefaults)
+          ? (rawDefaults as Record<string, unknown>)
+          : {};
+      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/src/flows/anomaly-flows.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { createAnomalyFlows, createDetectEntireFlow } from './anomaly-flows';
+import { createDefaultRegistry } from '../nodes';
+import { startRun, validateFlow } from '../engine';
+
+const registry = createDefaultRegistry(0);
+
+describe('anomaly flows', () => {
+  it('all five validate cleanly against the default registry', () => {
+    const flows = createAnomalyFlows();
+    expect(flows).toHaveLength(5);
+    for (const flow of flows) {
+      expect(validateFlow(flow, registry), flow.name).toEqual([]);
+      expect(flow.folder).toBe('Anomaly API');
+    }
+  });
+
+  it('detect-entire routes to composeIncident when the series carries an anomaly', async () => {
+    const flow = createDetectEntireFlow();
+    // Pin the live detection so no HTTP is needed; build still runs locally.
+    const isAnomaly = Array.from({ length: 24 }, (_, i) => i === 20);
+    const run = await startRun({
+      flow,
+      registry,
+      pins: {
+        detect: { isAnomaly, expectedValues: [], upperMargins: [], lowerMargins: [], period: 24 },
+      },
+    }).runToEnd();
+
+    expect(run.status).toBe('succeeded');
+    expect((run.nodeStates.cond.output as { $branch: string }).$branch).toBe('anomalous');
+    expect(run.nodeStates.composeIncident.status).toBe('succeeded');
+    expect(run.nodeStates.incidentResult.status).toBe('succeeded');
+    expect(run.nodeStates.cleanResult.status).toBe('skipped');
+  });
+
+  it('detect-entire falls back to the clean branch when no anomalies are found', async () => {
+    const flow = createDetectEntireFlow();
+    const isAnomaly = Array.from({ length: 24 }, () => false);
+    const run = await startRun({
+      flow,
+      registry,
+      pins: {
+        detect: { isAnomaly, expectedValues: [], upperMargins: [], lowerMargins: [], period: 24 },
+      },
+    }).runToEnd();
+
+    expect(run.status).toBe('succeeded');
+    expect((run.nodeStates.cond.output as { $branch: string }).$branch).toBe('clean');
+    expect(run.nodeStates.cleanResult.status).toBe('succeeded');
+    expect(run.nodeStates.composeIncident.status).toBe('skipped');
+    expect(run.nodeStates.incidentResult.status).toBe('skipped');
+  });
+
+  it('quota flow reproduces the warning-email decision at 850/1000 calls', async () => {
+    const flow = createAnomalyFlows().find((f) => f.id === 'anomaly-quota-emails')!;
+    const run = await startRun({ flow, registry }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    const result = run.nodeStates.result.output as { data: { action: string } };
+    expect(result.data.action).toBe('warning');
+  });
+
+  it('key lifecycle flow fails with KEY_LIMIT_REACHED at 5 active keys', async () => {
+    const flow = createAnomalyFlows().find((f) => f.id === 'anomaly-key-lifecycle')!;
+    flow.nodes.find((n) => n.id === 'enforce')!.config.activeKeyCount = 5;
+    const run = await startRun({ flow, registry }).runToEnd();
+    expect(run.status).toBe('failed');
+    expect(run.nodeStates.enforce.error).toContain('KEY_LIMIT_REACHED');
+    expect(run.nodeStates.result.status).toBe('skipped');
+  });
+
+  it('key lifecycle flow issues a hashed ef_ak_ key under the limit', async () => {
+    const flow = createAnomalyFlows().find((f) => f.id === 'anomaly-key-lifecycle')!;
+    const run = await startRun({ flow, registry }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    const generated = run.nodeStates.generate.output as { rawKey: string; keyPrefix: string; hash: string };
+    expect(generated.rawKey).toMatch(/^ef_ak_[0-9a-f]{48}$/);
+    expect(generated.keyPrefix).toBe(generated.rawKey.slice(0, 15));
+    expect(generated.hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});

package/src/flows/anomaly-flows.ts

@@ -0,0 +1,202 @@
+import type { FieldMapping, WorkflowDefinition, WorkflowEdge, WorkflowNode } from '../engine';
+
+const FOLDER = 'Anomaly API';
+const CREATED = '2026-07-02T00:00:00Z';
+
+interface NodeSpec {
+  id: string;
+  type: string;
+  label: string;
+  config?: Record<string, unknown>;
+  inputMap?: Record<string, FieldMapping>;
+  position?: { x: number; y: number };
+}
+
+function makeFlow(
+  id: string,
+  name: string,
+  specs: NodeSpec[],
+  edges: WorkflowEdge[],
+  scenarios?: WorkflowDefinition['scenarios'],
+): WorkflowDefinition {
+  const nodes: WorkflowNode[] = specs.map((spec, i) => ({
+    id: spec.id,
+    type: spec.type,
+    label: spec.label,
+    position: spec.position ?? { x: 60 + 250 * i, y: 200 },
+    config: spec.config ?? {},
+    inputMap: spec.inputMap,
+  }));
+  return {
+    id,
+    name,
+    version: 1,
+    folder: FOLDER,
+    nodes,
+    edges,
+    ...(scenarios ? { scenarios } : {}),
+    createdAt: CREATED,
+    updatedAt: CREATED,
+  };
+}
+
+const from = (sourceNodeId: string, sourceField: string): FieldMapping => ({ sourceNodeId, sourceField });
+
+/**
+ * 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 function createDetectEntireFlow(): WorkflowDefinition {
+  return makeFlow(
+    'anomaly-detect-entire',
+    'Detect · Entire Series',
+    [
+      { id: 'input', type: 'Input', label: 'Series Request', config: { fields: [{ name: 'points', type: 'number', required: true }, { name: 'spikeIndex', type: 'number' }], defaults: { points: 24, spikeIndex: 20 } }, position: { x: -180, y: 240 } },
+      { id: 'build', type: 'BuildSeries', label: 'Build Series', config: { points: 24, baseValue: 100, spikeIndex: 20, spikeFactor: 3 }, inputMap: { points: from('input', 'points'), spikeIndex: from('input', 'spikeIndex') }, position: { x: 60, y: 240 } },
+      { id: 'detect', type: 'DetectEntireSeries', label: 'Detect Entire Series', config: { apiKey: 'dev-emberflow', sensitivity: 80 }, inputMap: { series: from('build', 'series') }, position: { x: 300, y: 240 } },
+      { id: 'summarize', type: 'SummarizeAnomalies', label: 'Summarize Anomalies', inputMap: { isAnomaly: from('detect', 'isAnomaly'), series: from('build', 'series') }, position: { x: 540, y: 240 } },
+      { id: 'cond', type: 'Conditional', label: 'Severity?', config: { branches: [{ name: 'anomalous', op: 'gt', value: 0 }], fallback: 'clean' }, inputMap: { value: from('summarize', 'anomalyCount') }, position: { x: 1020, y: 240 } },
+      { id: 'composeIncident', type: 'ComposeIncident', label: 'Compose Incident', inputMap: { headline: from('summarize', 'headline'), anomalyCount: from('summarize', 'anomalyCount') }, position: { x: 1260, y: 120 } },
+      { id: 'incidentResult', type: 'Result', label: 'Incident', inputMap: { data: from('composeIncident', '$') }, position: { x: 1500, y: 120 } },
+      { id: 'cleanResult', type: 'Result', label: 'All Clear', inputMap: { data: from('summarize', '$') }, position: { x: 1260, y: 360 } },
+    ],
+    [
+      { id: 'e0', source: 'input', target: 'build', targetHandle: 'points' },
+      { id: 'e1', source: 'build', target: 'detect', targetHandle: 'series' },
+      { id: 'e2', source: 'detect', target: 'summarize', targetHandle: 'isAnomaly' },
+      { id: 'e3', source: 'build', target: 'summarize', targetHandle: 'series' },
+      { id: 'e4', source: 'summarize', target: 'cond', targetHandle: 'value' },
+      { id: 'e6', source: 'cond', target: 'composeIncident', sourceHandle: 'anomalous' },
+      { id: 'e7', source: 'cond', target: 'cleanResult', sourceHandle: 'clean' },
+      { id: 'e8', source: 'composeIncident', target: 'incidentResult', targetHandle: 'data' },
+    ],
+    [
+      {
+        id: 'scn-spike',
+        name: 'spike at 20',
+        description: '×3 spike — detector flags it, incident branch fires',
+        input: { points: 24, spikeIndex: 20 },
+      },
+      {
+        id: 'scn-flat',
+        name: 'flat series',
+        description: 'no spike (spikeIndex −1) — clean branch, all clear',
+        input: { points: 24, spikeIndex: -1 },
+      },
+    ],
+  );
+}
+
+/** Live call: streaming-style last-point verdict. */
+export function createDetectLastFlow(): WorkflowDefinition {
+  return makeFlow(
+    'anomaly-detect-last',
+    'Detect · Last Point',
+    [
+      { id: 'build', type: 'BuildSeries', label: 'Build Series (spike at end)', config: { points: 14, baseValue: 50, spikeIndex: 13, spikeFactor: 4 } },
+      { id: 'detect', type: 'DetectLastPoint', label: 'Detect Last Point', config: { apiKey: 'dev-emberflow', sensitivity: 80 }, inputMap: { series: from('build', 'series') } },
+      { id: 'result', type: 'Result', label: 'Verdict', inputMap: { data: from('detect', '$') } },
+    ],
+    [
+      { id: 'e1', source: 'build', target: 'detect', targetHandle: 'series' },
+      { id: 'e2', source: 'detect', target: 'result', targetHandle: 'data' },
+    ],
+  );
+}
+
+/** Live call: detection + Adtributor root-cause analysis. */
+export function createRootCauseFlow(): WorkflowDefinition {
+  return makeFlow(
+    'anomaly-root-cause',
+    'Detect · Root Cause',
+    [
+      { id: 'build', type: 'BuildDimensionalSeries', label: 'Build Dimensional Series', config: { points: 14, baseValue: 100, spikeIndex: 12, culpritSlice: 'paid' } },
+      { id: 'detect', type: 'DetectAttributed', label: 'Detect + Attribute', config: { apiKey: 'dev-emberflow', sensitivity: 80, topK: 3 }, inputMap: { series: from('build', 'series') } },
+      { id: 'extract', type: 'ExtractRootCause', label: 'Extract Root Cause', inputMap: { rca: from('detect', 'rca') } },
+      { id: 'result', type: 'Result', label: 'Root Cause', inputMap: { data: from('extract', '$') } },
+    ],
+    [
+      { id: 'e1', source: 'build', target: 'detect', targetHandle: 'series' },
+      { id: 'e2', source: 'detect', target: 'extract', targetHandle: 'rca' },
+      { id: 'e3', source: 'extract', target: 'result', targetHandle: 'data' },
+    ],
+  );
+}
+
+/** Replica of today's quota/email business logic (Clerk-gated server-side). */
+export function createQuotaFlow(): WorkflowDefinition {
+  return makeFlow(
+    'anomaly-quota-emails',
+    'Quota · Usage & Emails',
+    [
+      { id: 'input', type: 'Input', label: 'Usage Snapshot', config: { fields: [{ name: 'calls', type: 'number', required: true }], defaults: { calls: 850 } } },
+      { id: 'plan', type: 'PlanCatalog', label: 'Plan Catalog', config: { planCode: 'anomaly_free' } },
+      { id: 'usage', type: 'UsageState', label: 'Usage State', config: { calls: 850 }, inputMap: { calls: from('input', 'calls'), quota: from('plan', 'quota') } },
+      { id: 'classify', type: 'ClassifyQuotaEmail', label: 'Classify Quota Email', config: { alreadyWarned: false, alreadyNotifiedExceeded: false }, inputMap: { warn80: from('usage', 'warn80'), overQuota: from('usage', 'overQuota') } },
+      { id: 'result', type: 'Result', label: 'Sweep Decision', inputMap: { data: from('classify', '$') } },
+    ],
+    [
+      { id: 'e0', source: 'input', target: 'usage', targetHandle: 'calls' },
+      { id: 'e1', source: 'plan', target: 'usage', targetHandle: 'quota' },
+      { id: 'e2', source: 'usage', target: 'classify', targetHandle: 'warn80' },
+      { id: 'e3', source: 'classify', target: 'result', targetHandle: 'data' },
+    ],
+    // Free plan quota is 1,000 calls: the three scenarios straddle the
+    // warn-at-80% and exceeded thresholds in classifyUsageRow().
+    [
+      {
+        id: 'scn-quiet',
+        name: 'quiet month',
+        description: '400/1000 calls — no email',
+        input: { calls: 400 },
+      },
+      {
+        id: 'scn-warn',
+        name: 'approaching limit',
+        description: '850/1000 calls — 80% warning email',
+        input: { calls: 850 },
+      },
+      {
+        id: 'scn-over',
+        name: 'over quota',
+        description: '1200/1000 calls — exceeded email',
+        input: { calls: 1200 },
+      },
+    ],
+  );
+}
+
+/** Replica of today's key issuance + 5-key limit guard. */
+export function createKeyLifecycleFlow(): WorkflowDefinition {
+  return makeFlow(
+    'anomaly-key-lifecycle',
+    'Keys · Issue & Limit',
+    [
+      { id: 'generate', type: 'GenerateApiKey', label: 'Generate API Key', config: { label: 'production' } },
+      { id: 'enforce', type: 'EnforceKeyLimit', label: 'Enforce Key Limit', config: { activeKeyCount: 3 }, inputMap: { keyPrefix: from('generate', 'keyPrefix') } },
+      { id: 'result', type: 'Result', label: 'Issued Key', inputMap: { data: from('enforce', '$') } },
+    ],
+    [
+      { id: 'e1', source: 'generate', target: 'enforce', targetHandle: 'keyPrefix' },
+      { id: 'e2', source: 'enforce', target: 'result', targetHandle: 'data' },
+    ],
+  );
+}
+
+export function createAnomalyFlows(): WorkflowDefinition[] {
+  return [
+    createDetectEntireFlow(),
+    createDetectLastFlow(),
+    createRootCauseFlow(),
+    createQuotaFlow(),
+    createKeyLifecycleFlow(),
+  ];
+}