@pikku/core 0.12.72 → 0.12.77

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

@@ -5,8 +5,6 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import { pikkuState } from '../../pikku-state.js'
 import { WorkflowDispatchException } from './pikku-workflow-service.js'
 
-// Register a `workflowQueued: true` 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)
@@ -31,18 +29,17 @@ describe('dispatch durability: a transient queue failure is recoverable', () =>
     } as any)
 
     const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('flow', {}, false, 'hash', { type: 'test' })
+    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,
@@ -50,14 +47,13 @@ describe('dispatch durability: a transient queue failure is recoverable', () =>
       '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')
+    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.
     await (ws as any).beginReplay(runId)
     queueUp = true
     await assert.rejects(
@@ -81,7 +77,6 @@ describe('orchestrateWorkflow treats a dispatch failure as non-terminal', () =>
       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
   }
@@ -90,7 +85,9 @@ describe('orchestrateWorkflow treats a dispatch failure as non-terminal', () =>
     const ws = makeService(() => {
       throw new WorkflowDispatchException('r', 's')
     })
-    const runId = await ws.createRun('flow', {}, false, 'hash', { type: 'test' })
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
 
     await assert.rejects(
       ws.orchestrateWorkflow(runId, {}),
@@ -108,7 +105,9 @@ describe('orchestrateWorkflow treats a dispatch failure as non-terminal', () =>
     const ws = makeService(() => {
       throw new Error('business logic blew up')
     })
-    const runId = await ws.createRun('flow', {}, false, 'hash', { type: 'test' })
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
 
     await assert.rejects(ws.orchestrateWorkflow(runId, {}))
     const run = await ws.getRun(runId)

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

@@ -6,10 +6,6 @@ import { pikkuState } from '../../pikku-state.js'
 
 const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
-/**
- * Captures what the workflow service hands the queue, so a test can tell
- * whether core serialised the payload on the way past.
- */
 function serviceWithCapturingQueue() {
   const added: Array<{ queueName: string; data: any }> = []
   pikkuState(null, 'package', 'singletonServices', {

package/src/wirings/workflow/workflow-inline-authority.test.ts

@@ -0,0 +1,169 @@
+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 type {
+  WorkflowPlannedStep,
+  WorkflowRun,
+  WorkflowRunWire,
+} from './workflow.types.js'
+
+const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+const installSingletons = () =>
+  pikkuState(null, 'package', 'singletonServices', {
+    queueService: { add: async () => {} },
+    logger: silentLogger,
+  } as any)
+
+class SharedStoreWorkflowService extends InMemoryWorkflowService {
+  constructor(private readonly runStore: Map<string, WorkflowRun>) {
+    super()
+  }
+
+  protected override async createRunImpl(
+    workflowName: string,
+    input: any,
+    inline: boolean,
+    graphHash: string,
+    wire: WorkflowRunWire,
+    options?: {
+      deterministic?: boolean
+      plannedSteps?: WorkflowPlannedStep[]
+    }
+  ): Promise<string> {
+    const runId = await super.createRunImpl(
+      workflowName,
+      input,
+      inline,
+      graphHash,
+      wire,
+      options
+    )
+    this.runStore.set(runId, (await super.getRun(runId))!)
+    return runId
+  }
+
+  override async getRun(id: string): Promise<WorkflowRun | null> {
+    return this.runStore.get(id) ?? null
+  }
+}
+
+describe('whether a run is inline is decided by the run record, not by the process', () => {
+  test('an instance that did not start the run still knows it is inline', async () => {
+    installSingletons()
+    const store = new Map<string, WorkflowRun>()
+    const starter = new SharedStoreWorkflowService(store) as any
+    const observer = new SharedStoreWorkflowService(store) as any
+
+    const runId = await starter.createRun('flow', {}, true, 'hash', {
+      type: 'test',
+    })
+
+    assert.equal(await starter.isInline(runId), true)
+    assert.equal(
+      await observer.isInline(runId),
+      true,
+      'a second instance dispatched a queued job for a run that is already executing in-process'
+    )
+  })
+
+  test('an instance that did not start the run still knows it is queued', async () => {
+    installSingletons()
+    const store = new Map<string, WorkflowRun>()
+    const starter = new SharedStoreWorkflowService(store) as any
+    const observer = new SharedStoreWorkflowService(store) as any
+
+    const runId = await starter.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+
+    assert.equal(await starter.isInline(runId), false)
+    assert.equal(await observer.isInline(runId), false)
+  })
+
+  test('asking whether an unknown run is inline creates no state', async () => {
+    installSingletons()
+    const store = new Map<string, WorkflowRun>()
+    const ws = new SharedStoreWorkflowService(store) as any
+
+    assert.equal(await ws.isInline('no-such-run'), false)
+    assert.equal(ws.runContexts.size, 0)
+  })
+})
+
+describe('a run that stops executing here leaves no per-run state behind', () => {
+  const service = () => {
+    installSingletons()
+    return new InMemoryWorkflowService() as any
+  }
+
+  test('an inline run releases its ordinals when it unregisters', async () => {
+    const ws = service()
+    const before = ws.runContexts.size
+    const runId = await ws.createRun('flow', {}, true, 'hash', { type: 'test' })
+
+    await ws.inlineStep(runId, 'a', async () => 1)
+    await ws.inlineStep(runId, 'a', async () => 2)
+    ws.unregisterInlineRun(runId)
+
+    assert.equal(
+      ws.runContexts.size,
+      before,
+      'the ordinals map outlived the run that owned it'
+    )
+  })
+
+  test('a completed run releases the ordinals a step left behind', async () => {
+    const ws = service()
+    const before = ws.runContexts.size
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+
+    await ws.inlineStep(runId, 'a', async () => 1)
+    await ws.updateRunStatus(runId, 'completed', 1)
+
+    assert.equal(
+      ws.runContexts.size,
+      before,
+      'a terminal run still held its replay state'
+    )
+  })
+
+  test('a failed run releases the ordinals a step left behind', async () => {
+    const ws = service()
+    const before = ws.runContexts.size
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+
+    await ws.inlineStep(runId, 'a', async () => 1)
+    await ws.updateRunStatus(runId, 'failed', undefined, { message: 'boom' })
+
+    assert.equal(ws.runContexts.size, before)
+  })
+
+  test('running a queued step releases its context when the step returns', async () => {
+    const ws = service()
+    const before = ws.runContexts.size
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'test',
+    })
+    await ws.insertStepState(runId, 'a', 'someRpc', {})
+
+    await ws.executeWorkflowStep(runId, 'a', 'someRpc', {}, {
+      rpcWithWire: async () => {
+        await ws.inlineStep(runId, 'nested', async () => 'ok')
+        return 'ok'
+      },
+    })
+
+    assert.equal(
+      ws.runContexts.size,
+      before,
+      'the step worker kept per-run state for a run it no longer executes'
+    )
+  })
+})

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

@@ -8,8 +8,6 @@ const UUID_RE =
 
 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),

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

@@ -1,7 +1,5 @@
 import { createHash } from 'node: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 =>
@@ -12,10 +10,6 @@ const formatUuid = (bytes: Buffer): string => {
   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
@@ -25,24 +19,10 @@ export const uuidv5 = (
     .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
+  bytes[6] = (bytes[6]! & 0x0f) | 0x50
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80
   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-mirror.test.ts

@@ -5,11 +5,6 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import { pikkuState } from '../../pikku-state.js'
 import type { WorkflowRunMirror } from './workflow.types.js'
 
-/**
- * Every method on `WorkflowRunMirror`. A mirror method that is added to the
- * interface but never wired into the service writes nothing at runtime, and
- * nothing else would catch that — so the list is spelled out here.
- */
 const MIRROR_METHODS = [
   'createRun',
   'updateRunStatus',
@@ -28,7 +23,6 @@ const MIRROR_METHODS = [
 
 type Call = { method: string; args: any[] }
 
-/** A mirror that records every call, and optionally throws on all of them. */
 const recordingMirror = (
   onCall?: (method: string) => void
 ): { mirror: WorkflowRunMirror; calls: Call[] } => {
@@ -52,7 +46,6 @@ const service = (mirror?: WorkflowRunMirror) => {
   return ws
 }
 
-/** Drive every write the service mirrors, in dependency order. */
 const driveEveryWrite = async (ws: any) => {
   const runId = await ws.createRun('flow', { a: 1 }, false, 'hash', {
     type: 'test',

package/src/wirings/workflow/workflow-on-error.test.ts

@@ -3,11 +3,6 @@ import assert from 'node:assert/strict'
 
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 
-/**
- * Drive the real failure branch: a step that is already terminally failed must
- * invoke its onError handler and still throw. Only the nested compensation
- * call is intercepted, so the branch under test is the production one.
- */
 class TestWorkflowService extends InMemoryWorkflowService {
   public compensations: Array<{ rpcName: string; data: any }> = []
   public dispatches = 0
@@ -44,10 +39,6 @@ class TestWorkflowService extends InMemoryWorkflowService {
   }
 }
 
-/**
- * Seed a step in a non-terminal state, as a replay would find one that is
- * waiting on the queue rather than one that has failed.
- */
 async function seedPendingStep(ws: TestWorkflowService, stepName: string) {
   const runId = await ws.createRun('wf', {}, true, 'hash', {
     type: 'inline',

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

@@ -1,11 +1,3 @@
-/**
- * Queue worker functions for workflow orchestration.
- *
- * These are registered as queue consumers by the codegen pipeline
- * (injected into queue meta when workflows exist). They provide
- * the runtime implementations that process queued workflow jobs.
- */
-
 import { getSingletonServices } from '../../pikku-state.js'
 import type { PikkuRPC } from '../rpc/rpc-types.js'
 
@@ -14,7 +6,6 @@ export interface WorkflowStepInput {
   stepName: string
   rpcName: string
   data: unknown
-  /** Predecessor step name (the walked transition); undefined for entry steps. */
   fromStepName?: string
 }
 
@@ -27,10 +18,6 @@ export interface PikkuWorkflowSleeperInput {
   stepId: string
 }
 
-/**
- * Step worker — executes individual workflow steps dispatched via queue.
- * The orchestrator queues steps here when they're async (not inline).
- */
 export async function pikkuWorkflowWorkerFunc(
   _services: Record<string, unknown>,
   { runId, stepName, rpcName, data }: WorkflowStepInput,
@@ -51,10 +38,6 @@ export async function pikkuWorkflowWorkerFunc(
   )
 }
 
-/**
- * Orchestrator — resumes workflow execution after an async step completes.
- * Called when a step worker finishes and the workflow needs to continue.
- */
 export async function pikkuWorkflowOrchestratorFunc(
   _services: Record<string, unknown>,
   { runId }: PikkuWorkflowOrchestratorInput,
@@ -69,10 +52,6 @@ export async function pikkuWorkflowOrchestratorFunc(
   await services.workflowService.orchestrateWorkflow(runId, rpc)
 }
 
-/**
- * Sleeper — wakes a workflow after a workflow.sleep() duration expires.
- * Triggered by a delayed queue message or scheduler callback.
- */
 export async function pikkuWorkflowSleeperFunc(
   _services: Record<string, unknown>,
   { runId, stepId }: PikkuWorkflowSleeperInput

package/src/wirings/workflow/workflow-replay-snapshot.test.ts

@@ -14,11 +14,6 @@ function inlineService() {
   return new InMemoryWorkflowService()
 }
 
-/**
- * Every per-step read the service issues. In a real backend each one is its own
- * round-trip, so a replay that walks N completed steps costs N of them — and
- * over the life of a run that is O(N^2).
- */
 function countStepReads(ws: any) {
   const counter = { reads: 0 }
   const original = ws.getStepState.bind(ws)
@@ -49,7 +44,9 @@ describe('replay reads the run steps once, not once per step', () => {
     await ws.beginReplay(runId)
     for (let i = 0; i < 8; i++) {
       await ws.inlineStep(runId, `step-${i}`, async () => {
-        throw new Error(`step-${i} re-ran instead of replaying its cached result`)
+        throw new Error(
+          `step-${i} re-ran instead of replaying its cached result`
+        )
       })
     }
     ws.endReplay(runId)
@@ -105,7 +102,11 @@ describe('replay reads the run steps once, not once per step', () => {
     const late = await ws.inlineStep(runId, 'late', async () => 'must not run')
     ws.endReplay(runId)
 
-    assert.equal(late, 'first', 'the second replay re-ran a step the first one completed')
+    assert.equal(
+      late,
+      'first',
+      'the second replay re-ran a step the first one completed'
+    )
   })
 
   test('outside a replay, steps are still read one at a time', async () => {

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

@@ -11,7 +11,6 @@ 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)
@@ -29,8 +28,6 @@ describe('resolveStepJobOptions — workflow owns retry policy', () => {
   })
 
   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 })
   })
 
@@ -89,11 +86,9 @@ describe('executeWorkflowStep surfaces a stable invocationId', () => {
     })
     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')

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

@@ -30,11 +30,6 @@ const trackDetaches = (ws: any): string[] => {
   return detached
 }
 
-/**
- * A long-lived process orchestrates many runs. Anything it keeps per run has to
- * be released when that run stops executing here, or the engine grows for the
- * life of the deployment.
- */
 describe('per-run state is released when the run stops executing here', () => {
   test('a finished replay leaves nothing behind', async () => {
     const ws = service()
@@ -67,23 +62,23 @@ describe('per-run state is released when the run stops executing here', () => {
     const runId = await newRun(ws)
 
     ws.registerInlineRun(runId)
-    assert.equal(ws.isInline(runId), true)
+    assert.equal(await ws.isInline(runId), true)
 
     ws.unregisterInlineRun(runId)
-    assert.equal(ws.isInline(runId), false)
+    assert.equal(await ws.isInline(runId), false)
     assert.equal(ws.runContexts.size, 0)
   })
 
-  test('a replay inside an inline run does not release the inline flag', async () => {
+  test('a replay inside an inline run does not change what the run is', async () => {
     const ws = service()
-    const runId = await newRun(ws)
+    const runId = await newRun(ws, true)
 
     ws.registerInlineRun(runId)
     await ws.beginReplay(runId)
     ws.endReplay(runId)
 
     assert.equal(
-      ws.isInline(runId),
+      await ws.isInline(runId),
       true,
       'ending a replay dropped state the run still needs'
     )

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

@@ -5,13 +5,8 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import { pikkuState } from '../../pikku-state.js'
 import type { WorkflowRun } from './workflow.types.js'
 
-/**
- * A workflow service whose run reads are counted and timestamped, and whose
- * run finishes only once it has been read `endAfter` times.
- */
 class PollProbe extends InMemoryWorkflowService {
   readonly reads: number[] = []
-  /** Every wait the loop asked for, in order — the schedule, not the clock. */
   readonly waits: number[] = []
   endAfter = 1
 

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

@@ -22,11 +22,23 @@ describe('same step name invoked multiple times in one run', () => {
     ws.registerInlineRun(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')
+    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')
+    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')
@@ -51,7 +63,10 @@ describe('same step name invoked multiple times in one run', () => {
     // 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')
+    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 () => {

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

@@ -4,15 +4,8 @@ import assert from 'node:assert/strict'
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 import { pikkuState } from '../../pikku-state.js'
 
-// A queued workflow step is executed with the bare job wire (payload is just
-// { runId }), so its wire has no `pikkuUserId`. Without threading it from the
-// persisted run wire, an authed step (`pikkuFunc`) sees no session and throws
-// "Authentication required". These tests pin that `invokeStepRpc` merges the
-// run wire's `pikkuUserId` into the step wire override so the session rehydrates.
-
 const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
-// rpcService stand-in whose only job is to capture the wire override it's handed.
 function capturingRpcService(): {
   service: { rpcWithWire: (n: string, d: any, w: any) => Promise<any> }
   wire: () => any