ai-workflows 2.1.1 → 2.3.0

package/test/durable-execution-in-process.test.ts

@@ -0,0 +1,286 @@
+/**
+ * Tests for the in-process production DurableExecutionAdapter
+ * (`createInProcessDurableExecution`). Covers two modes:
+ *
+ *   1. Standalone — no runtime supplied. Behaves like the in-memory stub for
+ *      callers that want the port without WorkflowRuntime integration.
+ *
+ *   2. Wrapped — a {@link WorkflowRuntime} supplied at construction time.
+ *      Each run/step is reflected in the runtime's history, cascade context,
+ *      and (when wired) database.
+ *
+ * The existing `durable-execution.test.ts` exercises the in-memory stub's port
+ * semantics in detail; these tests focus on the integration surface unique to
+ * the in-process adapter.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  createInProcessDurableExecution,
+  DurableStepError,
+  WaitForEventTimeoutError,
+  type DurableExecutionAdapter,
+  type InProcessWorkflowContext,
+} from '../src/durable-execution.js'
+import { createWorkflowRuntime } from '../src/runtime.js'
+import type { ActionData, DatabaseContext } from '../src/types.js'
+
+describe('createInProcessDurableExecution — standalone (no runtime)', () => {
+  it('exposes the in-process kind discriminant', () => {
+    const dx = createInProcessDurableExecution()
+    expect(dx.kind).toBe('in-process')
+  })
+
+  it('satisfies the DurableExecutionAdapter port', () => {
+    const adapter: DurableExecutionAdapter = createInProcessDurableExecution()
+    expect(adapter.kind).toBe('in-process')
+  })
+
+  it('runs a workflow body and returns the result', async () => {
+    const dx = createInProcessDurableExecution()
+    const result = await dx.run<number, { x: number; y: number }>(
+      'sum',
+      async (ctx) => ctx.input.x + ctx.input.y,
+      { x: 7, y: 8 }
+    )
+    expect(result).toBe(15)
+  })
+
+  it('runtime field is undefined when no runtime is supplied', () => {
+    const dx = createInProcessDurableExecution()
+    expect(dx.runtime).toBeUndefined()
+  })
+
+  it('ctx.runtime is undefined inside a body when no runtime is supplied', async () => {
+    const dx = createInProcessDurableExecution()
+    let captured: InProcessWorkflowContext<undefined> | null = null
+    await dx.run(
+      'capture',
+      async (ctx) => {
+        captured = ctx
+      },
+      undefined
+    )
+    expect(captured).not.toBeNull()
+    expect(captured!.runtime).toBeUndefined()
+  })
+
+  it('memoizes step results within a run (delegates to inner mechanics)', async () => {
+    const dx = createInProcessDurableExecution()
+    const fn = vi.fn(async () => Math.random())
+    const result = await dx.run(
+      'memo',
+      async (ctx) => {
+        const a = await ctx.step('once', fn)
+        const b = await ctx.step('once', fn)
+        return [a, b]
+      },
+      undefined
+    )
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(result[0]).toBe(result[1])
+  })
+
+  it('retries failing steps and throws DurableStepError when exhausted', async () => {
+    const dx = createInProcessDurableExecution({ delay: async () => {} })
+    await expect(
+      dx.run(
+        'exhaust',
+        async (ctx) =>
+          ctx.step('boom', { retries: { limit: 2 } }, async () => {
+            throw new Error('persistent')
+          }),
+        undefined
+      )
+    ).rejects.toBeInstanceOf(DurableStepError)
+  })
+
+  it('sleep, sleepUntil, waitForEvent, emit are forwarded from the inner adapter', async () => {
+    const sleeps: number[] = []
+    const dx = createInProcessDurableExecution({
+      delay: async (ms) => {
+        sleeps.push(ms)
+      },
+    })
+    await dx.sleep('100ms')
+    await dx.sleepUntil(new Date(Date.now() + 50))
+    expect(sleeps[0]).toBe(100)
+    expect(sleeps.length).toBeGreaterThanOrEqual(1)
+
+    const promise = dx.waitForEvent<string>('go')
+    expect(dx.emit('go', 'value')).toBe(true)
+    await expect(promise).resolves.toBe('value')
+
+    await expect(dx.waitForEvent('never', 5)).rejects.toBeInstanceOf(WaitForEventTimeoutError)
+  })
+})
+
+describe('createInProcessDurableExecution — wrapped (runtime integration)', () => {
+  it('exposes the runtime through the adapter', () => {
+    const runtime = createWorkflowRuntime()
+    const dx = createInProcessDurableExecution({ runtime })
+    expect(dx.runtime).toBe(runtime)
+  })
+
+  it('exposes the runtime on the workflow context inside a run', async () => {
+    const runtime = createWorkflowRuntime()
+    const dx = createInProcessDurableExecution({ runtime })
+    let captured: InProcessWorkflowContext<undefined> | null = null
+    await dx.run(
+      'capture',
+      async (ctx) => {
+        captured = ctx
+      },
+      undefined
+    )
+    expect(captured!.runtime).toBe(runtime)
+  })
+
+  it('records run start/finish in runtime history', async () => {
+    const runtime = createWorkflowRuntime()
+    const dx = createInProcessDurableExecution({ runtime })
+    await dx.run('hello', async () => 'ok', undefined)
+    const names = runtime.state.history.map((entry) => entry.name)
+    expect(names).toContain('durable-run:start:hello')
+    expect(names).toContain('durable-run:finish:hello')
+  })
+
+  it('records run errors in runtime history when the body throws', async () => {
+    const runtime = createWorkflowRuntime()
+    const dx = createInProcessDurableExecution({ runtime })
+    await expect(
+      dx.run(
+        'fail',
+        async () => {
+          throw new Error('nope')
+        },
+        undefined
+      )
+    ).rejects.toThrow('nope')
+    const names = runtime.state.history.map((entry) => entry.name)
+    expect(names).toContain('durable-run:start:fail')
+    expect(names).toContain('durable-run:error:fail')
+  })
+
+  it('records cascade steps for each durable step', async () => {
+    const runtime = createWorkflowRuntime()
+    const dx = createInProcessDurableExecution({ runtime })
+    await dx.run(
+      'cascade',
+      async (ctx) => {
+        await ctx.step('step-a', async () => 'a')
+        await ctx.step('step-b', async () => 'b')
+      },
+      undefined
+    )
+    const stepNames = runtime.cascade.steps.map((s) => s.name)
+    expect(stepNames).toEqual(['step-a', 'step-b'])
+    expect(runtime.cascade.steps.every((s) => s.status === 'completed')).toBe(true)
+  })
+
+  it('marks cascade step as failed when step throws', async () => {
+    const runtime = createWorkflowRuntime()
+    const dx = createInProcessDurableExecution({ runtime, delay: async () => {} })
+    await expect(
+      dx.run(
+        'fail-step',
+        async (ctx) =>
+          ctx.step('boom', async () => {
+            throw new Error('kaboom')
+          }),
+        undefined
+      )
+    ).rejects.toBeInstanceOf(DurableStepError)
+    expect(runtime.cascade.steps).toHaveLength(1)
+    expect(runtime.cascade.steps[0]!.status).toBe('failed')
+    expect(runtime.cascade.steps[0]!.error).toBeInstanceOf(Error)
+  })
+
+  it('records step actions through runtime.$.db when configured', async () => {
+    const created: ActionData[] = []
+    const completed: Array<{ id: string; result: unknown }> = []
+    const db: DatabaseContext = {
+      recordEvent: async () => {},
+      createAction: async (action) => {
+        created.push(action)
+      },
+      completeAction: async (id, result) => {
+        completed.push({ id, result })
+      },
+      storeArtifact: async () => {},
+      getArtifact: async () => null,
+    }
+    const runtime = createWorkflowRuntime({ db })
+    const dx = createInProcessDurableExecution({ runtime })
+
+    await dx.run(
+      'with-db',
+      async (ctx) => {
+        await ctx.step('write', async () => 'ok')
+      },
+      undefined
+    )
+
+    expect(created).toHaveLength(1)
+    expect(created[0]).toMatchObject({
+      actor: 'workflow',
+      object: 'write',
+      action: 'step',
+      status: 'active',
+    })
+    expect(completed).toEqual([{ id: 'write', result: 'ok' }])
+  })
+
+  it('does not fail the step when db.createAction itself throws', async () => {
+    const db: DatabaseContext = {
+      recordEvent: async () => {},
+      createAction: async () => {
+        throw new Error('db down')
+      },
+      completeAction: async () => {},
+      storeArtifact: async () => {},
+      getArtifact: async () => null,
+    }
+    const runtime = createWorkflowRuntime({ db })
+    const dx = createInProcessDurableExecution({ runtime })
+
+    const result = await dx.run(
+      'tolerant',
+      async (ctx) => ctx.step('write', async () => 'still-ok'),
+      undefined
+    )
+    expect(result).toBe('still-ok')
+  })
+
+  it('integrates with $.send: durable workflow can dispatch to runtime handlers', async () => {
+    const runtime = createWorkflowRuntime()
+    const handler = vi.fn()
+    runtime.register('Plan', 'generated', handler)
+    const dx = createInProcessDurableExecution({ runtime })
+
+    await dx.run(
+      'cascade',
+      async (ctx) => {
+        const plan = await ctx.step('plan', async () => ({ id: 'p-1' }))
+        ctx.runtime!.$.send('Plan.generated', plan)
+      },
+      undefined
+    )
+
+    // Wait a tick for the async send to deliver.
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(handler).toHaveBeenCalledWith(expect.objectContaining({ id: 'p-1' }), runtime.$)
+  })
+
+  it('top-level step (outside a run) also records a cascade step', async () => {
+    const runtime = createWorkflowRuntime()
+    const dx = createInProcessDurableExecution({ runtime })
+    await dx.step('one-off', async () => 'done')
+    expect(runtime.cascade.steps).toHaveLength(1)
+    expect(runtime.cascade.steps[0]!.name).toBe('one-off')
+    expect(runtime.cascade.steps[0]!.status).toBe('completed')
+  })
+})

package/test/durable-execution.test.ts

@@ -0,0 +1,247 @@
+/**
+ * Tests for the DurableExecutionAdapter port and its in-memory stub.
+ *
+ * The in-memory stub is the only adapter shipped in this bead (Phase 0). The
+ * goal of these tests is twofold: (1) prove the port shape compiles and is
+ * exercisable end-to-end without leaning on a real backend; (2) document the
+ * port semantics callers can rely on across all adapters (run, step memo,
+ * retries, sleep, waitForEvent timeouts, schedule subscription).
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  createInMemoryDurableExecution,
+  DurableStepError,
+  WaitForEventTimeoutError,
+  type DurableExecutionAdapter,
+  type WorkflowContext,
+} from '../src/durable-execution.js'
+
+describe('DurableExecutionAdapter port', () => {
+  it('exposes the documented kind discriminant', () => {
+    const dx = createInMemoryDurableExecution()
+    expect(dx.kind).toBe('in-process')
+  })
+
+  it('runs a workflow body with the supplied input', async () => {
+    const dx = createInMemoryDurableExecution()
+    const result = await dx.run<number, { x: number; y: number }>(
+      'sum',
+      async (ctx) => ctx.input.x + ctx.input.y,
+      { x: 2, y: 3 }
+    )
+    expect(result).toBe(5)
+  })
+
+  it('passes a context with stable instanceId and name', async () => {
+    const dx = createInMemoryDurableExecution()
+    let captured: WorkflowContext<undefined> | null = null
+    await dx.run(
+      'named',
+      async (ctx) => {
+        captured = ctx
+      },
+      undefined
+    )
+    expect(captured).not.toBeNull()
+    expect(captured!.name).toBe('named')
+    expect(typeof captured!.instanceId).toBe('string')
+    expect(captured!.instanceId.length).toBeGreaterThan(0)
+  })
+
+  it('memoizes step results within a run', async () => {
+    const dx = createInMemoryDurableExecution()
+    const fn = vi.fn(async () => Math.random())
+    const result = await dx.run(
+      'memo',
+      async (ctx) => {
+        const a = await ctx.step('once', fn)
+        const b = await ctx.step('once', fn)
+        return [a, b]
+      },
+      undefined
+    )
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(result[0]).toBe(result[1])
+  })
+
+  it('retries failing steps according to config', async () => {
+    const dx = createInMemoryDurableExecution({ delay: async () => {} })
+    let attempts = 0
+    const result = await dx.run(
+      'retry',
+      async (ctx) => {
+        return ctx.step('flaky', { retries: { limit: 3, delay: 10 } }, async () => {
+          attempts++
+          if (attempts < 3) throw new Error('transient')
+          return 'ok'
+        })
+      },
+      undefined
+    )
+    expect(attempts).toBe(3)
+    expect(result).toBe('ok')
+  })
+
+  it('throws DurableStepError when retries are exhausted', async () => {
+    const dx = createInMemoryDurableExecution({ delay: async () => {} })
+    const cause = new Error('persistent')
+    await expect(
+      dx.run(
+        'exhaust',
+        async (ctx) => {
+          return ctx.step('always-fails', { retries: { limit: 2 } }, async () => {
+            throw cause
+          })
+        },
+        undefined
+      )
+    ).rejects.toMatchObject({
+      name: 'DurableStepError',
+      stepName: 'always-fails',
+      attempts: 2,
+      retryable: true,
+      cause,
+    })
+  })
+
+  it('exposes DurableStepError as an Error instance with cause', async () => {
+    const dx = createInMemoryDurableExecution({ delay: async () => {} })
+    let caught: unknown
+    try {
+      await dx.run(
+        'exhaust2',
+        async (ctx) =>
+          ctx.step('boom', async () => {
+            throw new Error('nope')
+          }),
+        undefined
+      )
+    } catch (err) {
+      caught = err
+    }
+    expect(caught).toBeInstanceOf(Error)
+    expect(caught).toBeInstanceOf(DurableStepError)
+  })
+
+  it('sleeps for the requested duration (string form)', async () => {
+    const sleeps: number[] = []
+    const dx = createInMemoryDurableExecution({
+      delay: async (ms) => {
+        sleeps.push(ms)
+      },
+    })
+    await dx.run(
+      'sleeper',
+      async (ctx) => {
+        await ctx.sleep('500ms')
+        await ctx.sleep(250)
+        await ctx.sleep('1 second')
+      },
+      undefined
+    )
+    expect(sleeps).toEqual([500, 250, 1000])
+  })
+
+  it('sleeps until a future date', async () => {
+    let nowVal = 1_000_000
+    const sleeps: number[] = []
+    const dx = createInMemoryDurableExecution({
+      now: () => nowVal,
+      delay: async (ms) => {
+        sleeps.push(ms)
+        nowVal += ms
+      },
+    })
+    await dx.run(
+      'until',
+      async (ctx) => {
+        await ctx.sleepUntil(new Date(nowVal + 750))
+      },
+      undefined
+    )
+    expect(sleeps).toEqual([750])
+  })
+
+  it('does not sleep when sleepUntil is in the past', async () => {
+    const sleeps: number[] = []
+    const dx = createInMemoryDurableExecution({
+      now: () => 5_000,
+      delay: async (ms) => {
+        sleeps.push(ms)
+      },
+    })
+    await dx.run(
+      'past',
+      async (ctx) => {
+        await ctx.sleepUntil(new Date(0))
+      },
+      undefined
+    )
+    expect(sleeps).toEqual([])
+  })
+
+  it('rejects unrecognised duration strings', async () => {
+    const dx = createInMemoryDurableExecution({ delay: async () => {} })
+    await expect(
+      dx.run('bad', async (ctx) => ctx.sleep('two fortnights'), undefined)
+    ).rejects.toThrow(/Unrecognised duration/)
+  })
+
+  it('waitForEvent resolves when emit is called with matching name', async () => {
+    const dx = createInMemoryDurableExecution()
+    const promise = dx.waitForEvent<number>('Order.placed')
+    expect(dx.emit('Order.placed', 42)).toBe(true)
+    await expect(promise).resolves.toBe(42)
+  })
+
+  it('waitForEvent times out with WaitForEventTimeoutError', async () => {
+    const dx = createInMemoryDurableExecution()
+    await expect(dx.waitForEvent('never', 10)).rejects.toBeInstanceOf(WaitForEventTimeoutError)
+  })
+
+  it('emit returns false when no waiter is pending', () => {
+    const dx = createInMemoryDurableExecution()
+    expect(dx.emit('nothing', null)).toBe(false)
+  })
+
+  it('waitForEvent inside a workflow run resolves via emit', async () => {
+    const dx = createInMemoryDurableExecution()
+    const completion = dx.run<string, undefined>(
+      'await-event',
+      async (ctx) => ctx.waitForEvent<string>('approved'),
+      undefined
+    )
+    // Allow the run to register its waiter before we emit.
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(dx.emit('approved', 'go')).toBe(true)
+    await expect(completion).resolves.toBe('go')
+  })
+
+  it('schedule returns a subscription with a stable id and unsubscribe', () => {
+    const dx = createInMemoryDurableExecution()
+    const sub = dx.schedule('midnight', '0 0 * * *', async () => undefined)
+    expect(typeof sub.id).toBe('string')
+    expect(sub.id.length).toBeGreaterThan(0)
+    sub.unsubscribe()
+    // Calling unsubscribe twice is a no-op, not an error.
+    sub.unsubscribe()
+  })
+
+  it('top-level step() executes outside a run', async () => {
+    const dx = createInMemoryDurableExecution()
+    const fn = vi.fn(async () => 'value')
+    const result = await dx.step('once', fn)
+    expect(result).toBe('value')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('satisfies the DurableExecutionAdapter port type', () => {
+    // Compile-time check: assigning the stub to the port type proves
+    // structural compatibility.
+    const adapter: DurableExecutionAdapter = createInMemoryDurableExecution()
+    expect(adapter.kind).toBe('in-process')
+  })
+})