@pikku/core 0.12.37 → 0.12.39

package/src/wirings/workflow/run-timeline.test.ts

@@ -0,0 +1,211 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  buildRunTimeline,
+  reconstructStateAt,
+  reconstructFinalState,
+} from './run-timeline.js'
+import type { StepState } from './workflow.types.js'
+
+type HistoryEntry = StepState & { stepName: string }
+
+const T = (ms: number) => new Date(1_700_000_000_000 + ms)
+
+/** A succeeded step attempt with the standard lifecycle timestamps. */
+const ok = (
+  stepName: string,
+  base: number,
+  opts: { from?: string; result?: unknown; attempt?: number } = {}
+): HistoryEntry =>
+  ({
+    stepId: `${stepName}-${opts.attempt ?? 1}`,
+    stepName,
+    status: 'succeeded',
+    attemptCount: opts.attempt ?? 1,
+    fromStepName: opts.from,
+    result: opts.result,
+    createdAt: T(base),
+    runningAt: T(base + 1),
+    succeededAt: T(base + 2),
+    updatedAt: T(base + 2),
+  }) as HistoryEntry
+
+const failed = (
+  stepName: string,
+  base: number,
+  opts: { from?: string; attempt?: number; message?: string } = {}
+): HistoryEntry =>
+  ({
+    stepId: `${stepName}-${opts.attempt ?? 1}`,
+    stepName,
+    status: 'failed',
+    attemptCount: opts.attempt ?? 1,
+    fromStepName: opts.from,
+    error: { message: opts.message ?? 'boom' },
+    createdAt: T(base),
+    runningAt: T(base + 1),
+    failedAt: T(base + 2),
+    updatedAt: T(base + 2),
+  }) as HistoryEntry
+
+describe('buildRunTimeline', () => {
+  test('explodes each attempt into ordered lifecycle events', () => {
+    const tl = buildRunTimeline([ok('begin', 0, { result: { n: 1 } })])
+    assert.deepEqual(
+      tl.map((e) => e.type),
+      ['pending', 'running', 'succeeded']
+    )
+    // seq is monotonic from 0
+    assert.deepEqual(
+      tl.map((e) => e.seq),
+      [0, 1, 2]
+    )
+    // result rides only on the succeeded event
+    assert.deepEqual(tl[2]!.result, { n: 1 })
+    assert.equal(tl[0]!.result, undefined)
+  })
+
+  test('orders across steps by timestamp, lifecycle, then history index', () => {
+    // two steps; b created at the same instant begin succeeds
+    const tl = buildRunTimeline([
+      ok('begin', 0, { result: 1 }),
+      ok('next', 2, { from: 'begin', result: 2 }),
+    ])
+    // begin.pending(0) begin.running(1) begin.succeeded(2)==next.pending(2)
+    // → succeeded sorts before pending at the same instant (lifecycle 3 vs 0)?
+    // No: pending=0 < succeeded=3, so next.pending precedes begin.succeeded.
+    const at2 = tl.filter((e) => e.at.getTime() === T(2).getTime())
+    assert.deepEqual(
+      at2.map((e) => `${e.stepName}:${e.type}`),
+      ['next:pending', 'begin:succeeded']
+    )
+  })
+
+  test('carries provenance on the created event only', () => {
+    const tl = buildRunTimeline([ok('next', 5, { from: 'begin' })])
+    const created = tl.find((e) => e.type === 'pending')!
+    assert.equal(created.fromStepName, 'begin')
+    assert.equal(
+      tl.find((e) => e.type === 'succeeded')!.fromStepName,
+      undefined
+    )
+  })
+
+  test('terminal event is driven by status, not lifecycle timestamps', () => {
+    // Kysely leaves succeededAt/runningAt null but the row's status + result
+    // are authoritative — the terminal event must still fire (off updatedAt).
+    const noStamps = {
+      stepId: 's-1',
+      stepName: 'begin',
+      status: 'succeeded',
+      attemptCount: 1,
+      result: { ok: 1 },
+      createdAt: T(0),
+      updatedAt: T(5),
+    } as HistoryEntry
+    const tl = buildRunTimeline([noStamps])
+    assert.deepEqual(
+      tl.map((e) => e.type),
+      ['pending', 'succeeded']
+    )
+    const succeeded = tl.find((e) => e.type === 'succeeded')!
+    assert.equal(succeeded.at.getTime(), T(5).getTime(), 'falls back to updatedAt')
+    assert.deepEqual(succeeded.result, { ok: 1 })
+    assert.deepEqual(reconstructFinalState(tl).results, { begin: { ok: 1 } })
+  })
+})
+
+describe('reconstructStateAt', () => {
+  // begin → next → finish, each succeeding in order
+  const history: HistoryEntry[] = [
+    ok('begin', 0, { result: { step: 'begin' } }),
+    ok('next', 10, { from: 'begin', result: { step: 'next' } }),
+    ok('finish', 20, { from: 'next', result: { step: 'finish' } }),
+  ]
+  const tl = buildRunTimeline(history)
+
+  test('a point before the first event is the empty initial state', () => {
+    const s = reconstructStateAt(tl, -1)
+    assert.equal(s.seq, -1)
+    assert.deepEqual(s.steps, [])
+    assert.deepEqual(s.results, {})
+    assert.equal(s.phase, 'pending')
+  })
+
+  test('mid-run by seq: only steps up to that event exist', () => {
+    // fold through begin.succeeded (seq 2)
+    const s = reconstructStateAt(tl, 2)
+    assert.deepEqual(s.path, ['begin'])
+    assert.equal(s.steps[0]!.status, 'succeeded')
+    assert.deepEqual(s.results, { begin: { step: 'begin' } })
+    // next hasn't been created yet at this point
+    assert.equal(s.phase, 'idle')
+  })
+
+  test('mid-run captures an in-flight step as running', () => {
+    // begin done (0,1,2), next created+running (3,4) but not yet succeeded
+    const s = reconstructStateAt(tl, 4)
+    assert.deepEqual(s.path, ['begin', 'next'])
+    assert.equal(s.steps[1]!.stepName, 'next')
+    assert.equal(s.steps[1]!.status, 'running')
+    assert.equal(s.steps[1]!.fromStepName, 'begin')
+    assert.equal(s.phase, 'running')
+    // next's result not yet available in the replay cache
+    assert.deepEqual(s.results, { begin: { step: 'begin' } })
+  })
+
+  test('time-travel by Date folds every event at or before the instant', () => {
+    const s = reconstructStateAt(tl, T(12))
+    // begin fully done (<=2), next created(10)+running(11) but succeeded at 12
+    assert.deepEqual(s.path, ['begin', 'next'])
+    assert.equal(s.steps[1]!.status, 'succeeded')
+    assert.deepEqual(s.results, {
+      begin: { step: 'begin' },
+      next: { step: 'next' },
+    })
+  })
+
+  test('final state has the full walked path and all results', () => {
+    const s = reconstructFinalState(tl)
+    assert.deepEqual(s.path, ['begin', 'next', 'finish'])
+    assert.deepEqual(s.results, {
+      begin: { step: 'begin' },
+      next: { step: 'next' },
+      finish: { step: 'finish' },
+    })
+    assert.equal(s.phase, 'idle')
+  })
+})
+
+describe('reconstructStateAt — retries', () => {
+  // attempt 1 fails, attempt 2 (created later) succeeds
+  const history: HistoryEntry[] = [
+    failed('flaky', 0, { message: 'first try' }),
+    ok('flaky', 10, { result: { ok: true }, attempt: 2 }),
+  ]
+  const tl = buildRunTimeline(history)
+
+  test('between attempts the step is failed', () => {
+    const s = reconstructStateAt(tl, T(2)) // through failedAt of attempt 1
+    assert.equal(s.steps[0]!.status, 'failed')
+    assert.equal(s.steps[0]!.error?.message, 'first try')
+    assert.equal(s.phase, 'failed')
+    assert.deepEqual(s.results, {})
+  })
+
+  test("the retry's created event reopens the step and clears the error", () => {
+    const s = reconstructStateAt(tl, T(10)) // attempt-2 pending
+    assert.equal(s.steps[0]!.status, 'pending')
+    assert.equal(s.steps[0]!.error, undefined)
+    assert.equal(s.steps[0]!.attemptCount, 2)
+    assert.equal(s.phase, 'running')
+  })
+
+  test('after the retry succeeds the result is available', () => {
+    const s = reconstructFinalState(tl)
+    assert.equal(s.steps[0]!.status, 'succeeded')
+    assert.deepEqual(s.results, { flaky: { ok: true } })
+    assert.equal(s.path.length, 1, 'a retried step is still one path entry')
+  })
+})

package/src/wirings/workflow/run-timeline.ts

@@ -0,0 +1,241 @@
+import type { SerializedError } from '../../types/core.types.js'
+import type { StepState, StepStatus } from './workflow.types.js'
+
+/**
+ * Time-travel over a workflow run.
+ *
+ * A run's durable history (`getRunHistory`) is one row per step *attempt*, each
+ * carrying lifecycle timestamps (created/scheduled/running/succeeded/failed).
+ * `buildRunTimeline` explodes those rows into a flat, chronologically-ordered
+ * event stream, and `reconstructStateAt` folds the stream up to any point to
+ * recover what the run "knew" then — the same step cache a replay would hold:
+ * per-step status, accumulated results, and the walked path.
+ *
+ * These are pure functions over history — no IO — so they're trivially testable
+ * and transport-independent (the same fold works for Redis/Kysely/in-memory).
+ */
+
+/** A single observable transition of one step attempt. */
+export interface RunTimelineEvent {
+  /** Monotonic 0-based position in the timeline. */
+  seq: number
+  /** When it happened. */
+  at: Date
+  /** The step's new status at this event (matches StepStatus lifecycle). */
+  type: Extract<
+    StepStatus,
+    'pending' | 'scheduled' | 'running' | 'succeeded' | 'failed'
+  >
+  /** Physical step name (includes revisit ordinal, e.g. `attempt#2`). */
+  stepName: string
+  /** Which attempt this event belongs to (1-based). */
+  attemptCount: number
+  /** Predecessor that scheduled this step — only on the `pending` (created)
+   *  event; undefined for entry steps. Reconstructs the walked edge. */
+  fromStepName?: string
+  /** Result snapshot — only on `succeeded`. */
+  result?: unknown
+  /** Error snapshot — only on `failed`. */
+  error?: SerializedError
+}
+
+export type RunTimeline = RunTimelineEvent[]
+
+type HistoryEntry = StepState & { stepName: string }
+
+/** Lifecycle tiebreak for events that share a timestamp. */
+const LIFECYCLE_ORDER: Record<RunTimelineEvent['type'], number> = {
+  pending: 0,
+  scheduled: 1,
+  running: 2,
+  succeeded: 3,
+  failed: 3,
+}
+
+/**
+ * Build the ordered event stream for a run from its raw history.
+ *
+ * History is expected oldest-first but is sorted defensively by (timestamp,
+ * lifecycle, original index) so simultaneous timestamps stay deterministic.
+ */
+export function buildRunTimeline(history: HistoryEntry[]): RunTimeline {
+  const raw: Array<Omit<RunTimelineEvent, 'seq'> & { order: number }> = []
+
+  history.forEach((entry, order) => {
+    const base = {
+      stepName: entry.stepName,
+      attemptCount: entry.attemptCount,
+      order,
+    }
+    // The created event always exists; it carries provenance.
+    raw.push({
+      ...base,
+      at: entry.createdAt,
+      type: 'pending',
+      fromStepName: entry.fromStepName,
+    })
+    // Intermediate events are optional enrichment — emit only if the backend
+    // recorded their timestamp.
+    if (entry.scheduledAt) {
+      raw.push({ ...base, at: entry.scheduledAt, type: 'scheduled' })
+    }
+    if (entry.runningAt) {
+      raw.push({ ...base, at: entry.runningAt, type: 'running' })
+    }
+    // The terminal event is driven by the row's authoritative status (the
+    // lifecycle timestamps aren't populated by every backend — Kysely leaves
+    // them null), falling back to updatedAt when the specific stamp is absent.
+    if (entry.status === 'succeeded') {
+      raw.push({
+        ...base,
+        at: entry.succeededAt ?? entry.updatedAt,
+        type: 'succeeded',
+        result: entry.result,
+      })
+    } else if (entry.status === 'failed') {
+      raw.push({
+        ...base,
+        at: entry.failedAt ?? entry.updatedAt,
+        type: 'failed',
+        error: entry.error,
+      })
+    }
+  })
+
+  raw.sort((a, b) => {
+    const ta = a.at.getTime()
+    const tb = b.at.getTime()
+    if (ta !== tb) return ta - tb
+    const la = LIFECYCLE_ORDER[a.type]
+    const lb = LIFECYCLE_ORDER[b.type]
+    if (la !== lb) return la - lb
+    return a.order - b.order
+  })
+
+  return raw.map(({ order: _order, ...event }, seq) => ({ ...event, seq }))
+}
+
+/** A step's reconstructed state at a point in the timeline. */
+export interface ReconstructedStep {
+  stepName: string
+  status: StepStatus
+  attemptCount: number
+  fromStepName?: string
+  result?: unknown
+  error?: SerializedError
+}
+
+/** Coarse run phase derived purely from step states (not the run's output). */
+export type RunPhase = 'pending' | 'running' | 'failed' | 'idle'
+
+/** The whole run's reconstructed state at a point in the timeline. */
+export interface ReconstructedRunState {
+  /** seq of the last applied event, or -1 if the point precedes all events. */
+  seq: number
+  /** Wall-clock time of the last applied event. */
+  at?: Date
+  /** Per-step latest state, in first-seen (walked) order. */
+  steps: ReconstructedStep[]
+  /** Outputs available to downstream steps — the replay step cache at this
+   *  point (succeeded steps only). */
+  results: Record<string, unknown>
+  /** Step names in the order they were first created — the walked path. */
+  path: string[]
+  /** Derived phase: `running` if any step is in-flight, else `failed` if a step
+   *  is failed with no in-flight work, else `idle` (between transitions). */
+  phase: RunPhase
+}
+
+const IN_FLIGHT: ReadonlySet<StepStatus> = new Set([
+  'pending',
+  'scheduled',
+  'running',
+])
+
+/**
+ * Fold the timeline up to `at` and return the run's state at that point.
+ *
+ * `at` is either a seq index (inclusive — apply events `0..at`) or a `Date`
+ * (inclusive — apply every event at or before that instant). A point before the
+ * first event yields the empty initial state.
+ */
+export function reconstructStateAt(
+  timeline: RunTimeline,
+  at: number | Date
+): ReconstructedRunState {
+  const cutoff = (event: RunTimelineEvent): boolean =>
+    typeof at === 'number'
+      ? event.seq <= at
+      : event.at.getTime() <= at.getTime()
+
+  const steps = new Map<string, ReconstructedStep>()
+  const path: string[] = []
+  let lastSeq = -1
+  let lastAt: Date | undefined
+
+  for (const event of timeline) {
+    if (!cutoff(event)) break
+    lastSeq = event.seq
+    lastAt = event.at
+
+    let step = steps.get(event.stepName)
+    if (!step) {
+      step = {
+        stepName: event.stepName,
+        status: event.type,
+        attemptCount: event.attemptCount,
+        fromStepName: event.fromStepName,
+      }
+      steps.set(event.stepName, step)
+      path.push(event.stepName)
+    }
+    step.status = event.type
+    step.attemptCount = event.attemptCount
+    if (event.fromStepName !== undefined) {
+      step.fromStepName = event.fromStepName
+    }
+    // A retry's created event reopens the step — drop the prior outcome.
+    if (event.type === 'pending') {
+      delete step.result
+      delete step.error
+    }
+    if (event.type === 'succeeded') {
+      step.result = event.result
+      step.error = undefined
+    }
+    if (event.type === 'failed') {
+      step.error = event.error
+    }
+  }
+
+  const orderedSteps = path.map((name) => steps.get(name)!)
+  const results: Record<string, unknown> = {}
+  for (const step of orderedSteps) {
+    if (step.status === 'succeeded') {
+      results[step.stepName] = step.result
+    }
+  }
+
+  return {
+    seq: lastSeq,
+    at: lastAt,
+    steps: orderedSteps,
+    results,
+    path,
+    phase: derivePhase(orderedSteps),
+  }
+}
+
+/** Reconstruct the final state (fold the whole timeline). */
+export function reconstructFinalState(
+  timeline: RunTimeline
+): ReconstructedRunState {
+  return reconstructStateAt(timeline, timeline.length - 1)
+}
+
+function derivePhase(steps: ReconstructedStep[]): RunPhase {
+  if (steps.length === 0) return 'pending'
+  if (steps.some((s) => IN_FLIGHT.has(s.status))) return 'running'
+  if (steps.some((s) => s.status === 'failed')) return 'failed'
+  return 'idle'
+}

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 {