@kiberon-labs/behave-graph-suspendable 1.0.1

package/tests/coreNodeSuspension.test.ts

@@ -0,0 +1,143 @@
+import type { GraphJSON } from '@kiberon-labs/behave-graph';
+import { describe, expect, it } from 'vitest';
+import { makeRecorderDescription } from './fixtures/testNodes';
+import { makeTestEngine } from './testUtils';
+
+/**
+ * Core flow nodes keep their cursors in node state (not closures), so the
+ * engine can capture them generically — no ISuspendable implementation needed.
+ * These tests run the unmodified core `flow/forLoop` and `flow/sequence`
+ * through a mid-execution suspension round-trip.
+ */
+
+const COMPLETED = 999;
+
+const forLoopGraph: GraphJSON = {
+  variables: [],
+  customEvents: [],
+  nodes: [
+    {
+      type: 'lifecycle/onStart',
+      id: '0',
+      flows: { flow: { nodeId: '1', socket: 'flow' } }
+    },
+    {
+      type: 'flow/forLoop',
+      id: '1',
+      parameters: {
+        startIndex: { value: 0 },
+        endIndex: { value: 5 }
+      },
+      flows: {
+        loopBody: { nodeId: '2', socket: 'flow' },
+        completed: { nodeId: '3', socket: 'flow' }
+      }
+    },
+    {
+      type: 'test/recorder',
+      id: '2',
+      parameters: { index: { link: { nodeId: '1', socket: 'index' } } }
+    },
+    {
+      type: 'test/recorder',
+      id: '3',
+      parameters: { index: { value: COMPLETED } }
+    }
+  ]
+};
+
+/** flow/sequence with three outputs, each reporting a distinct marker. */
+const sequenceGraph: GraphJSON = {
+  variables: [],
+  customEvents: [],
+  nodes: [
+    {
+      type: 'lifecycle/onStart',
+      id: '0',
+      flows: { flow: { nodeId: '1', socket: 'flow' } }
+    },
+    {
+      type: 'flow/sequence',
+      id: '1',
+      configuration: { numOutputs: 3 },
+      flows: {
+        1: { nodeId: '2', socket: 'flow' },
+        2: { nodeId: '3', socket: 'flow' },
+        3: { nodeId: '4', socket: 'flow' }
+      }
+    },
+    {
+      type: 'test/recorder',
+      id: '2',
+      parameters: { index: { value: 1 } }
+    },
+    {
+      type: 'test/recorder',
+      id: '3',
+      parameters: { index: { value: 2 } }
+    },
+    {
+      type: 'test/recorder',
+      id: '4',
+      parameters: { index: { value: 3 } }
+    }
+  ]
+};
+
+const makeEngineWithRecorder = (
+  graph: GraphJSON,
+  record: (index: number) => void
+) =>
+  makeTestEngine(graph, { 'test/recorder': makeRecorderDescription(record) });
+
+describe('core flow/forLoop across suspension', () => {
+  it('resumes the remaining iterations instead of restarting', async () => {
+    const firstRun: number[] = [];
+    const first = makeEngineWithRecorder(forLoopGraph, (i) => firstRun.push(i));
+
+    first.start();
+    await first.engine.executeAllSync(100, 4);
+    expect(firstRun).toEqual([0, 1, 2]);
+
+    const suspension = first.engine.suspend();
+    // the loop cursor is captured from node state, generically
+    expect(suspension.nodes['1']).toEqual({ nextIndex: 3 });
+
+    const persisted = JSON.parse(JSON.stringify(suspension));
+
+    const secondRun: number[] = [];
+    const second = makeEngineWithRecorder(forLoopGraph, (i) =>
+      secondRun.push(i)
+    );
+    second.engine.unsuspend(persisted, undefined);
+    await second.engine.executeAllSync();
+
+    expect(secondRun).toEqual([3, 4, COMPLETED]);
+  });
+});
+
+describe('core flow/sequence across suspension', () => {
+  it('fires only the remaining outputs instead of restarting', async () => {
+    const firstRun: number[] = [];
+    const first = makeEngineWithRecorder(sequenceGraph, (i) =>
+      firstRun.push(i)
+    );
+
+    first.start();
+    // budget: sequence trigger + first output's recorder
+    await first.engine.executeAllSync(100, 2);
+    expect(firstRun).toEqual([1]);
+
+    const suspension = first.engine.suspend();
+    expect(suspension.nodes['1']).toEqual({ nextIndex: 1 });
+
+    const secondRun: number[] = [];
+    const second = makeEngineWithRecorder(sequenceGraph, (i) =>
+      secondRun.push(i)
+    );
+    second.engine.unsuspend(JSON.parse(JSON.stringify(suspension)), undefined);
+    await second.engine.executeAllSync();
+
+    expect(secondRun).toEqual([2, 3]);
+  });
+});

package/tests/fixtures/testNodes.ts

@@ -0,0 +1,222 @@
+import {
+  AsyncNode,
+  FlowNode,
+  NodeDescription,
+  Socket,
+  type Engine,
+  type Fiber,
+  type IGraph,
+  type NodeConfiguration
+} from '@kiberon-labs/behave-graph';
+import type { SuspendableEngine } from '../../src/engine';
+import type { IAsyncSuspendable, ISuspendable } from '../../src/types';
+
+export type SuspendedLoopState = {
+  nextIndex: number | null;
+};
+
+/**
+ * A for-loop flow node that can survive a suspension round-trip.
+ *
+ * Unlike the core `flow/forLoop` (which keeps its cursor in closures on the
+ * fiber's listener stack and therefore restarts when rehydrated), this node
+ * tracks the next iteration index on the instance. `suspend()` captures it and
+ * `hydrate()` restores it, so a re-trigger after unsuspension continues from
+ * where the loop left off instead of `startIndex`.
+ */
+export class SuspendableForLoop
+  extends FlowNode
+  implements ISuspendable<SuspendedLoopState>
+{
+  public static Description = new NodeDescription(
+    'flow/suspendableForLoop',
+    'Flow',
+    'Suspendable For Loop',
+    (description, graph, config, id) =>
+      new SuspendableForLoop(description, graph, config, id)
+  );
+
+  private nextIndex: number | null = null;
+
+  constructor(
+    description: NodeDescription,
+    graph: IGraph,
+    config: NodeConfiguration,
+    id: string
+  ) {
+    super(
+      description,
+      graph,
+      [
+        new Socket('flow', 'flow'),
+        new Socket('integer', 'startIndex'),
+        new Socket('integer', 'endIndex')
+      ],
+      [
+        new Socket('flow', 'loopBody'),
+        new Socket('integer', 'index'),
+        new Socket('flow', 'completed')
+      ],
+      config,
+      id
+    );
+  }
+
+  suspend(): SuspendedLoopState {
+    return { nextIndex: this.nextIndex };
+  }
+
+  hydrate(data: SuspendedLoopState): void {
+    this.nextIndex = data.nextIndex;
+  }
+
+  override triggered(fiber: Fiber, _triggeringSocketName: string) {
+    const endIndex = Number(this.readInput('endIndex'));
+
+    // fresh run starts at startIndex; a hydrated run resumes mid-loop
+    if (this.nextIndex === null) {
+      this.nextIndex = Number(this.readInput('startIndex'));
+    }
+
+    const iterate = () => {
+      if (this.nextIndex !== null && this.nextIndex < endIndex) {
+        this.writeOutput('index', BigInt(this.nextIndex));
+        this.nextIndex++;
+        fiber.commit(this, 'loopBody', () => {
+          iterate();
+        });
+      } else {
+        this.nextIndex = null;
+        fiber.commit(this, 'completed');
+      }
+    };
+    iterate();
+  }
+}
+
+export type SuspendedWaitState = {
+  waiting: boolean;
+};
+
+/**
+ * An async node that parks the fiber on a pending promise until externally
+ * signalled — the asynchronous counterpart to a flow node. Unlike flow nodes
+ * (which resume by re-triggering with restored state), an async node is
+ * resumed through `fiber.continue()` -> `unsuspend(continuanceData)`, which
+ * delivers the awaited data and commits the downstream flow.
+ *
+ * After being signalled once (via unsuspension), subsequent triggers pass
+ * straight through so resumed graphs can run to completion.
+ */
+export class WaitForSignal
+  extends AsyncNode
+  implements IAsyncSuspendable<unknown, SuspendedWaitState>
+{
+  public static Description = new NodeDescription(
+    'test/waitForSignal',
+    'Flow',
+    'Wait For Signal',
+    (description, graph, config, id) =>
+      new WaitForSignal(description, graph, config, id)
+  );
+
+  private waiting = false;
+  private signalled = false;
+  private notifyParked: (() => void) | undefined;
+
+  /** Resolves when the node has parked the fiber. */
+  public readonly parked: Promise<void>;
+
+  constructor(
+    description: NodeDescription,
+    graph: IGraph,
+    config: NodeConfiguration,
+    id: string
+  ) {
+    super(
+      description,
+      graph,
+      [new Socket('flow', 'flow')],
+      [new Socket('flow', 'flow'), new Socket('integer', 'value')],
+      config,
+      id
+    );
+    this.parked = new Promise((resolve) => {
+      this.notifyParked = resolve;
+    });
+  }
+
+  override triggered(
+    engine: Engine,
+    _triggeringSocketName: string,
+    finished: () => void
+  ) {
+    if (this.signalled) {
+      // already received its signal in a previous (suspended) life
+      this.writeOutput('value', BigInt(-1));
+      engine.commitToNewFiber(this, 'flow');
+      finished();
+      return;
+    }
+
+    this.waiting = true;
+    this.notifyParked?.();
+    // park the fiber until the engine is suspended (the promise never
+    // resolves; the suspension snapshot captures this node as the resume point)
+    return new Promise<void>(() => {});
+  }
+
+  suspend(): SuspendedWaitState {
+    return { waiting: this.waiting };
+  }
+
+  hydrate(data: SuspendedWaitState): void {
+    this.waiting = data.waiting;
+  }
+
+  async unsuspend(
+    data: unknown,
+    engine: SuspendableEngine,
+    _triggeringSocketName: string,
+    cb: () => void
+  ): Promise<void> {
+    this.waiting = false;
+    this.signalled = true;
+    this.writeOutput('value', BigInt(data as number));
+    engine.commitToNewFiber(this, 'flow');
+    cb();
+  }
+
+  override dispose() {
+    this.waiting = false;
+  }
+}
+
+/**
+ * A flow node that reports each visited iteration index to the test. The
+ * factory closes over the callback so each test gets an isolated recorder.
+ */
+export const makeRecorderDescription = (record: (index: number) => void) =>
+  new NodeDescription(
+    'test/recorder',
+    'Action',
+    'Recorder',
+    (description, graph, config, id) =>
+      new (class extends FlowNode {
+        constructor() {
+          super(
+            description,
+            graph,
+            [new Socket('flow', 'flow'), new Socket('integer', 'index')],
+            [new Socket('flow', 'flow')],
+            config,
+            id
+          );
+        }
+
+        override triggered(fiber: Fiber, _socketName: string) {
+          record(Number(this.readInput('index')));
+          fiber.commit(this, 'flow');
+        }
+      })()
+  );

package/tests/loopSuspension.test.ts

@@ -0,0 +1,137 @@
+import type { GraphJSON } from '@kiberon-labs/behave-graph';
+import { describe, expect, it } from 'vitest';
+import {
+  makeRecorderDescription,
+  SuspendableForLoop
+} from './fixtures/testNodes';
+import { makeTestEngine } from './testUtils';
+
+/** Marker the completion recorder reports when the loop's `completed` fires. */
+const COMPLETED = 999;
+
+/**
+ * onStart -> suspendable for-loop [0, 5).
+ * Loop body reports each index via `test/recorder`; the `completed` output
+ * reports the COMPLETED marker.
+ */
+const loopGraph: GraphJSON = {
+  variables: [],
+  customEvents: [],
+  nodes: [
+    {
+      type: 'lifecycle/onStart',
+      id: '0',
+      flows: { flow: { nodeId: '1', socket: 'flow' } }
+    },
+    {
+      type: 'flow/suspendableForLoop',
+      id: '1',
+      parameters: {
+        startIndex: { value: 0 },
+        endIndex: { value: 5 }
+      },
+      flows: {
+        loopBody: { nodeId: '2', socket: 'flow' },
+        completed: { nodeId: '3', socket: 'flow' }
+      }
+    },
+    {
+      type: 'test/recorder',
+      id: '2',
+      parameters: {
+        index: { link: { nodeId: '1', socket: 'index' } }
+      }
+    },
+    {
+      type: 'test/recorder',
+      id: '3',
+      parameters: {
+        index: { value: COMPLETED }
+      }
+    }
+  ]
+};
+
+const makeLoopEngine = (record: (index: number) => void) =>
+  makeTestEngine(loopGraph, {
+    [SuspendableForLoop.Description.typeName]: SuspendableForLoop.Description,
+    'test/recorder': makeRecorderDescription(record)
+  });
+
+describe('suspending mid-loop', () => {
+  it('runs the loop to completion when never suspended', async () => {
+    const recorded: number[] = [];
+    const { engine, start } = makeLoopEngine((i) => recorded.push(i));
+
+    start();
+    await engine.executeAllSync();
+
+    expect(recorded).toEqual([0, 1, 2, 3, 4, COMPLETED]);
+  });
+
+  it('completes only the remaining iterations after unsuspending, instead of restarting', async () => {
+    // --- first engine: run the loop partway, then suspend -----------------
+    const firstRun: number[] = [];
+    const { engine, start } = makeLoopEngine((i) => firstRun.push(i));
+
+    start();
+    // Step budget chosen to stop execution mid-loop: the loop trigger plus the
+    // first three body executions consume the budget, leaving iterations 3 and
+    // 4 (and the completion) outstanding on the fiber.
+    await engine.executeAllSync(100, 4);
+    expect(firstRun).toEqual([0, 1, 2]);
+    expect(engine.hasPending()).toBe(true);
+
+    const suspension = engine.suspend();
+
+    // the loop's cursor must be captured in the suspension...
+    expect(suspension.nodes['1']).toEqual({ nextIndex: 3 });
+    // ...along with the pending fiber pointing back at the loop node
+    expect(suspension.fiberQueue).toHaveLength(1);
+    expect(suspension.fiberQueue[0]!.queue).toEqual(['1']);
+
+    // serialization must survive a stringify round-trip (e.g. disk persistence)
+    const persisted = JSON.parse(JSON.stringify(suspension));
+
+    // --- second engine: rehydrate on a fresh graph and finish -------------
+    const secondRun: number[] = [];
+    const { engine: resumed } = makeLoopEngine((i) => secondRun.push(i));
+
+    resumed.unsuspend(persisted, undefined);
+    await resumed.executeAllSync();
+
+    // only the remaining iterations execute — the loop does not restart at 0
+    expect(secondRun).toEqual([3, 4, COMPLETED]);
+
+    // and across both runs every iteration executed exactly once
+    expect([...firstRun, ...secondRun.slice(0, -1)]).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  it('can immediately re-suspend after resuming', async () => {
+    const firstRun: number[] = [];
+    const first = makeLoopEngine((i) => firstRun.push(i));
+    first.start();
+    await first.engine.executeAllSync(100, 2);
+    expect(firstRun).toEqual([0]);
+
+    const suspension = first.engine.suspend();
+    expect(suspension.nodes['1']).toEqual({ nextIndex: 1 });
+
+    // resume, run one more iteration, suspend again
+    const secondRun: number[] = [];
+    const second = makeLoopEngine((i) => secondRun.push(i));
+    second.engine.unsuspend(suspension, undefined);
+    await second.engine.executeAllSync(100, 2);
+    expect(secondRun).toEqual([1]);
+
+    const secondSuspension = second.engine.suspend();
+    expect(secondSuspension.nodes['1']).toEqual({ nextIndex: 2 });
+
+    // final resume runs the loop to the end
+    const thirdRun: number[] = [];
+    const third = makeLoopEngine((i) => thirdRun.push(i));
+    third.engine.unsuspend(secondSuspension, undefined);
+    await third.engine.executeAllSync();
+    expect(thirdRun).toEqual([2, 3, 4, COMPLETED]);
+  });
+});

package/tests/nestedLoopSuspension.test.ts

@@ -0,0 +1,125 @@
+import type { GraphJSON } from '@kiberon-labs/behave-graph';
+import { describe, expect, it } from 'vitest';
+import { makeRecorderDescription } from './fixtures/testNodes';
+import { makeTestEngine } from './testUtils';
+
+const COMPLETED = 999;
+
+/**
+ * onStart -> outer forLoop [0,3) -> inner forLoop [0,3) -> recorder.
+ * The recorder receives outer*10 + inner via math nodes, so each recorded
+ * value identifies exactly which (outer, inner) iteration ran.
+ */
+const nestedLoopGraph: GraphJSON = {
+  variables: [],
+  customEvents: [],
+  nodes: [
+    {
+      type: 'lifecycle/onStart',
+      id: '0',
+      flows: { flow: { nodeId: 'outer', socket: 'flow' } }
+    },
+    {
+      type: 'flow/forLoop',
+      id: 'outer',
+      parameters: {
+        startIndex: { value: 0 },
+        endIndex: { value: 3 }
+      },
+      flows: {
+        loopBody: { nodeId: 'inner', socket: 'flow' },
+        completed: { nodeId: 'done', socket: 'flow' }
+      }
+    },
+    {
+      type: 'flow/forLoop',
+      id: 'inner',
+      parameters: {
+        startIndex: { value: 0 },
+        endIndex: { value: 3 }
+      },
+      flows: {
+        loopBody: { nodeId: 'rec', socket: 'flow' }
+      }
+    },
+    {
+      type: 'math/multiply/integer',
+      id: 'mul',
+      parameters: {
+        a: { link: { nodeId: 'outer', socket: 'index' } },
+        b: { value: 10 }
+      }
+    },
+    {
+      type: 'math/add/integer',
+      id: 'add',
+      parameters: {
+        a: { link: { nodeId: 'mul', socket: 'result' } },
+        b: { link: { nodeId: 'inner', socket: 'index' } }
+      }
+    },
+    {
+      type: 'test/recorder',
+      id: 'rec',
+      parameters: { index: { link: { nodeId: 'add', socket: 'result' } } }
+    },
+    {
+      type: 'test/recorder',
+      id: 'done',
+      parameters: { index: { value: COMPLETED } }
+    }
+  ]
+};
+
+const ALL_ITERATIONS = [0, 1, 2, 10, 11, 12, 20, 21, 22];
+
+const makeNestedEngine = (record: (index: number) => void) =>
+  makeTestEngine(nestedLoopGraph, {
+    'test/recorder': makeRecorderDescription(record)
+  });
+
+describe('nested loops across suspension', () => {
+  it('runs all inner iterations for every outer iteration when not suspended', async () => {
+    const recorded: number[] = [];
+    const { engine, start } = makeNestedEngine((i) => recorded.push(i));
+
+    start();
+    await engine.executeAllSync();
+
+    expect(recorded).toEqual([...ALL_ITERATIONS, COMPLETED]);
+  });
+
+  it('resumes mid-inner-loop: finishes the inner loop, then the remaining outer iterations', async () => {
+    const firstRun: number[] = [];
+    const first = makeNestedEngine((i) => firstRun.push(i));
+
+    first.start();
+    // run until partway through the inner loop of outer iteration 1
+    let steps = 0;
+    while (firstRun.length < 5 && first.engine.hasPending() && steps < 100) {
+      await first.engine.executeAllSync(100, 1);
+      steps++;
+    }
+    expect(firstRun).toEqual([0, 1, 2, 10, 11]);
+
+    const suspension = first.engine.suspend();
+
+    // both cursors captured independently: outer is mid-iteration 1 (next: 2),
+    // inner has fired 10 and 11 (next: 2)
+    expect(suspension.nodes['outer']).toEqual({ nextIndex: 2 });
+    expect(suspension.nodes['inner']).toEqual({ nextIndex: 2 });
+
+    const persisted = JSON.parse(JSON.stringify(suspension));
+
+    const secondRun: number[] = [];
+    const second = makeNestedEngine((i) => secondRun.push(i));
+    second.engine.unsuspend(persisted, undefined);
+    await second.engine.executeAllSync();
+
+    // the inner loop finishes its remaining iteration (12) BEFORE the outer
+    // loop advances — and neither loop restarts
+    expect(secondRun).toEqual([12, 20, 21, 22, COMPLETED]);
+
+    expect([...firstRun, ...secondRun.slice(0, -1)]).toEqual(ALL_ITERATIONS);
+  });
+});

package/tests/nodes/suspender.ts

@@ -0,0 +1,31 @@
+import {
+  AsyncNode,
+  NodeDescription,
+  NodeDescription2,
+  Socket,
+  type IGraph
+} from '@kiberon-labs/behave-graph';
+import type { IAsyncSuspendable } from '~/types';
+
+export class Suspender extends AsyncNode implements IAsyncSuspendable {
+  public static Description = new NodeDescription2({
+    typeName: 'Suspender',
+    category: 'Testing',
+    factory: (description, graph) => new Suspender(description, graph)
+  });
+
+  constructor(description: NodeDescription, graph: IGraph) {
+    super(
+      description,
+      graph,
+      [new Socket('flow', 'flow')],
+      [new Socket('flow', 'flow')]
+    );
+  }
+
+  suspend() {
+    return {};
+  }
+  async unsuspend(): Promise<void> {}
+  hydrate(): void {}
+}

package/tests/testUtils.ts

@@ -0,0 +1,37 @@
+import {
+  ManualLifecycleEventEmitter,
+  readGraphFromJSON,
+  registerCoreProfile,
+  type GraphJSON,
+  type IRegistry
+} from '@kiberon-labs/behave-graph';
+import { SuspendableEngine } from '../src/engine';
+
+/**
+ * Builds an isolated engine over the given graph JSON. Each call produces a
+ * fresh registry, lifecycle emitter, graph and engine so that suspension
+ * round-trips can be tested across truly independent engine instances (as if
+ * resuming in a new process).
+ */
+export const makeTestEngine = (
+  graphJson: GraphJSON,
+  extraNodes: Record<string, unknown> = {}
+) => {
+  const lifecycle = new ManualLifecycleEventEmitter();
+  const registry: IRegistry = registerCoreProfile({
+    values: {},
+    nodes: {},
+    dependencies: {
+      ILifecycleEventEmitter: lifecycle
+    }
+  });
+  Object.assign(registry.nodes, extraNodes);
+
+  const graph = readGraphFromJSON({ graphJson, registry });
+  const engine = new SuspendableEngine(graph, registry);
+
+  /** Emits the lifecycle start event, queueing the onStart fiber. */
+  const start = () => lifecycle.startEvent.emit();
+
+  return { engine, graph, registry, lifecycle, start };
+};