@pikku/core 0.12.107 → 0.12.111

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

@@ -1,94 +0,0 @@
-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.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'
-    )
-
-    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.registerInlineRun(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.registerInlineRun(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'.
-    await (ws as any).beginReplay(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-step-session.test.ts

@@ -1,87 +0,0 @@
-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'
-
-const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
-
-function capturingRpcService(): {
-  service: { rpcWithWire: (n: string, d: any, w: any) => Promise<any> }
-  wire: () => any
-} {
-  let captured: any
-  return {
-    service: {
-      rpcWithWire: async (_rpcName: string, _data: any, wire: any) => {
-        captured = wire
-        return { ok: true }
-      },
-    },
-    wire: () => captured,
-  }
-}
-
-describe('queued workflow steps carry the run wire pikkuUserId', () => {
-  test('invokeStepRpc merges run.wire.pikkuUserId into the step wire override', async () => {
-    pikkuState(null, 'package', 'singletonServices', {
-      logger: silentLogger,
-    } as any)
-
-    const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'queue',
-      pikkuUserId: 'user-abc',
-    })
-    await ws.insertStepState(runId, 'deploy', 'deployByStageKind', {})
-    const stepState = await ws.getStepState(runId, 'deploy')
-
-    const rpc = capturingRpcService()
-    await (ws as any).invokeStepRpc(
-      runId,
-      'deploy',
-      stepState,
-      'deployByStageKind',
-      {},
-      rpc.service
-    )
-
-    assert.equal(
-      rpc.wire().pikkuUserId,
-      'user-abc',
-      'the step wire override carries the run wire pikkuUserId so authed steps rehydrate'
-    )
-    assert.ok(
-      rpc.wire().workflowStep,
-      'workflowStep provenance is still present'
-    )
-  })
-
-  test('no pikkuUserId key is injected when the run wire has none', async () => {
-    pikkuState(null, 'package', 'singletonServices', {
-      logger: silentLogger,
-    } as any)
-
-    const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'test',
-    })
-    await ws.insertStepState(runId, 'noauth', 'someFn', {})
-    const stepState = await ws.getStepState(runId, 'noauth')
-
-    const rpc = capturingRpcService()
-    await (ws as any).invokeStepRpc(
-      runId,
-      'noauth',
-      stepState,
-      'someFn',
-      {},
-      rpc.service
-    )
-
-    assert.ok(
-      !('pikkuUserId' in rpc.wire()),
-      'no undefined pikkuUserId is added when the run wire lacks one'
-    )
-  })
-})

package/src/wirings/workflow/workflow-suspend.ts

@@ -1,61 +0,0 @@
-import { WorkflowSuspendedException } from './workflow-errors.js'
-import type { ApprovalStore } from './workflow-approval.js'
-import type { StepState } from './workflow.types.js'
-
-/** The durable step name a suspension point is recorded under. */
-export const suspendStepNameFor = (reason: string): string =>
-  `__workflow_suspend:${reason}`
-
-/** What the suspend gate needs from the workflow service. */
-export type SuspendStore = Pick<
-  ApprovalStore,
-  'getStepState' | 'insertStepState' | 'setStepRunning' | 'setStepResult'
->
-
-/**
- * Record a suspension point and unwind the run.
- *
- * A suspension that has already succeeded returns instead of throwing, so a
- * replay walks past a gate the run has already passed through.
- */
-export const recordSuspension = async (
-  store: SuspendStore,
-  runId: string,
-  reason: string,
-  stepName: string,
-  fromStepName: string | undefined
-): Promise<void> => {
-  const insert = () =>
-    store.insertStepState(
-      runId,
-      stepName,
-      'pikkuWorkflowSuspend',
-      { reason },
-      undefined,
-      fromStepName
-    )
-
-  let stepState: StepState
-  try {
-    stepState = await store.getStepState(runId, stepName)
-  } catch {
-    stepState = await insert()
-  }
-  if (!stepState.stepId) {
-    stepState = await insert()
-  }
-
-  if (stepState.status === 'succeeded') {
-    return
-  }
-
-  if (stepState.status === 'pending') {
-    await store.setStepRunning(stepState.stepId)
-  }
-
-  await store.setStepResult(stepState.stepId, {
-    reason,
-    suspendedAt: new Date().toISOString(),
-  })
-  throw new WorkflowSuspendedException(runId, reason)
-}

package/src/wirings/workflow/workflow-terminal-run-guard.test.ts

@@ -1,105 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
-import { pikkuState, resetPikkuState } from '../../pikku-state.js'
-
-const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
-
-/** Records every run lock taken, which is the whole point of the guard. */
-class LockSpyWorkflowService extends InMemoryWorkflowService {
-  public readonly locked: string[] = []
-
-  public override async withRunLock<T>(
-    id: string,
-    fn: () => Promise<T>
-  ): Promise<T> {
-    this.locked.push(id)
-    return super.withRunLock(id, fn)
-  }
-}
-
-/** A registered, fully described workflow, so nothing else can short-circuit. */
-const startRun = async (): Promise<{
-  service: LockSpyWorkflowService
-  runId: string
-  entered: () => boolean
-}> => {
-  resetPikkuState()
-  pikkuState(null, 'package', 'singletonServices', {
-    logger: silentLogger,
-    queueService: { add: async () => 'job-1' },
-  } as any)
-
-  let bodyEntered = false
-  const func = async () => {
-    bodyEntered = true
-  }
-  pikkuState(null, 'workflows', 'meta', {
-    flow: { name: 'flow', pikkuFuncId: 'flow', source: 'dsl' },
-  } as any)
-  pikkuState(null, 'workflows', 'registrations').set('flow', {
-    name: 'flow',
-    func,
-  } as any)
-  pikkuState(null, 'function', 'meta', {
-    flow: {
-      pikkuFuncId: 'flow',
-      inputSchemaName: null,
-      outputSchemaName: null,
-      sessionless: true,
-    },
-  } as any)
-  pikkuState(null, 'function', 'functions').set('flow', { func } as any)
-
-  const service = new LockSpyWorkflowService()
-  const runId = await service.createRun('flow', {}, false, '', { type: 'test' })
-  return { service, runId, entered: () => bodyEntered }
-}
-
-/**
- * The leak this guards, read straight off production: every granted advisory
- * lock held by an idle session mapped to a run that was already `failed`. The
- * orchestrator queue is at-least-once, so a message for a settled run is
- * routine — and answering it by taking the run lock and replaying the body is
- * how a run that can never move again ends up holding a lock and a pooled
- * connection while it waits on something that will never arrive.
- */
-describe('an orchestrator message for a run that already settled', () => {
-  for (const status of ['failed', 'completed', 'cancelled'] as const) {
-    test(`a ${status} run is answered without taking its lock`, async () => {
-      const { service, runId, entered } = await startRun()
-      await service.updateRunStatus(runId, status)
-
-      await service.runWorkflowJob(runId, {} as any)
-
-      assert.deepEqual(
-        service.locked,
-        [],
-        'the run lock was taken for a run that can never move again'
-      )
-      assert.equal(
-        entered(),
-        false,
-        'the workflow body was replayed after the run had settled'
-      )
-    })
-  }
-
-  /**
-   * Guards the tests above: they would pass just as well for a service that
-   * refused to orchestrate anything at all.
-   */
-  test('a suspended run is still orchestrated', async () => {
-    const { service, runId } = await startRun()
-    await service.updateRunStatus(runId, 'suspended')
-
-    await service.runWorkflowJob(runId, {} as any)
-
-    assert.deepEqual(
-      service.locked,
-      [runId],
-      'suspended ends a pass, not the run — it resumes when its signal arrives'
-    )
-  })
-})

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

@@ -1,268 +0,0 @@
-import type { CommonWireMeta } from '../../types/core.types.js'
-import type { SerializedError } from '../../errors/serialized-error.js'
-import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
-import type { GroupConcurrencyConfig } from '../queue/queue.types.js'
-
-export type { WorkflowService } from '../../services/workflow-service.js'
-
-export type {
-  WorkflowStepOptions,
-  WorkflowWireDoRPC,
-  WorkflowApprovalOptions,
-  ApprovalOutcome,
-  InputSource,
-  OutputBinding,
-  RpcStepMeta,
-  Condition,
-  BranchStepMeta,
-  ParallelGroupStepMeta,
-  FanoutStepMeta,
-  ReturnStepMeta,
-  InlineStepMeta,
-  SleepStepMeta,
-  CancelStepMeta,
-  SuspendStepMeta,
-  ApprovalStepMeta,
-  SetStepMeta,
-  SwitchCaseMeta,
-  SwitchStepMeta,
-  FilterStepMeta,
-  ArrayPredicateStepMeta,
-  WorkflowStepMeta,
-  WorkflowStepWire,
-  PikkuWorkflowWire,
-} from './dsl/workflow-dsl.types.js'
-
-import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
-
-export interface WorkflowRunWire {
-  type: string
-  id?: string
-  parentRunId?: string
-  parentStepId?: string
-  pikkuUserId?: string
-}
-
-export interface WorkflowServiceConfig {
-  retries: number
-  retryDelay: number
-  orchestratorQueueName: string
-  stepWorkerQueueName: string
-  sleeperRPCName: string
-}
-
-export interface WorkflowQueueOptions {
-  queueStrategy?: 'per-workflow' | 'shared-groups'
-  queueConcurrency?: number
-  queueGroupConcurrency?: number | GroupConcurrencyConfig
-}
-
-export interface WorkflowPlannedStep {
-  stepName: string
-  displayName?: string
-}
-
-export type WorkflowStatus =
-  'running' | 'suspended' | 'completed' | 'failed' | 'cancelled'
-
-export type WorkflowVersionStatus = 'draft' | 'active' | 'declined'
-
-export type StepStatus =
-  'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed' | 'suspended'
-
-export interface WorkflowRun {
-  id: string
-  workflow: string
-  status: WorkflowStatus
-  input: any
-  output?: any
-  error?: SerializedError
-  inline?: boolean
-  graphHash?: string
-  deterministic?: boolean
-  plannedSteps?: WorkflowPlannedStep[]
-  wire: WorkflowRunWire
-  createdAt: Date
-  updatedAt: Date
-}
-
-export interface StepState {
-  stepId: string
-  status: StepStatus
-  /**
-   * The function the workflow dispatched this step with, recorded so a worker
-   * can reject a queue message naming anything else. `null` is a step with no
-   * function of its own (inline work); `undefined` is a store that never
-   * recorded one, and cannot be compared against.
-   */
-  rpcName?: string | null
-  result?: any
-  error?: SerializedError
-  attemptCount: number
-  retries?: number
-  retryDelay?: string | number
-  fromStepName?: string
-  createdAt: Date
-  updatedAt: Date
-  childRunId?: string
-  runningAt?: Date
-  scheduledAt?: Date
-  succeededAt?: Date
-  failedAt?: Date
-}
-
-export interface WorkflowRunStatus {
-  id: string
-  status: WorkflowStatus
-  startedAt: Date
-  completedAt?: Date
-  deterministic?: boolean
-  plannedSteps?: WorkflowPlannedStep[]
-  steps: Array<{
-    name: string
-    status: StepStatus
-    duration?: number
-    attempts?: number
-  }>
-  output?: unknown
-  error?: { message: string }
-}
-
-export interface WorkflowRunService {
-  listRuns(options?: {
-    workflowName?: string
-    status?: string
-    limit?: number
-    offset?: number
-  }): Promise<WorkflowRun[]>
-  getRun(id: string): Promise<WorkflowRun | null>
-  getRunSteps(
-    runId: string
-  ): Promise<
-    Array<StepState & { stepName: string; rpcName?: string; data?: any }>
-  >
-  getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
-  getDistinctWorkflowNames(): Promise<string[]>
-  getWorkflowVersion(
-    name: string,
-    graphHash: string
-  ): Promise<{ graph: any; source: string } | null>
-  deleteRun(id: string): Promise<boolean>
-}
-
-export interface WorkflowRunMirror {
-  createRun(
-    runId: string,
-    workflowName: string,
-    input: any,
-    inline: boolean,
-    graphHash: string,
-    wire: WorkflowRunWire,
-    options?: {
-      deterministic?: boolean
-      plannedSteps?: WorkflowPlannedStep[]
-    }
-  ): Promise<void>
-
-  updateRunStatus(
-    id: string,
-    status: WorkflowStatus,
-    output?: any,
-    error?: SerializedError
-  ): Promise<void>
-
-  insertStepState(
-    runId: string,
-    step: StepState & { stepName: string; rpcName: string | null; data: any }
-  ): Promise<void>
-
-  setStepRunning(stepId: string): Promise<void>
-  setStepScheduled(stepId: string): Promise<void>
-  setStepResult(stepId: string, result: any): Promise<void>
-  setStepChildRunId(stepId: string, childRunId: string): Promise<void>
-  setStepError(stepId: string, error: SerializedError): Promise<void>
-
-  createRetryAttempt(
-    failedStepId: string,
-    newStep: StepState & { stepName: string }
-  ): Promise<void>
-
-  setBranchTaken(stepId: string, branchKey: string): Promise<void>
-
-  updateRunState(runId: string, name: string, value: unknown): Promise<void>
-
-  upsertWorkflowVersion(
-    name: string,
-    graphHash: string,
-    graph: any,
-    source: string,
-    status?: WorkflowVersionStatus
-  ): Promise<void>
-
-  updateWorkflowVersionStatus(
-    name: string,
-    graphHash: string,
-    status: WorkflowVersionStatus
-  ): Promise<void>
-}
-
-export type CoreWorkflow<
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> =
-    CorePikkuFunctionConfig<any, any, any>,
-> = {
-  name: string
-  func: PikkuFunctionConfig
-  middleware?: PikkuFunctionConfig['middleware']
-  tags?: string[]
-}
-
-export interface PikkuWorkflow {
-  start: <I>(input: I) => Promise<{ runId: string }>
-  getRun: (runId: string) => Promise<WorkflowRun>
-  cancelRun: (runId: string) => Promise<void>
-}
-
-export interface ContextVariable {
-  type: 'string' | 'number' | 'boolean' | 'object' | 'array'
-  default?: unknown
-  description?: string
-}
-
-export type WorkflowContext = Record<string, ContextVariable>
-
-export type WorkflowsMeta = Record<
-  string,
-  CommonWireMeta & {
-    name: string
-    steps: WorkflowStepMeta[]
-    context?: WorkflowContext
-    dsl?: boolean
-    expose?: boolean
-    scenario?: boolean
-    /**
-     * The flow asserts through an expectation helper — `expectService`,
-     * `expectError`, `expectEventually` — rather than a `then` step. Those are
-     * inline steps and carry no phase, so without this PKU680 reads a scenario
-     * whose only witness is a recorded service call as asserting nothing.
-     */
-    asserts?: boolean
-    skip?: string
-    actors?: string[]
-  }
->
-
-export interface WorkflowRuntimeMeta {
-  name: string
-  pikkuFuncId: string
-  source: 'dsl' | 'complex' | 'graph' | 'scenario'
-  description?: string
-  tags?: string[]
-  actors?: string[]
-  nodes?: Record<string, any>
-  entryNodeIds?: string[]
-  graphHash?: string
-  deterministic?: boolean
-  plannedSteps?: WorkflowPlannedStep[]
-}
-
-export type WorkflowsRuntimeMeta = Record<string, WorkflowRuntimeMeta>