@pikku/core 0.12.37 → 0.12.39

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 */
@@ -161,6 +164,8 @@ export interface WorkflowRunStatus {
     name: string
     status: StepStatus
     duration?: number
+    /** Number of attempts for this step (1 = first try; > 1 means it retried). */
+    attempts?: number
   }>
   output?: unknown
   error?: { message: string }
@@ -360,6 +365,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 = {