@pikku/core 0.12.37 → 0.12.38

package/src/wirings/workflow/workflow-dispatch-durability.test.ts

@@ -0,0 +1,117 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState } from '../../pikku-state.js'
+import { WorkflowDispatchException } from './pikku-workflow-service.js'
+
+// Register an `inline: false` function so the workflow's `do()` routes the step
+// through the queue (dispatchStep) instead of running it inline.
+function registerDispatchedFn(rpcName: string): void {
+  const funcId = `fn:${rpcName}`
+  pikkuState(null, 'rpc', 'meta', { [rpcName]: funcId } as any)
+  pikkuState(null, 'function', 'meta', {
+    [funcId]: { inline: false },
+  } as any)
+}
+
+const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+describe('dispatch durability: a transient queue failure is recoverable', () => {
+  test('failed dispatch leaves the step PENDING and the run un-failed, then re-dispatches on replay', async () => {
+    registerDispatchedFn('doThing')
+    let queueUp = false
+    pikkuState(null, 'package', 'singletonServices', {
+      queueService: {
+        add: async () => {
+          if (!queueUp) throw new Error('pg-boss is down')
+        },
+      },
+      logger: silentLogger,
+    } as any)
+
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', { type: 'test' })
+    await ws.insertStepState(runId, 'thing', 'doThing', {})
+
+    // Queue is down → dispatch throws the TRANSIENT exception (not a step failure).
+    await assert.rejects(
+      (ws as any).rpcStep(runId, 'thing', 'doThing', {}, {}),
+      (err: any) => err instanceof WorkflowDispatchException,
+      'a queue outage surfaces as WorkflowDispatchException'
+    )
+
+    // The step must NOT be stranded in `scheduled` — otherwise replay would pause
+    // forever on a job that was never enqueued.
+    const afterFail = await ws.getStepState(runId, 'thing')
+    assert.equal(
+      afterFail.status,
+      'pending',
+      'step stays pending after a failed dispatch'
+    )
+
+    // The run itself must stay alive (not failed) — it is the snapshot we replay.
+    const runAfterFail = await ws.getRun(runId)
+    assert.notEqual(runAfterFail?.status, 'failed', 'run is not failed by a queue blip')
+
+    // Queue recovers → replaying the step now dispatches (pauses via async exception)
+    // and the step transitions to `scheduled`. A real replay runs through
+    // runWorkflowJob which resets the ordinal counter; simulate that so the
+    // second reach resolves to the same step key, not the next ordinal.
+    ;(ws as any).resetStepOrdinals(runId)
+    queueUp = true
+    await assert.rejects(
+      (ws as any).rpcStep(runId, 'thing', 'doThing', {}, {}),
+      (err: any) => err.name === 'WorkflowAsyncException',
+      'recovered dispatch pauses the workflow as normal'
+    )
+    const afterRecover = await ws.getStepState(runId, 'thing')
+    assert.equal(
+      afterRecover.status,
+      'scheduled',
+      'step is scheduled only after a successful dispatch'
+    )
+  })
+})
+
+describe('orchestrateWorkflow treats a dispatch failure as non-terminal', () => {
+  function makeService(throwIt: () => never) {
+    pikkuState(null, 'package', 'singletonServices', {
+      queueService: { add: async () => {} },
+      logger: silentLogger,
+    } as any)
+    const ws = new InMemoryWorkflowService()
+    // Override the replay to throw whatever the test wants.
+    ;(ws as any).runWorkflowJob = async () => throwIt()
+    return ws
+  }
+
+  test('WorkflowDispatchException → run NOT marked failed, error rethrown for queue retry', async () => {
+    const ws = makeService(() => {
+      throw new WorkflowDispatchException('r', 's')
+    })
+    const runId = await ws.createRun('flow', {}, false, 'hash', { type: 'test' })
+
+    await assert.rejects(
+      ws.orchestrateWorkflow(runId, {}),
+      (err: any) => err instanceof WorkflowDispatchException
+    )
+    const run = await ws.getRun(runId)
+    assert.notEqual(
+      run?.status,
+      'failed',
+      'a transient dispatch failure must leave the run resumable'
+    )
+  })
+
+  test('a genuine step error still fails the run (unchanged behavior)', async () => {
+    const ws = makeService(() => {
+      throw new Error('business logic blew up')
+    })
+    const runId = await ws.createRun('flow', {}, false, 'hash', { type: 'test' })
+
+    await assert.rejects(ws.orchestrateWorkflow(runId, {}))
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'failed', 'real errors still fail the run')
+  })
+})

package/src/wirings/workflow/workflow-invocation-id.test.ts

@@ -0,0 +1,53 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { uuidv5, deriveInvocationId } from './workflow-invocation-id.js'
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+describe('uuidv5', () => {
+  test('matches the canonical RFC 4122 v5 vector', () => {
+    // www.example.com in the DNS namespace → known fixed UUID. Proves the
+    // SHA-1 + version/variant bit-twiddling is a correct v5 implementation.
+    const DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
+    assert.equal(
+      uuidv5('www.example.com', DNS),
+      '2ed6657d-e927-568b-95e1-2665a8aea6a2'
+    )
+  })
+
+  test('is deterministic and sets version 5 + RFC variant bits', () => {
+    const a = uuidv5('hello')
+    const b = uuidv5('hello')
+    assert.equal(a, b, 'same input → same UUID')
+    assert.match(a, UUID_RE, 'version nibble is 5 and variant is 8/9/a/b')
+  })
+
+  test('different names produce different UUIDs', () => {
+    assert.notEqual(uuidv5('a'), uuidv5('b'))
+  })
+})
+
+describe('deriveInvocationId', () => {
+  test('is stable across calls for the same run + step (the dedupe key)', () => {
+    const id1 = deriveInvocationId('run-1', 'updateUser')
+    const id2 = deriveInvocationId('run-1', 'updateUser')
+    assert.equal(id1, id2)
+    assert.match(id1, UUID_RE)
+  })
+
+  test('differs per step name within a run', () => {
+    assert.notEqual(
+      deriveInvocationId('run-1', 'updateUser'),
+      deriveInvocationId('run-1', 'chargeCard')
+    )
+  })
+
+  test('differs per run for the same step name', () => {
+    assert.notEqual(
+      deriveInvocationId('run-1', 'updateUser'),
+      deriveInvocationId('run-2', 'updateUser')
+    )
+  })
+})

package/src/wirings/workflow/workflow-invocation-id.ts

@@ -0,0 +1,48 @@
+import { createHash } from 'crypto'
+
+// Fixed namespace for pikku workflow step invocation IDs. Frozen — changing it
+// would alter every derived invocationId and break dedupe across a deploy.
+const PIKKU_WORKFLOW_NAMESPACE = '70696b6b-7500-5770-9f6c-6f77000a0001'
+
+const parseUuid = (uuid: string): Buffer =>
+  Buffer.from(uuid.replace(/-/g, ''), 'hex')
+
+const formatUuid = (bytes: Buffer): string => {
+  const hex = bytes.toString('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+/**
+ * RFC 4122 v5 (SHA-1, name-based) UUID. Deterministic: the same name +
+ * namespace always yields the same UUID — no `uuid` dependency needed.
+ */
+export const uuidv5 = (
+  name: string,
+  namespace: string = PIKKU_WORKFLOW_NAMESPACE
+): string => {
+  const hash = createHash('sha1')
+    .update(parseUuid(namespace))
+    .update(name, 'utf8')
+    .digest()
+  const bytes = hash.subarray(0, 16)
+  bytes[6] = (bytes[6]! & 0x0f) | 0x50 // version 5
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80 // RFC 4122 variant
+  return formatUuid(bytes)
+}
+
+/**
+ * The stable identity of one step *invocation* within a run — the idempotency /
+ * dedupe key handed to a step. Unlike `stepId` (minted fresh per attempt), this
+ * stays identical across every retry of the same call, because it is derived
+ * purely from `runId` + `stepName`, both of which are stable across replays.
+ *
+ * Same inputs → same UUID, so a step can safely
+ * `INSERT … ON CONFLICT (invocation_id)` / pass it as a Stripe idempotency key,
+ * and a retry of a half-applied side effect is collapsed onto the first attempt.
+ *
+ * NOTE: calling the *same* `stepName` more than once in a run is not yet
+ * disambiguated here (the store still keys steps by `runId:stepName`); when
+ * per-invocation ordinals land, the ordinal becomes the third hash component.
+ */
+export const deriveInvocationId = (runId: string, stepName: string): string =>
+  uuidv5(`${runId}:${stepName}`)

package/src/wirings/workflow/workflow-queue-workers.ts

@@ -14,6 +14,8 @@ export interface WorkflowStepInput {
   stepName: string
   rpcName: string
   data: unknown
+  /** Predecessor step name (the walked transition); undefined for entry steps. */
+  fromStepName?: string
 }
 
 export interface PikkuWorkflowOrchestratorInput {

package/src/wirings/workflow/workflow-retry-policy.test.ts

@@ -0,0 +1,111 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState } from '../../pikku-state.js'
+import { DEFAULT_STEP_RETRIES } from './pikku-workflow-service.js'
+import type { PikkuWorkflowService } from './pikku-workflow-service.js'
+import { deriveInvocationId } from './workflow-invocation-id.js'
+import type { WorkflowStepOptions } from './workflow.types.js'
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+// Expose the protected retry-policy resolver for direct assertion.
+class TestWorkflowService extends InMemoryWorkflowService {
+  public resolve(options?: WorkflowStepOptions) {
+    return (this as PikkuWorkflowService as any).resolveStepJobOptions(options)
+  }
+}
+
+describe('resolveStepJobOptions — workflow owns retry policy', () => {
+  const ws = new TestWorkflowService()
+
+  test('unset retries → default + exponential backoff (rides out outages)', () => {
+    assert.deepEqual(ws.resolve(undefined), {
+      attempts: DEFAULT_STEP_RETRIES + 1,
+      backoff: 'exponential',
+    })
+  })
+
+  test('retries: 0 → attempts: 1 and NO backoff (the non-idempotent opt-out)', () => {
+    // The whole point: an explicit 0 must never inherit the queue default and
+    // re-run a step the workflow said to run exactly once.
+    assert.deepEqual(ws.resolve({ retries: 0 }), { attempts: 1 })
+  })
+
+  test('explicit retries always honored', () => {
+    assert.deepEqual(ws.resolve({ retries: 3 }), {
+      attempts: 4,
+      backoff: 'exponential',
+    })
+  })
+
+  test('numeric retryDelay → fixed backoff', () => {
+    assert.deepEqual(ws.resolve({ retries: 3, retryDelay: 250 }), {
+      attempts: 4,
+      backoff: { type: 'fixed', delay: 250 },
+    })
+  })
+
+  test("retryDelay: 'exponential' → exponential backoff", () => {
+    assert.deepEqual(ws.resolve({ retries: 2, retryDelay: 'exponential' }), {
+      attempts: 3,
+      backoff: 'exponential',
+    })
+  })
+})
+
+describe('executeWorkflowStep surfaces a stable invocationId', () => {
+  test('invocationId is stable across a retry; stepId is per-attempt', async () => {
+    const ws = new InMemoryWorkflowService()
+    pikkuState(null, 'package', 'singletonServices', {
+      queueService: { add: async () => {} },
+      logger: { error() {}, info() {}, warn() {}, debug() {} },
+    } as any)
+
+    const captured: Array<{
+      invocationId: string
+      stepId: string
+      attemptCount: number
+    }> = []
+    const rpc = {
+      rpcWithWire: async (_n: string, _d: any, opts: any) => {
+        captured.push(opts.workflowStep)
+        if (captured.length === 1) throw new Error('transient boom')
+        return { ok: true }
+      },
+    }
+
+    const runId = await ws.createRun('invflow', {}, false, 'hash', {
+      type: 'test',
+    })
+    await ws.insertStepState(runId, 'updateUser', 'doUpdateUser', {})
+
+    // First attempt fails (default retries not exhausted → throws, not failed-run).
+    await assert.rejects(
+      ws.executeWorkflowStep(runId, 'updateUser', 'doUpdateUser', {}, rpc)
+    )
+    // Retry attempt succeeds.
+    await ws.executeWorkflowStep(runId, 'updateUser', 'doUpdateUser', {}, rpc)
+
+    assert.equal(captured.length, 2, 'step ran twice')
+    assert.equal(
+      captured[0]!.invocationId,
+      captured[1]!.invocationId,
+      'invocationId is identical across retries — the dedupe key'
+    )
+    assert.equal(
+      captured[0]!.invocationId,
+      deriveInvocationId(runId, 'updateUser')
+    )
+    assert.match(captured[0]!.invocationId, UUID_RE)
+    assert.equal(captured[0]!.attemptCount, 1)
+    assert.equal(captured[1]!.attemptCount, 2)
+    assert.notEqual(
+      captured[0]!.stepId,
+      captured[1]!.stepId,
+      'stepId is minted per attempt — must NOT be used as the dedupe key'
+    )
+  })
+})

package/src/wirings/workflow/workflow-step-ordinal.test.ts

@@ -0,0 +1,79 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState } from '../../pikku-state.js'
+import { deriveInvocationId } from './workflow-invocation-id.js'
+
+const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+function inlineService() {
+  pikkuState(null, 'package', 'singletonServices', {
+    queueService: { add: async () => {} },
+    logger: silentLogger,
+  } as any)
+  return new InMemoryWorkflowService()
+}
+
+describe('same step name invoked multiple times in one run', () => {
+  test('each reach gets its own row + invocationId (no clobber)', async () => {
+    const ws = inlineService()
+    const runId = await ws.createRun('flow', {}, true, 'hash', { type: 'test' })
+    ;(ws as any).inlineRuns.add(runId)
+
+    // Two `do('process', fn)` reaches in the SAME replay (no reset between).
+    const r1 = await (ws as any).inlineStep(runId, 'process', async () => 'first')
+    const r2 = await (ws as any).inlineStep(runId, 'process', async () => 'second')
+
+    assert.equal(r1, 'first')
+    assert.equal(r2, 'second', 'second call must NOT return the first cached result')
+
+    // Distinct rows: 'process' (ordinal 0) and 'process#1'.
+    const s0 = await ws.getStepState(runId, 'process')
+    const s1 = await ws.getStepState(runId, 'process#1')
+    assert.notEqual(s0.stepId, s1.stepId, 'distinct step rows')
+    assert.equal(s0.result, 'first')
+    assert.equal(s1.result, 'second')
+
+    // Per-invocation dedupe keys differ (not per-name).
+    assert.notEqual(
+      deriveInvocationId(runId, 'process'),
+      deriveInvocationId(runId, 'process#1')
+    )
+  })
+
+  test('ordinal 0 is unchanged: a single call keeps the bare name + its old invocationId', async () => {
+    const ws = inlineService()
+    const runId = await ws.createRun('flow', {}, true, 'hash', { type: 'test' })
+    ;(ws as any).inlineRuns.add(runId)
+
+    await (ws as any).inlineStep(runId, 'solo', async () => 'x')
+    // Stored under the bare name, and the dedupe key matches the pre-ordinal hash.
+    const s = await ws.getStepState(runId, 'solo')
+    assert.equal(s.result, 'x')
+    await assert.rejects(ws.getStepState(runId, 'solo#1'), 'no synthetic row for a single call')
+  })
+
+  test('a fresh replay resets ordinals so the same call resolves to the same row', async () => {
+    const ws = inlineService()
+    const runId = await ws.createRun('flow', {}, true, 'hash', { type: 'test' })
+    ;(ws as any).inlineRuns.add(runId)
+
+    let runs = 0
+    const r1 = await (ws as any).inlineStep(runId, 'once', async () => {
+      runs++
+      return 'v'
+    })
+    // Next replay resets the counter; the same `do('once')` must hit the cached
+    // row, not mint 'once#1'.
+    ;(ws as any).resetStepOrdinals(runId)
+    const r2 = await (ws as any).inlineStep(runId, 'once', async () => {
+      runs++
+      return 'v2'
+    })
+
+    assert.equal(r1, 'v')
+    assert.equal(r2, 'v', 'replay returns the cached result of the same step')
+    assert.equal(runs, 1, 'step body ran exactly once across replays')
+  })
+})

package/src/wirings/workflow/workflow.types.ts

@@ -134,6 +134,9 @@ export interface StepState {
   retries?: number
   /** Delay between retries */
   retryDelay?: string | number
+  /** Step name of the predecessor that scheduled this step (the transition/edge
+   *  walked to reach it); undefined for entry steps. Reconstructs the path. */
+  fromStepName?: string
   /** Creation timestamp */
   createdAt: Date
   /** Last update timestamp */
@@ -360,6 +363,8 @@ export type WorkflowStepInput = {
   stepName: string
   rpcName: string
   data: any
+  /** Predecessor step name (the walked transition); undefined for entry steps. */
+  fromStepName?: string
 }
 
 export type WorkflowOrchestratorInput = {