@pikku/core 0.12.106 → 0.12.111

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

@@ -1,290 +0,0 @@
-import { getDurationInMilliseconds } from '../../time-utils.js'
-import {
-  WorkflowApprovalResolvedError,
-  WorkflowSuspendedException,
-} from './workflow-errors.js'
-import type {
-  ApprovalOutcome,
-  StepState,
-  WorkflowApprovalOptions,
-} from './workflow.types.js'
-import type {
-  ApprovalDecider,
-  WorkflowApprovalPolicy,
-} from './dsl/workflow-dsl.types.js'
-import {
-  approvalPolicyRefusal,
-  WorkflowApprovalForbiddenError,
-} from './workflow-approval-policy.js'
-
-/** The durable step name an approval point is recorded under. */
-export const approvalStepNameFor = (reason: string): string =>
-  `__workflow_approval:${reason}`
-
-/**
- * The run-state key holding an approval's decision.
- *
- * Hex-encoded because the key is composed from a caller-supplied reason, and
- * run state is a flat record — an unescaped reason could collide with, or
- * shadow, another key.
- */
-export const approvalStateKey = (stepName: string): string => {
-  let hex = ''
-  for (const byte of new TextEncoder().encode(stepName)) {
-    hex += byte.toString(16).padStart(2, '0')
-  }
-  return `__approval_${hex}`
-}
-
-/**
- * An answer to an approval gate, as the audit trail sees it.
- *
- * `denied` covers both a submission refused at the door and a decision cleared
- * on replay — from the trail's point of view they are the same event, someone
- * tried to answer a gate they could not.
- */
-export type ApprovalAuditEvent = {
-  runId: string
-  reason: string
-  outcome: 'success' | 'denied'
-  decidedBy?: ApprovalDecider
-  refusal?: string
-}
-
-/** What the approval gate needs from the workflow service. */
-export type ApprovalStore = {
-  getStepState: (runId: string, stepName: string) => Promise<StepState>
-  insertStepState: (
-    runId: string,
-    stepName: string,
-    rpcName: string,
-    input: unknown,
-    output: undefined,
-    fromStepName?: string
-  ) => Promise<StepState>
-  setStepRunning: (stepId: string) => Promise<void>
-  setStepResult: (stepId: string, result: unknown) => Promise<void>
-  getRunState: (runId: string) => Promise<Record<string, unknown>>
-  updateRunState: (runId: string, key: string, value: unknown) => Promise<void>
-  resumeWorkflow: (runId: string) => Promise<void>
-  scheduleRunWake: (runId: string, delay: number) => Promise<void>
-  getRunOwner: (runId: string) => Promise<string | undefined>
-  auditApproval: (event: ApprovalAuditEvent) => Promise<void>
-}
-
-/** What run state holds for an approval point between suspension and replay. */
-type ApprovalRecord = {
-  decision?: unknown
-  decidedAt?: string
-  decidedBy?: ApprovalDecider
-  policy?: WorkflowApprovalPolicy
-  expiresAt?: string
-  error?: unknown
-}
-
-/**
- * Record a decision against an approval point and wake the run.
- *
- * A decision arriving for an already-settled approval is refused rather than
- * overwriting it: the run has moved on, and a second answer would be recorded
- * against a gate nobody is waiting at.
- *
- * The decider is recorded rather than judged here, for the same reason the
- * payload is: the gate's policy is a value on the workflow, and a decision can
- * legitimately arrive before the run has ever reached the gate. Where the run
- * has already published its policy, it is applied eagerly so a caller who
- * cannot answer is told so rather than left waiting.
- */
-export const recordApprovalDecision = async (
-  store: ApprovalStore,
-  runId: string,
-  reason: string,
-  decision: unknown,
-  decidedBy?: ApprovalDecider
-): Promise<void> => {
-  const stepName = approvalStepNameFor(reason)
-  const stateKey = approvalStateKey(stepName)
-
-  let resolved: StepState | undefined
-  try {
-    resolved = await store.getStepState(runId, stepName)
-  } catch {
-    // knowledge: decisions/security/workflow-approval-payloads-are-validated-on-replay-inside-the-workflow.md
-  }
-  if (resolved?.stepId && resolved.status === 'succeeded') {
-    const outcome = resolved.result as ApprovalOutcome<unknown> | undefined
-    throw new WorkflowApprovalResolvedError(
-      reason,
-      outcome?.status ?? 'decided'
-    )
-  }
-
-  const state = await store.getRunState(runId)
-  const record = (state[stateKey] ?? {}) as ApprovalRecord
-
-  if (record.policy) {
-    const refusal = approvalPolicyRefusal(
-      record.policy,
-      await store.getRunOwner(runId),
-      decidedBy
-    )
-    if (refusal) {
-      await store.auditApproval({
-        runId,
-        reason,
-        outcome: 'denied',
-        decidedBy,
-        refusal,
-      })
-      throw new WorkflowApprovalForbiddenError(reason, refusal)
-    }
-  }
-
-  await store.updateRunState(runId, stateKey, {
-    ...record,
-    decision,
-    decidedAt: new Date().toISOString(),
-    decidedBy,
-    error: undefined,
-  } satisfies ApprovalRecord)
-  await store.auditApproval({ runId, reason, outcome: 'success', decidedBy })
-  await store.resumeWorkflow(runId)
-}
-
-/**
- * Evaluate an approval gate on replay.
- *
- * The payload is validated here rather than where it was submitted, because the
- * schema is a value on the workflow and only the workflow has it. A payload
- * that fails validation is cleared and the run suspends again, so a bad
- * submission cannot settle the gate.
- *
- * The decider is judged here for the same reason, and for one more: a decision
- * can be recorded before the run has ever reached the gate, so submission time
- * is not a point at which the policy is reliably knowable. Judging on replay is
- * what makes the policy hold in every ordering.
- */
-export const evaluateApprovalStep = async (
-  store: ApprovalStore,
-  runId: string,
-  reason: string,
-  approvalStepName: string,
-  fromStepName: string | undefined,
-  options: WorkflowApprovalOptions
-): Promise<ApprovalOutcome<unknown>> => {
-  const insert = () =>
-    store.insertStepState(
-      runId,
-      approvalStepName,
-      'pikkuWorkflowApproval',
-      {
-        reason,
-        expiry: options.expiry,
-        approvers: options.approvers,
-        approverScope: options.approverScope,
-      },
-      undefined,
-      fromStepName
-    )
-
-  let stepState: StepState
-  try {
-    stepState = await store.getStepState(runId, approvalStepName)
-  } catch {
-    stepState = await insert()
-  }
-  if (!stepState.stepId) {
-    stepState = await insert()
-  }
-
-  if (stepState.status === 'succeeded') {
-    return stepState.result as ApprovalOutcome<unknown>
-  }
-
-  const stateKey = approvalStateKey(approvalStepName)
-  let record = ((await store.getRunState(runId))[stateKey] ??
-    {}) as ApprovalRecord
-
-  const policy: WorkflowApprovalPolicy = {
-    approvers: options.approvers,
-    approverScope: options.approverScope,
-  }
-
-  if (stepState.status === 'pending') {
-    await store.setStepRunning(stepState.stepId)
-    record = { ...record, policy }
-    if (options.expiry !== undefined && !record.expiresAt) {
-      const expiry = getDurationInMilliseconds(options.expiry)
-      record = {
-        ...record,
-        expiresAt: new Date(Date.now() + expiry).toISOString(),
-      }
-      await store.updateRunState(runId, stateKey, record)
-      await store.scheduleRunWake(runId, expiry)
-    } else {
-      await store.updateRunState(runId, stateKey, record)
-    }
-  }
-
-  if (record.decision !== undefined) {
-    const refusal = approvalPolicyRefusal(
-      policy,
-      await store.getRunOwner(runId),
-      record.decidedBy
-    )
-    if (refusal) {
-      await store.updateRunState(runId, stateKey, {
-        ...record,
-        decision: undefined,
-        decidedAt: undefined,
-        decidedBy: undefined,
-        error: [{ message: refusal }],
-      } satisfies ApprovalRecord)
-      await store.auditApproval({
-        runId,
-        reason,
-        outcome: 'denied',
-        decidedBy: record.decidedBy,
-        refusal,
-      })
-      throw new WorkflowSuspendedException(runId, reason)
-    }
-
-    const validation = await options.schema['~standard'].validate(
-      record.decision
-    )
-    if (validation.issues) {
-      await store.updateRunState(runId, stateKey, {
-        ...record,
-        decision: undefined,
-        decidedAt: undefined,
-        decidedBy: undefined,
-        error: validation.issues.map((issue) => ({
-          message: issue.message,
-          path: issue.path?.map((segment) =>
-            typeof segment === 'object' ? segment.key : segment
-          ),
-        })),
-      })
-      throw new WorkflowSuspendedException(runId, reason)
-    }
-    // Spread rather than assigned, so a gate answered without a session keeps
-    // the shape it had before there was anything to record.
-    const outcome: ApprovalOutcome<unknown> = {
-      status: 'decided',
-      data: validation.value,
-      ...(record.decidedBy ? { decidedBy: record.decidedBy } : {}),
-      ...(record.decidedAt ? { decidedAt: record.decidedAt } : {}),
-    }
-    await store.setStepResult(stepState.stepId, outcome)
-    return outcome
-  }
-
-  if (record.expiresAt && Date.now() >= Date.parse(record.expiresAt)) {
-    const outcome: ApprovalOutcome<unknown> = { status: 'expired' }
-    await store.setStepResult(stepState.stepId, outcome)
-    return outcome
-  }
-
-  throw new WorkflowSuspendedException(runId, reason)
-}

package/src/wirings/workflow/workflow-child-run-session.test.ts

@@ -1,168 +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() {} }
-
-const registerChildWorkflow = (name: string) => {
-  pikkuState(null, 'workflows', 'meta', {
-    [name]: { name, pikkuFuncId: name, source: 'dsl', graphHash: 'h' },
-  } as any)
-  pikkuState(null, 'workflows', 'registrations').set(name, {
-    name,
-    func: async () => undefined,
-  } as any)
-  pikkuState(null, 'function', 'meta', {
-    [name]: {
-      pikkuFuncId: name,
-      inputSchemaName: null,
-      outputSchemaName: null,
-      sessionless: true,
-    },
-  } as any)
-  pikkuState(null, 'function', 'functions').set(name, {
-    func: async () => undefined,
-  } as any)
-}
-
-/**
- * A step whose rpcName names a workflow starts that workflow as a child. The
- * child's wire is built by the parent, so whatever identifies the caller has to
- * be copied across explicitly — nothing else carries it.
- */
-describe('a child workflow inherits the parent run wire pikkuUserId', () => {
-  const startParentWithChildStep = async (pikkuUserId?: string) => {
-    resetPikkuState()
-    pikkuState(null, 'package', 'singletonServices', {
-      logger: silentLogger,
-    } as any)
-    registerChildWorkflow('childFlow')
-
-    const ws = new InMemoryWorkflowService()
-    const runId = await ws.createRun('parentFlow', {}, true, '', {
-      type: 'test',
-      ...(pikkuUserId ? { pikkuUserId } : {}),
-    })
-    ws.registerInlineRun(runId)
-    await ws.insertStepState(runId, 'callChild', 'childFlow', {})
-
-    await (ws as any).rpcStep(runId, 'callChild', 'childFlow', {}, {})
-    return ws
-  }
-
-  const childRunWire = async (ws: InMemoryWorkflowService) => {
-    const runs: any[] = []
-    for (const id of (ws as any).runs?.keys?.() ?? []) {
-      const run = await ws.getRun(id)
-      if (run?.workflow === 'childFlow') runs.push(run)
-    }
-    assert.equal(runs.length, 1, 'exactly one child run should have started')
-    return runs[0]!.wire
-  }
-
-  test('the child run wire carries the parent pikkuUserId', async () => {
-    const ws = await startParentWithChildStep('user-abc')
-
-    assert.equal(
-      (await childRunWire(ws)).pikkuUserId,
-      'user-abc',
-      'a child started from a step must inherit who the parent was running as'
-    )
-  })
-
-  test('no pikkuUserId is invented when the parent has none', async () => {
-    const ws = await startParentWithChildStep()
-
-    assert.equal((await childRunWire(ws)).pikkuUserId, undefined)
-  })
-
-  test('the child records its parent', async () => {
-    const ws = await startParentWithChildStep('user-abc')
-    const wire = await childRunWire(ws)
-
-    assert.equal(wire.type, 'workflow')
-    assert.equal(wire.id, 'childFlow')
-    assert.ok(wire.parentRunId, 'the child must name the run that started it')
-  })
-})
-
-/**
- * Queuing a child workflow is only worth anything if the parent comes back with
- * the child's output. The routing tests assert which way a step goes; this
- * asserts what the parent is left holding once the child it queued has ended.
- */
-describe('a queued child workflow hands its output back to the parent step', () => {
-  const CHILD_OUTPUT = { invoiceId: 'inv-42' }
-
-  const setup = async () => {
-    resetPikkuState()
-    pikkuState(null, 'package', 'singletonServices', {
-      logger: silentLogger,
-      queueService: { add: async () => {} },
-    } as any)
-    registerChildWorkflow('childFlow')
-    pikkuState(null, 'function', 'functions').set('childFlow', {
-      func: async () => CHILD_OUTPUT,
-    } as any)
-
-    const ws = new InMemoryWorkflowService()
-    const parentRunId = await ws.createRun('parentFlow', {}, false, '', {
-      type: 'test',
-    })
-    const step = await ws.insertStepState(
-      parentRunId,
-      'callChild',
-      'childFlow',
-      {}
-    )
-    const stepId = (step as any).stepId ?? (step as any).id
-    assert.ok(stepId, 'the parent step must have an id to hand back to')
-    return { ws, parentRunId, stepId }
-  }
-
-  const childRunIdOf = async (ws: InMemoryWorkflowService) => {
-    for (const id of (ws as any).runs?.keys?.() ?? []) {
-      const run = await ws.getRun(id)
-      if (run?.workflow === 'childFlow') return run.id
-    }
-    throw new Error('no child run was started')
-  }
-
-  test('the parent step carries the child output once the child completes', async () => {
-    const { ws, parentRunId, stepId } = await setup()
-
-    // The step worker that picked the queued job off runs this; it starts the
-    // child and unwinds the parent rather than waiting on it.
-    await (ws as any).executeWorkflowStepInner(
-      parentRunId,
-      'callChild',
-      'childFlow',
-      {},
-      {}
-    )
-
-    const childRunId = await childRunIdOf(ws)
-    const childRun = await ws.getRun(childRunId)
-    assert.equal(
-      childRun?.wire?.parentStepId,
-      stepId,
-      'the child must name the step it has to hand its output back to'
-    )
-
-    await ws.updateRunStatus(childRunId, 'completed', CHILD_OUTPUT)
-    await (ws as any).onChildWorkflowCompleted(
-      await ws.getRun(childRunId),
-      CHILD_OUTPUT
-    )
-
-    const steps = await ws.getRunSteps(parentRunId)
-    const callChild = steps.find((s: any) => s.stepName === 'callChild')
-    assert.deepEqual(
-      callChild?.result,
-      CHILD_OUTPUT,
-      'the parent step must end up holding what the child returned'
-    )
-  })
-})

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

@@ -1,66 +0,0 @@
-export const DEFAULT_STEP_RETRIES = 5
-
-/** Statuses from which a run never advances again on its own. */
-export const WORKFLOW_END_STATES: ReadonlySet<string> = new Set([
-  'completed',
-  'failed',
-  'cancelled',
-  'suspended',
-])
-
-/** Statuses a run cannot leave at all. */
-export const WORKFLOW_TERMINAL_STATES: ReadonlySet<string> = new Set([
-  'completed',
-  'failed',
-  'cancelled',
-])
-
-/**
- * True for a run that will never move again, whatever arrives for it.
- *
- * Worth checking before doing anything with an orchestrator message, because
- * such a message is routine rather than exceptional: the queue is
- * at-least-once, the relay re-dispatches on purpose, and a run can settle
- * while a message for it is still in flight. Replaying one is not free —
- * `runWorkflowJob` takes the run lock and re-enters the workflow body, and a
- * body re-entered after its run failed can park on a wait that nothing will
- * ever satisfy, holding the lock and the connection under it until something
- * external gives up. Every leaked advisory lock seen in production traced back
- * to that: a granted lock, an idle session, and a run already `failed`.
- *
- * Note `suspended` is deliberately absent. It ends a run's *current* pass but
- * not the run, which resumes when its approval or signal arrives.
- */
-export const isRunSettled = (status: string): boolean =>
-  WORKFLOW_TERMINAL_STATES.has(status)
-
-export const WORKFLOW_POLL_MIN_MS = 10
-
-export const WORKFLOW_POLL_FACTOR = 1.6
-
-export const WORKFLOW_CHILD_POLL_MAX_MS = 500
-
-/** Idle window before a `running` run with nothing in flight is treated as stalled. */
-export const DEFAULT_STALLED_RUN_MS = 5 * 60_000
-
-/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
-export const DEFAULT_STALLED_RUN_LIMIT = 100
-
-/**
- * How long a step may sit `pending` before the relay assumes its dispatch was
- * lost. This is a bet that no healthy queue takes this long to move a job from
- * `pending` to `running`; set it above the observed p99 of that latency.
- */
-export const DEFAULT_UNDISPATCHED_STEP_MS = 30_000
-
-/** Steps re-driven per `relayUndispatchedSteps` call, so one tick is bounded. */
-export const DEFAULT_UNDISPATCHED_STEP_LIMIT = 100
-
-/** First wait before a step already re-dispatched once is re-dispatched again. */
-export const REDISPATCH_BACKOFF_MS = 30_000
-
-/** Ceiling on the doubling backoff, so a permanently stuck step still gets swept. */
-export const REDISPATCH_BACKOFF_MAX_MS = 10 * 60_000
-
-/** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
-export const REDISPATCH_BACKOFF_MAX_ENTRIES = 10_000

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

@@ -1,116 +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 { WorkflowDispatchException } from './workflow-errors.js'
-
-function registerDispatchedFn(rpcName: string): void {
-  const funcId = `fn:${rpcName}`
-  pikkuState(null, 'rpc', 'meta', { [rpcName]: funcId } as any)
-  pikkuState(null, 'function', 'meta', {
-    [funcId]: { workflowQueued: true },
-  } 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', {})
-
-    await assert.rejects(
-      (ws as any).rpcStep(runId, 'thing', 'doThing', {}, {}),
-      (err: any) => err instanceof WorkflowDispatchException,
-      'a queue outage surfaces as WorkflowDispatchException'
-    )
-
-    const afterFail = await ws.getStepState(runId, 'thing')
-    assert.equal(
-      afterFail.status,
-      'pending',
-      'step stays pending after a failed dispatch'
-    )
-
-    const runAfterFail = await ws.getRun(runId)
-    assert.notEqual(
-      runAfterFail?.status,
-      'failed',
-      'run is not failed by a queue blip'
-    )
-
-    await (ws as any).beginReplay(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()
-    ;(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-dispatch-payload.test.ts

@@ -1,55 +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 serviceWithCapturingQueue() {
-  const added: Array<{ queueName: string; data: any }> = []
-  pikkuState(null, 'package', 'singletonServices', {
-    queueService: {
-      add: async (queueName: string, data: any) => {
-        added.push({ queueName, data })
-        return 'job-1'
-      },
-    },
-    logger: silentLogger,
-  } as any)
-  return { ws: new InMemoryWorkflowService() as any, added }
-}
-
-describe('dispatching a step does not serialise the payload twice', () => {
-  test('the queue receives the payload core was given', async () => {
-    const { ws, added } = serviceWithCapturingQueue()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'test',
-    })
-    const payload = { when: new Date('2020-01-01T00:00:00.000Z'), n: 1 }
-
-    await ws.queueStepWorker(runId, 'step-1', 'rpc.fn', payload)
-
-    assert.equal(added.length, 1)
-    assert.ok(
-      added[0]!.data.data.when instanceof Date,
-      'core round-tripped the payload through JSON before handing it to a queue that serialises it anyway'
-    )
-    assert.equal(added[0]!.data.data.n, 1)
-    assert.equal(added[0]!.data.runId, runId)
-    assert.equal(added[0]!.data.stepName, 'step-1')
-  })
-
-  test('a payload the queue cannot serialise is still the queue’s problem, not a silent drop', async () => {
-    const { ws, added } = serviceWithCapturingQueue()
-    const runId = await ws.createRun('flow', {}, false, 'hash', {
-      type: 'test',
-    })
-    const circular: any = { name: 'loop' }
-    circular.self = circular
-
-    await ws.queueStepWorker(runId, 'step-1', 'rpc.fn', circular)
-
-    assert.equal(added[0]!.data.data.self, added[0]!.data.data)
-  })
-})