@xdelivered/emberflow 0.2.0

package/src/nodes/flow-control.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest';
+import { createDefaultRegistry } from './index';
+import { startRun } from '../engine';
+import type { LogLine, WorkflowDefinition, WorkflowRun } from '../engine';
+
+const inputOnlyFlow = (): WorkflowDefinition => ({
+  id: 'input-only',
+  name: 'Input Only',
+  version: 1,
+  nodes: [
+    {
+      id: 'input',
+      type: 'Input',
+      label: 'Input',
+      position: { x: 0, y: 0 },
+      config: {
+        fields: [
+          { name: 'username', type: 'string', required: true },
+          { name: 'password', type: 'string', required: true },
+        ],
+        defaults: { username: 'ada' },
+      },
+    },
+  ],
+  edges: [],
+  createdAt: '2026-07-02T00:00:00Z',
+  updatedAt: '2026-07-02T00:00:00Z',
+});
+
+describe('Input node', () => {
+  it('fails listing the missing required field(s)', async () => {
+    const run = await startRun({ flow: inputOnlyFlow(), registry: createDefaultRegistry(0) }).runToEnd();
+    expect(run.status).toBe('failed');
+    expect(run.nodeStates.input.error).toBe('Missing required input field(s): password');
+  });
+
+  it('merges the invocation payload over configured defaults', async () => {
+    const run = await startRun({
+      flow: inputOnlyFlow(),
+      registry: createDefaultRegistry(0),
+      input: { password: 'lovelace' },
+    }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect(run.nodeStates.input.output).toEqual({ username: 'ada', password: 'lovelace' });
+  });
+});
+
+const environmentFlow = (): WorkflowDefinition => ({
+  id: 'environment-only',
+  name: 'Environment Only',
+  version: 1,
+  nodes: [
+    { id: 'env', type: 'Environment', label: 'Environment', position: { x: 0, y: 0 }, config: {} },
+  ],
+  edges: [],
+  createdAt: '2026-07-05T00:00:00Z',
+  updatedAt: '2026-07-05T00:00:00Z',
+});
+
+describe('Environment node', () => {
+  it('passes the run environment through to its output', async () => {
+    const run = await startRun({
+      flow: environmentFlow(),
+      registry: createDefaultRegistry(0),
+      environment: 'prod',
+    }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect(run.nodeStates.env.output).toEqual({ environment: 'prod', isProd: true });
+  });
+
+  it('defaults to "local" (isProd false) when the run carries no environment', async () => {
+    const run = await startRun({
+      flow: environmentFlow(),
+      registry: createDefaultRegistry(0),
+    }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect(run.nodeStates.env.output).toEqual({ environment: 'local', isProd: false });
+  });
+
+  it('isProd is false for any non-prod environment name', async () => {
+    const run = await startRun({
+      flow: environmentFlow(),
+      registry: createDefaultRegistry(0),
+      environment: 'dev',
+    }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect(run.nodeStates.env.output).toEqual({ environment: 'dev', isProd: false });
+  });
+});
+
+const conditionalFlow = (
+  value: unknown,
+  branches: unknown[],
+  fallback?: string,
+): WorkflowDefinition => ({
+  id: 'conditional-only',
+  name: 'Conditional Only',
+  version: 1,
+  nodes: [
+    {
+      id: 'cond',
+      type: 'Conditional',
+      label: 'Conditional',
+      position: { x: 0, y: 0 },
+      config: { value, branches, ...(fallback !== undefined ? { fallback } : {}) },
+    },
+  ],
+  edges: [],
+  createdAt: '2026-07-03T00:00:00Z',
+  updatedAt: '2026-07-03T00:00:00Z',
+});
+
+async function runConditional(
+  value: unknown,
+  branches: unknown[],
+  fallback?: string,
+): Promise<{ run: WorkflowRun; logs: LogLine[] }> {
+  const logs: LogLine[] = [];
+  const run = await startRun({
+    flow: conditionalFlow(value, branches, fallback),
+    registry: createDefaultRegistry(0),
+    events: { onLog: (line) => logs.push(line) },
+  }).runToEnd();
+  return { run, logs };
+}
+
+describe('Conditional node', () => {
+  it('matches eq on strict equality', async () => {
+    const { run } = await runConditional('active', [{ name: 'A', op: 'eq', value: 'active' }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 'active', $branch: 'A' });
+  });
+
+  it('matches eq on numeric-looking values of different types', async () => {
+    const { run } = await runConditional('3', [{ name: 'A', op: 'eq', value: 3 }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: '3', $branch: 'A' });
+  });
+
+  it('neq matches when values differ', async () => {
+    const { run } = await runConditional('active', [{ name: 'A', op: 'neq', value: 'inactive' }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 'active', $branch: 'A' });
+  });
+
+  it('neq does not match equal (numeric-looking) values', async () => {
+    const { run } = await runConditional('3', [
+      { name: 'A', op: 'neq', value: 3 },
+      { name: 'B', op: 'eq', value: 3 },
+    ]);
+    expect(run.nodeStates.cond.output).toEqual({ value: '3', $branch: 'B' });
+  });
+
+  it('gt matches with Number() coercion', async () => {
+    const { run } = await runConditional('5', [{ name: 'A', op: 'gt', value: 3 }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: '5', $branch: 'A' });
+  });
+
+  it('gte matches at the boundary', async () => {
+    const { run } = await runConditional(3, [{ name: 'A', op: 'gte', value: 3 }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 3, $branch: 'A' });
+  });
+
+  it('lt matches with Number() coercion', async () => {
+    const { run } = await runConditional(1, [{ name: 'A', op: 'lt', value: 3 }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 1, $branch: 'A' });
+  });
+
+  it('lte matches at the boundary', async () => {
+    const { run } = await runConditional(3, [{ name: 'A', op: 'lte', value: 3 }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 3, $branch: 'A' });
+  });
+
+  it('contains matches substrings on strings', async () => {
+    const { run } = await runConditional('hello world', [{ name: 'A', op: 'contains', value: 'world' }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 'hello world', $branch: 'A' });
+  });
+
+  it('contains matches membership on arrays', async () => {
+    const { run } = await runConditional(['a', 'b'], [{ name: 'A', op: 'contains', value: 'b' }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: ['a', 'b'], $branch: 'A' });
+  });
+
+  it('contains does not match non-string, non-array input', async () => {
+    const { run } = await runConditional(42, [
+      { name: 'A', op: 'contains', value: 4 },
+      { name: 'fallback', op: 'exists', value: undefined },
+    ]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 42, $branch: 'fallback' });
+  });
+
+  it('exists matches defined, non-null input', async () => {
+    const { run } = await runConditional(0, [{ name: 'A', op: 'exists' }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 0, $branch: 'A' });
+  });
+
+  it('exists does not match null or undefined input', async () => {
+    const { run } = await runConditional(null, [
+      { name: 'A', op: 'exists' },
+      { name: 'B', op: 'truthy' },
+    ], 'clean');
+    expect(run.nodeStates.cond.output).toEqual({ value: null, $branch: 'clean' });
+  });
+
+  it('truthy matches non-falsy input', async () => {
+    const { run } = await runConditional('x', [{ name: 'A', op: 'truthy' }]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 'x', $branch: 'A' });
+  });
+
+  it('truthy does not match falsy input', async () => {
+    const { run } = await runConditional(0, [{ name: 'A', op: 'truthy' }], 'clean');
+    expect(run.nodeStates.cond.output).toEqual({ value: 0, $branch: 'clean' });
+  });
+
+  it('first matching rule wins, in order', async () => {
+    const { run } = await runConditional(5, [
+      { name: 'P1', op: 'gt', value: 3 },
+      { name: 'P2', op: 'gt', value: 0 },
+    ]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 5, $branch: 'P1' });
+  });
+
+  it('falls back to the configured fallback branch when no rule matches', async () => {
+    const { run } = await runConditional(-1, [
+      { name: 'P1', op: 'gt', value: 3 },
+      { name: 'P2', op: 'gt', value: 0 },
+    ], 'clean');
+    expect(run.nodeStates.cond.output).toEqual({ value: -1, $branch: 'clean' });
+  });
+
+  it('fails when no rule matches and no fallback is configured', async () => {
+    const { run } = await runConditional(-1, [{ name: 'P1', op: 'gt', value: 3 }]);
+    expect(run.status).toBe('failed');
+    expect(run.nodeStates.cond.error).toBe('Conditional: no rule matched and no fallback is set');
+  });
+
+  it('non-numeric input on a numeric op falls through to the fallback', async () => {
+    const { run } = await runConditional('not-a-number', [
+      { name: 'P1', op: 'gt', value: 3 },
+    ], 'clean');
+    expect(run.nodeStates.cond.output).toEqual({ value: 'not-a-number', $branch: 'clean' });
+  });
+
+  it('skips a malformed rule (missing name) with a warn log and keeps evaluating', async () => {
+    const { run, logs } = await runConditional(5, [
+      { op: 'gt', value: 3 },
+      { name: 'P2', op: 'gt', value: 0 },
+    ]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 5, $branch: 'P2' });
+    expect(logs.some((l) => l.level === 'warn' && l.message.includes('malformed rule'))).toBe(true);
+  });
+
+  it('skips a malformed rule (unknown op) with a warn log and keeps evaluating', async () => {
+    const { run, logs } = await runConditional(5, [
+      { name: 'P1', op: 'between', value: [0, 10] },
+      { name: 'P2', op: 'gt', value: 0 },
+    ]);
+    expect(run.nodeStates.cond.output).toEqual({ value: 5, $branch: 'P2' });
+    expect(logs.some((l) => l.level === 'warn' && l.message.includes('malformed rule'))).toBe(true);
+  });
+});
+
+describe('Conditional numeric-coercion guards', () => {
+  it('eq 0 does not match null, empty string, or empty array', async () => {
+    for (const input of [null, '', []]) {
+      const { run } = await runConditional(
+        input,
+        [{ name: 'zero', op: 'eq', value: 0 }],
+        'other',
+      );
+      expect(run.nodeStates.cond.output).toEqual({ value: input, $branch: 'other' });
+    }
+  });
+
+  it('gt -1 does not match null', async () => {
+    const { run } = await runConditional(
+      null,
+      [{ name: 'pos', op: 'gt', value: -1 }],
+      'other',
+    );
+    expect(run.nodeStates.cond.output).toEqual({ value: null, $branch: 'other' });
+  });
+});

package/src/nodes/flow-control.ts

@@ -0,0 +1,305 @@
+import { getByPath } from '../engine';
+import type { NodeRegistry } from '../engine';
+
+/** A single Conditional rule row: `{ name, op, value? }`. */
+interface ConditionalRule {
+  name?: unknown;
+  op?: unknown;
+  value?: unknown;
+}
+
+const CONDITIONAL_OPS = new Set([
+  'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'exists', 'truthy',
+]);
+
+/**
+ * Only numbers and non-empty numeric strings take part in numeric coercion —
+ * Number(null), Number(''), and Number([]) are all 0, which would make
+ * `eq 0` match null/''/[] and `gt -1` match null.
+ */
+function asComparableNumber(v: unknown): number {
+  if (typeof v === 'number') return v;
+  if (typeof v === 'string' && v.trim() !== '') return Number(v);
+  return NaN;
+}
+
+/** eq/neq base: strict equality, plus numeric-looking equality (`Number()` on both sides). */
+function looksEqual(input: unknown, comparand: unknown): boolean {
+  if (input === comparand) return true;
+  const a = asComparableNumber(input);
+  const b = asComparableNumber(comparand);
+  return !Number.isNaN(a) && !Number.isNaN(b) && a === b;
+}
+
+function numericMatch(op: 'gt' | 'gte' | 'lt' | 'lte', input: unknown, comparand: unknown): boolean {
+  const a = asComparableNumber(input);
+  const b = asComparableNumber(comparand);
+  if (Number.isNaN(a) || Number.isNaN(b)) return false;
+  switch (op) {
+    case 'gt': return a > b;
+    case 'gte': return a >= b;
+    case 'lt': return a < b;
+    case 'lte': return a <= b;
+  }
+}
+
+function ruleMatches(op: string, input: unknown, comparand: unknown): boolean {
+  switch (op) {
+    case 'eq': return looksEqual(input, comparand);
+    case 'neq': return !looksEqual(input, comparand);
+    case 'gt': case 'gte': case 'lt': case 'lte':
+      return numericMatch(op, input, comparand);
+    case 'contains':
+      if (typeof input === 'string') return input.includes(String(comparand));
+      if (Array.isArray(input)) return input.includes(comparand);
+      return false;
+    case 'exists':
+      return input !== undefined && input !== null;
+    case 'truthy':
+      return Boolean(input);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Flow-control nodes. Route reads a field from its input object and emits
+ * `$branch`; the executor then skips downstream nodes hanging off untaken
+ * branch handles (edge.sourceHandle = branch name).
+ */
+export function registerFlowControlNodes(registry: NodeRegistry): void {
+  registry.register(
+    {
+      type: 'Input',
+      label: 'Input',
+      description:
+        'Entry point — emits the payload the run was invoked with (falling back to configured defaults).',
+      simpleDescription: 'Starts the run with its input data',
+      category: 'input',
+      traceKind: 'compute',
+      tags: ['entry'],
+      configSchema: {
+        fields: [
+          { name: 'fields', type: 'array' },
+          { name: 'defaults', type: 'object' },
+        ],
+      },
+      // Dynamic — the emitted shape depends on the configured fields.
+      outputSchema: { fields: [] },
+    },
+    async (ctx) => {
+      const merged = {
+        ...((ctx.config.defaults as Record<string, unknown>) ?? {}),
+        ...ctx.runInput,
+      };
+      const declared = Array.isArray(ctx.config.fields)
+        ? (ctx.config.fields as { name: string; required?: boolean }[])
+        : [];
+      const missing = declared
+        .filter((f) => f.required && merged[f.name] === undefined)
+        .map((f) => f.name);
+      if (missing.length) {
+        throw new Error(`Missing required input field(s): ${missing.join(', ')}`);
+      }
+      const summary = JSON.stringify(merged);
+      // Full JSON, untruncated: the log UI renders parseable payloads as
+      // collapsible highlighted blocks — a sliced tail breaks the parse and
+      // regresses to a wall of escaped text.
+      ctx.log('info', `Run input: ${summary}`);
+      return merged;
+    },
+  );
+
+  registry.register(
+    {
+      type: 'Environment',
+      label: 'Environment',
+      description:
+        'Reports the environment this run targets. Emits `environment` (the run\'s target environment name, e.g. "prod"; "local" when the run carries none) and `isProd` (a convenience boolean, true only when environment === "prod"). PORT NOTE: the name comes from the run\'s target environment threaded through node ctx (ctx.environment) — it is undefined for browser/in-tab runs, which report "local". `isProd` exists so the common case (branch on "is this production?") is a one-field Conditional; branch on `environment` directly for finer-grained routing.',
+      simpleDescription: 'Reports which environment this run targets, so steps can branch on it.',
+      category: 'logic',
+      traceKind: 'compute',
+      tags: ['branching'],
+      // No inputs — the environment is read from the run context.
+      inputSchema: { fields: [] },
+      outputSchema: {
+        fields: [
+          { name: 'environment', type: 'string' },
+          { name: 'isProd', type: 'boolean' },
+        ],
+      },
+    },
+    async (ctx) => {
+      const environment = ctx.environment ?? 'local';
+      const isProd = environment === 'prod';
+      ctx.log('info', `Environment: ${environment} (isProd=${isProd})`);
+      return { environment, isProd };
+    },
+  );
+
+  registry.register(
+    {
+      type: 'Route',
+      label: 'Route',
+      description:
+        'Branches the flow on a field of its input. Edges leaving a named branch handle only run when that branch matches.',
+      simpleDescription: 'Sends the data down a different path based on one value',
+      category: 'logic',
+      traceKind: 'compute',
+      tags: ['branching'],
+      inputSchema: {
+        fields: [{ name: 'value', type: 'object', required: true }],
+      },
+      configSchema: {
+        fields: [
+          { name: 'field', type: 'string', required: true },
+          { name: 'branches', type: 'array', required: true },
+          { name: 'fallback', type: 'string' },
+        ],
+      },
+      outputSchema: {
+        fields: [{ name: '$branch', type: 'string' }],
+      },
+    },
+    async (ctx) => {
+      const value = (ctx.input.value ?? {}) as Record<string, unknown>;
+      const field = String(ctx.config.field ?? '');
+      const branches = Array.isArray(ctx.config.branches)
+        ? (ctx.config.branches as unknown[]).map(String)
+        : [];
+      const raw = getByPath(value, field);
+      const candidate = String(raw);
+      let branch: string | undefined = branches.includes(candidate) ? candidate : undefined;
+      if (branch === undefined && typeof ctx.config.fallback === 'string' && ctx.config.fallback) {
+        branch = ctx.config.fallback;
+      }
+      if (branch === undefined) {
+        throw new Error(
+          `Route: "${field}" resolved to "${candidate}", which matches no branch and no fallback is set`,
+        );
+      }
+      ctx.log('info', `Routing ${field}=${candidate} → branch "${branch}"`);
+      return { ...value, $branch: branch };
+    },
+  );
+
+  registry.register(
+    {
+      type: 'Conditional',
+      label: 'Conditional',
+      description:
+        'Branches the flow on an ordered set of rules evaluated against its input. The first matching rule wins; edges leaving a named branch handle only run when that branch matches.',
+      simpleDescription: 'Chooses a path based on the data',
+      category: 'logic',
+      traceKind: 'compute',
+      tags: ['branching'],
+      inputSchema: {
+        fields: [{ name: 'value', type: 'object', required: true }],
+      },
+      configSchema: {
+        fields: [
+          { name: 'branches', type: 'array', required: true },
+          { name: 'fallback', type: 'string' },
+        ],
+      },
+      outputSchema: {
+        fields: [{ name: '$branch', type: 'string' }],
+      },
+    },
+    async (ctx) => {
+      const value = ctx.input.value;
+      const rules = Array.isArray(ctx.config.branches) ? (ctx.config.branches as unknown[]) : [];
+      let branch: string | undefined;
+      for (const raw of rules) {
+        const rule = (raw !== null && typeof raw === 'object' ? raw : {}) as ConditionalRule;
+        const name = typeof rule.name === 'string' && rule.name ? rule.name : undefined;
+        const op = typeof rule.op === 'string' ? rule.op : undefined;
+        if (!name || !op || !CONDITIONAL_OPS.has(op)) {
+          ctx.log('warn', `Conditional: skipping malformed rule ${JSON.stringify(raw)}`);
+          continue;
+        }
+        if (ruleMatches(op, value, rule.value)) {
+          branch = name;
+          break;
+        }
+      }
+      if (branch === undefined && typeof ctx.config.fallback === 'string' && ctx.config.fallback) {
+        branch = ctx.config.fallback;
+      }
+      if (branch === undefined) {
+        throw new Error('Conditional: no rule matched and no fallback is set');
+      }
+      ctx.log('info', `Conditional matched → branch "${branch}"`);
+      return { value, $branch: branch };
+    },
+  );
+
+  registry.register(
+    {
+      type: 'Merge',
+      label: 'Merge',
+      description:
+        'Coalesces converging branch arms into one value: emits `value` = the first of its mapped inputs that is neither undefined nor null, in inputMap declaration order. PORT NOTE: the engine leaves an inputMap field undefined when its source node was skipped (an untaken branch arm), so wiring one input per arm makes `value` resolve to whichever arm actually ran. Use it as the join point after a Conditional whose arms each produce the same downstream value from a DIFFERENT node.',
+      simpleDescription: 'Joins branch paths — passes on whichever arm produced a value.',
+      category: 'logic',
+      traceKind: 'compute',
+      tags: ['branching'],
+      // Free-form: the converging arm values are supplied via inputMap, one
+      // field per arm; declaration order sets coalesce priority.
+      inputSchema: { fields: [] },
+      outputSchema: {
+        fields: [{ name: 'value', type: 'object' }],
+      },
+    },
+    async (ctx) => {
+      const entries = Object.entries(ctx.input);
+      const chosen = entries.find(([, v]) => v !== undefined && v !== null);
+      if (!chosen) {
+        ctx.log('warn', 'Merge: no incoming arm produced a value');
+        return { value: undefined };
+      }
+      ctx.log('info', `Merge: passing on value from "${chosen[0]}"`);
+      return { value: chosen[1] };
+    },
+  );
+
+  registry.register(
+    {
+      type: 'Subflow',
+      label: 'Subflow',
+      description:
+        'Runs another workflow to completion with the mapped input, then emits that child run\'s collected output.',
+      simpleDescription: 'Runs another workflow and uses its result',
+      category: 'logic',
+      traceKind: 'compute',
+      tags: ['subflow'],
+      // Free-form input: whatever is mapped onto this node becomes the child
+      // run's invocation payload (like an Input node's run input).
+      inputSchema: { fields: [] },
+      configSchema: {
+        fields: [{ name: 'workflowId', type: 'string', required: true }],
+      },
+      // Dynamic — the emitted shape is the child flow's Result output.
+      outputSchema: { fields: [] },
+    },
+    async (ctx) => {
+      const workflowId = String(ctx.config.workflowId ?? '');
+      if (!workflowId) throw new Error('Subflow: no workflowId configured');
+      if (!ctx.runSubflow) {
+        throw new Error('subflows need a host that can look up workflows');
+      }
+      ctx.log('info', `Running subflow "${workflowId}"`);
+      const result = await ctx.runSubflow(workflowId, ctx.input);
+      if (result.status === 'failed') {
+        throw new Error(result.error ?? 'subflow failed');
+      }
+      const output = result.output;
+      // Spread a plain object so downstream nodes can map its fields directly;
+      // wrap anything else under `output`.
+      if (output !== null && typeof output === 'object' && !Array.isArray(output)) {
+        return { ...(output as Record<string, unknown>) };
+      }
+      return { output };
+    },
+  );
+}

package/src/nodes/index.ts

@@ -0,0 +1,22 @@
+import type { NodeRegistry } from '../engine';
+import { createLoginRegistry } from './login';
+import { registerWeatherNodes } from './weather';
+import { registerAnomalyNodes } from './anomaly';
+import { registerFlowControlNodes } from './flow-control';
+import { registerLoopNodes } from './loops';
+import { registerPradarNodesModule } from './pradar';
+import { registerResponseNodes } from './response';
+import { registerRequireAuthNode } from './requireAuth';
+
+/** All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth. */
+export function createDefaultRegistry(delayMs?: number): NodeRegistry {
+  const registry = createLoginRegistry(delayMs);
+  registerWeatherNodes(registry);
+  registerAnomalyNodes(registry);
+  registerFlowControlNodes(registry);
+  registerLoopNodes(registry);
+  registerPradarNodesModule(registry);
+  registerResponseNodes(registry);
+  registerRequireAuthNode(registry);
+  return registry;
+}

package/src/nodes/login.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { createLoginRegistry } from './login';
+import { createDefaultRegistry } from './index';
+import { createLoginFlow } from '../flows/login-flow';
+import { startRun } from '../engine';
+
+describe('login example', () => {
+  it('registers the five login nodes', () => {
+    const types = createLoginRegistry(0).list().map((d) => d.type);
+    expect(types).toEqual(
+      expect.arrayContaining(['ValidateCredentials', 'FetchUser', 'CheckPlan', 'IssueToken', 'Result']),
+    );
+  });
+
+  it('runs the prebuilt flow end to end', async () => {
+    const run = await startRun({ flow: createLoginFlow(), registry: createDefaultRegistry(0) }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    const result = Object.values(run.nodeStates).find((s) => (s.output as any)?.token !== undefined);
+    expect(result).toBeDefined();
+  });
+
+  it('result node output contains the token', async () => {
+    const flow = createLoginFlow();
+    const run = await startRun({ flow, registry: createDefaultRegistry(0) }).runToEnd();
+    const resultNode = flow.nodes.find((n) => n.type === 'Result')!;
+    expect((run.nodeStates[resultNode.id].output as any).data.token).toBe('tok_user-ada');
+  });
+
+  it('fails on short password', async () => {
+    const flow = createLoginFlow();
+    (flow.nodes.find((n) => n.id === 'input')!.config.defaults as Record<string, unknown>).password = 'x';
+    const run = await startRun({ flow, registry: createDefaultRegistry(0) }).runToEnd();
+    expect(run.status).toBe('failed');
+  });
+
+  it('takes the welcome branch for a run invoked with a new-user payload', async () => {
+    const run = await startRun({
+      flow: createLoginFlow(),
+      registry: createDefaultRegistry(0),
+      input: { username: 'new-zoe', password: 'longenough' },
+    }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect((run.nodeStates.route.output as any).$branch).toBe('true');
+    expect(run.nodeStates.welcome.status).toBe('succeeded');
+    expect((run.nodeStates.issueToken.output as any).token).toBe('tok_user-new-zoe');
+  });
+
+  it('falls back to configured defaults when invoked with no input', async () => {
+    const run = await startRun({
+      flow: createLoginFlow(),
+      registry: createDefaultRegistry(0),
+    }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect((run.nodeStates.issueToken.output as any).token).toBe('tok_user-ada');
+  });
+
+  it('existing user (ada) routes through checkPlan and skips welcome', async () => {
+    const flow = createLoginFlow();
+    const run = await startRun({ flow, registry: createDefaultRegistry(0) }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect(run.nodeStates.route.status).toBe('succeeded');
+    expect((run.nodeStates.route.output as any).$branch).toBe('existing');
+    expect(run.nodeStates.checkPlan.status).toBe('succeeded');
+    expect(run.nodeStates.welcome.status).toBe('skipped');
+    expect(run.nodeStates.issueToken.status).toBe('succeeded');
+  });
+
+  it('new user (new-ada) routes through welcome and skips checkPlan', async () => {
+    const flow = createLoginFlow();
+    (flow.nodes.find((n) => n.id === 'input')!.config.defaults as Record<string, unknown>).username = 'new-ada';
+    const run = await startRun({ flow, registry: createDefaultRegistry(0) }).runToEnd();
+    expect(run.status).toBe('succeeded');
+    expect((run.nodeStates.route.output as any).$branch).toBe('true');
+    expect(run.nodeStates.welcome.status).toBe('succeeded');
+    expect((run.nodeStates.welcome.output as any).message).toBe('Welcome aboard, new-ada!');
+    expect(run.nodeStates.checkPlan.status).toBe('skipped');
+    expect(run.nodeStates.issueToken.status).toBe('succeeded');
+    // checkPlan skipped → plan input undefined → IssueToken defaults to 'free'.
+    expect((run.nodeStates.issueToken.output as any).plan).toBe('free');
+  });
+});