@pikku/core 0.12.63 → 0.12.66

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -48,9 +48,11 @@ import type { PikkuWire, SerializedError } from '../../types/core.types.js'
 import type { QueueService } from '../queue/queue.types.js'
 import { runScheduledTask } from '../scheduler/scheduler-runner.js'
 import type {
+  ApprovalOutcome,
   PikkuScenarioWire,
   StepState,
   StepStatus,
+  WorkflowApprovalOptions,
   WorkflowPlannedStep,
   WorkflowRun,
   WorkflowRunMirror,
@@ -203,6 +205,27 @@ addError(WorkflowRunCancelledError, {
   message: 'Workflow was cancelled.',
 })
 
+/**
+ * A decision arrived for an approval gate that has already resolved. The gate
+ * caches its outcome as the step result and never re-reads run state, so the
+ * decision could not take effect — it is rejected rather than accepted and
+ * dropped.
+ */
+export class WorkflowApprovalResolvedError extends PikkuError {
+  public payload: {
+    reason: string
+    outcome: ApprovalOutcome<unknown>['status']
+  }
+  constructor(reason: string, outcome: ApprovalOutcome<unknown>['status']) {
+    super(`Approval already ${outcome}: ${reason}`)
+    this.payload = { reason, outcome }
+  }
+}
+addError(WorkflowApprovalResolvedError, {
+  status: 409,
+  message: 'Approval has already been resolved.',
+})
+
 export class WorkflowServiceNotInitialized extends Error {}
 export class WorkflowStepNameNotString extends Error {
   constructor(stepName: any) {
@@ -1802,6 +1825,30 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
   }
 
+  /**
+   * Run a failed step's compensation handler as a durable step of its own.
+   *
+   * Durable rather than a bare invoke so a replay does not compensate twice —
+   * a handler is typically a refund or a rollback. `onError` is deliberately
+   * not forwarded: a compensation handler cannot itself compensate.
+   */
+  private async runStepCompensation(
+    runId: string,
+    stepName: string,
+    onErrorRpcName: string,
+    rpcService: any,
+    error: Error
+  ): Promise<void> {
+    await this.rpcStep(
+      runId,
+      `${stepName}:onError`,
+      onErrorRpcName,
+      { error: { message: error.message } },
+      rpcService,
+      { retries: 0 }
+    )
+  }
+
   private async rpcStep(
     runId: string,
     logicalStepName: string,
@@ -1821,6 +1868,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
       retryDelay: stepOptions?.retryDelay,
       actor: stepOptions?.actor,
+      onError: stepOptions?.onError,
     }
     // Check if step already exists
     let stepState: StepState
@@ -1849,6 +1897,17 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         stepState.error?.message ||
           `Step '${stepName}' failed after exhausting all retries`
       )
+      // Compensation, mirroring a graph node's onError: run the handler, then
+      // still throw — the workflow fails either way.
+      if (resolvedStepOptions.onError) {
+        await this.runStepCompensation(
+          runId,
+          stepName,
+          resolvedStepOptions.onError,
+          rpcService,
+          error
+        )
+      }
       // Preserve original error properties if available
       if (stepState.error) {
         Object.assign(error, stepState.error)
@@ -2148,6 +2207,214 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     })
   }
 
+  /**
+   * Wake a run later by enqueuing a delayed orchestrator pass. Deliberately NOT
+   * {@link scheduleSleep}: that resolves the step it is given, which for an
+   * approval would resolve the gate itself. This only nudges the run to replay
+   * and re-evaluate — the gate stays the sole judge of its own outcome.
+   *
+   * Best-effort by design. Expiry is decided from the recorded deadline on
+   * replay, so losing this wake costs liveness (the run sits until something
+   * else resumes it), never correctness.
+   */
+  private async scheduleRunWake(runId: string, delay: number): Promise<void> {
+    try {
+      const queueService = this.verifyQueueService()
+      const run = await this.getRun(runId)
+      if (!run?.workflow) return
+      await queueService.add(
+        this.getOrchestratorQueueName(run.workflow),
+        { runId },
+        { ...this.resolveStepJobOptions(), delay }
+      )
+    } catch (error) {
+      this.logger?.warn(
+        `Failed to schedule approval expiry wake for run ${runId}; expiry will still resolve on the next replay`,
+        error
+      )
+    }
+  }
+
+  /**
+   * Durable step name for an approval gate. Namespaced separately from suspend
+   * so the two can't collide, and derived from `reason` for the same reason
+   * {@link getSuspendStepName} is: it must be stable across replays.
+   */
+  private getApprovalStepName(reason: string): string {
+    return `__workflow_approval:${reason}`
+  }
+
+  /**
+   * Run-state key holding an approval gate's record. Hex-encoded because the
+   * Mongo backend restricts state keys to `/^[a-zA-Z0-9_]+$/` and a `reason` is
+   * arbitrary human text. One key per gate, so two gates resolving concurrently
+   * can't clobber each other through a read-modify-write.
+   */
+  private approvalStateKey(stepName: string): string {
+    let hex = ''
+    for (const byte of new TextEncoder().encode(stepName)) {
+      hex += byte.toString(16).padStart(2, '0')
+    }
+    return `__approval_${hex}`
+  }
+
+  /**
+   * Record a decision against an approval gate and wake the run. Called from
+   * outside the workflow (an HTTP route, an RPC), so the schema value is NOT in
+   * scope here — the payload is stored raw and validated on replay inside the
+   * workflow body, which is the only place the schema exists. An invalid payload
+   * therefore leaves the gate closed rather than failing the run.
+   *
+   * `reason` addresses the first reach of that gate. An approval reached more
+   * than once under the same reason (e.g. in a loop) gets `#N`-suffixed step
+   * rows that this cannot currently target.
+   */
+  public async approveStep(
+    runId: string,
+    reason: string,
+    decision: unknown
+  ): Promise<void> {
+    const stepName = this.getApprovalStepName(reason)
+    const stateKey = this.approvalStateKey(stepName)
+
+    // A resolved gate returns its cached step result and never re-reads state,
+    // so a decision recorded now would be silently discarded — most obviously
+    // when it loses the race with expiry. Reject instead, so the approver
+    // learns their decision did not land.
+    let resolved: StepState | undefined
+    try {
+      resolved = await this.getStepState(runId, stepName)
+    } catch {
+      // No step row yet: the run has not reached the gate. Recording a decision
+      // ahead of it is legitimate — the gate picks it up on arrival.
+    }
+    if (resolved?.stepId && resolved.status === 'succeeded') {
+      const outcome = resolved.result as ApprovalOutcome<unknown> | undefined
+      throw new WorkflowApprovalResolvedError(
+        reason,
+        outcome?.status ?? 'decided'
+      )
+    }
+
+    const state = await this.getRunState(runId)
+    const record = (state[stateKey] ?? {}) as Record<string, unknown>
+    await this.updateRunState(runId, stateKey, {
+      ...record,
+      decision,
+      decidedAt: new Date().toISOString(),
+      error: undefined,
+    })
+    await this.resumeWorkflow(runId)
+  }
+
+  private async approvalStep(
+    runId: string,
+    reason: string,
+    options: WorkflowApprovalOptions
+  ): Promise<ApprovalOutcome<unknown>> {
+    const fromStepName = this.lastStepName(runId)
+    const approvalStepName = this.nextStepKey(
+      runId,
+      this.getApprovalStepName(reason)
+    )
+    return await this.withStepLock(runId, approvalStepName, async () => {
+      let stepState: StepState
+      try {
+        stepState = await this.getStepState(runId, approvalStepName)
+      } catch {
+        stepState = await this.insertStepState(
+          runId,
+          approvalStepName,
+          'pikkuWorkflowApproval',
+          { reason, expiry: options.expiry },
+          undefined,
+          fromStepName
+        )
+      }
+      if (!stepState.stepId) {
+        stepState = await this.insertStepState(
+          runId,
+          approvalStepName,
+          'pikkuWorkflowApproval',
+          { reason, expiry: options.expiry },
+          undefined,
+          fromStepName
+        )
+      }
+
+      // Unlike suspend, `succeeded` here means a decision (or expiry) was
+      // actually resolved, and the step result IS the return channel.
+      if (stepState.status === 'succeeded') {
+        return stepState.result as ApprovalOutcome<unknown>
+      }
+
+      const stateKey = this.approvalStateKey(approvalStepName)
+      let record = ((await this.getRunState(runId))[stateKey] ?? {}) as {
+        decision?: unknown
+        decidedAt?: string
+        expiresAt?: string
+        error?: unknown
+      }
+
+      if (stepState.status === 'pending') {
+        await this.setStepRunning(stepState.stepId)
+        // First reach: stamp the deadline and nudge the run awake when it
+        // passes. The deadline is what's authoritative — see below.
+        if (options.expiry !== undefined && !record.expiresAt) {
+          const expiresAt = new Date(
+            Date.now() + getDurationInMilliseconds(options.expiry)
+          ).toISOString()
+          record = { ...record, expiresAt }
+          await this.updateRunState(runId, stateKey, record)
+          await this.scheduleRunWake(
+            runId,
+            getDurationInMilliseconds(options.expiry)
+          )
+        }
+      }
+
+      if (record.decision !== undefined) {
+        const validation = await options.schema['~standard'].validate(
+          record.decision
+        )
+        if (validation.issues) {
+          // Drop the bad decision and re-close the gate, leaving the failure
+          // legible to whoever tries next. Failing the run instead would let any
+          // caller kill a workflow with a malformed payload.
+          await this.updateRunState(runId, stateKey, {
+            ...record,
+            decision: undefined,
+            decidedAt: 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)
+        }
+        const outcome: ApprovalOutcome<unknown> = {
+          status: 'decided',
+          data: validation.value,
+        }
+        await this.setStepResult(stepState.stepId, outcome)
+        return outcome
+      }
+
+      // Expiry is decided by comparing against the recorded deadline rather than
+      // by the timer having fired, so a duplicate, late, or dropped timer all
+      // produce the same answer.
+      if (record.expiresAt && Date.now() >= Date.parse(record.expiresAt)) {
+        const outcome: ApprovalOutcome<unknown> = { status: 'expired' }
+        await this.setStepResult(stepState.stepId, outcome)
+        return outcome
+      }
+
+      throw new WorkflowSuspendedException(runId, reason)
+    })
+  }
+
   public createWorkflowWire(
     name: string,
     runId: string,
@@ -2345,6 +2612,11 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         await this.suspendStep(runId, reason)
       },
 
+      approval: (async (reason: string, options: WorkflowApprovalOptions) => {
+        this.verifyStepName(reason)
+        return await this.approvalStep(runId, reason, options)
+      }) as PikkuScenarioWire['approval'],
+
       runScheduledTask: async (taskName: string) => {
         await runScheduledTask({ name: taskName })
       },

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

@@ -0,0 +1,154 @@
+import { describe, test } from 'node:test'
+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
+  private pretendDispatchSucceeds = false
+
+  public alwaysDispatch() {
+    this.pretendDispatchSucceeds = true
+  }
+
+  protected override async dispatchStep(...args: any[]): Promise<boolean> {
+    this.dispatches++
+    if (this.pretendDispatchSucceeds) {
+      return true
+    }
+    return (super.dispatchStep as any)(...args)
+  }
+
+  public async callFailedStep(
+    runId: string,
+    stepName: string,
+    onError?: string
+  ) {
+    const self = this as any
+    const realRpcStep = self.rpcStep.bind(self)
+    let depth = 0
+    self.rpcStep = async (...args: any[]) => {
+      if (depth++ > 0) {
+        this.compensations.push({ rpcName: args[2], data: args[3] })
+        return { compensated: true }
+      }
+      return realRpcStep(...args)
+    }
+    return self.rpcStep(runId, stepName, 'chargeCard', {}, {}, { onError })
+  }
+}
+
+/**
+ * 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',
+  } as any)
+  const step = await ws.insertStepState(runId, stepName, 'chargeCard', {})
+  return { runId, step }
+}
+
+async function seedFailedStep(ws: TestWorkflowService, stepName: string) {
+  const runId = await ws.createRun('wf', {}, true, 'hash', {
+    type: 'inline',
+  } as any)
+  const step = await ws.insertStepState(runId, stepName, 'chargeCard', {})
+  await (ws as any).updateStepStateImpl?.(runId, stepName, {
+    status: 'failed',
+    error: { message: 'card declined' },
+  })
+  const raw = (ws as any).steps ?? (ws as any).stepStates
+  if (raw?.get) {
+    const key = [...raw.keys()].find((k: string) => k.includes(stepName))
+    if (key) {
+      raw.set(key, {
+        ...raw.get(key),
+        status: 'failed',
+        error: { message: 'card declined' },
+      })
+    }
+  }
+  return { runId, step }
+}
+
+describe('workflow onError — compensation on terminal step failure', () => {
+  test('a failed step runs its handler and still throws the original error', async () => {
+    const ws = new TestWorkflowService()
+    const { runId } = await seedFailedStep(ws, 'Charge')
+
+    await assert.rejects(
+      () => ws.callFailedStep(runId, 'Charge', 'refundOrder'),
+      /card declined/,
+      'compensation must not swallow the failure — the workflow still fails'
+    )
+
+    assert.equal(
+      ws.compensations.length,
+      1,
+      'the onError handler must have been invoked'
+    )
+    assert.equal(ws.compensations[0].rpcName, 'refundOrder')
+    assert.deepEqual(
+      ws.compensations[0].data,
+      { error: { message: 'card declined' } },
+      'the handler receives the failure reason, as a graph onError node does'
+    )
+  })
+
+  test('a step still sitting on the queue pauses without compensating', async () => {
+    const ws = new TestWorkflowService()
+    const { runId, step } = await seedPendingStep(ws, 'Charge')
+    await ws.setStepScheduled(step.stepId)
+
+    await assert.rejects(
+      () => ws.callFailedStep(runId, 'Charge', 'refundOrder'),
+      (error: Error) => error.name === 'WorkflowAsyncException',
+      'a scheduled step must pause the workflow, not fail it'
+    )
+
+    assert.equal(
+      ws.compensations.length,
+      0,
+      'compensating a step that has not run yet would refund a charge that was never made'
+    )
+  })
+
+  test('the pause thrown right after dispatch does not compensate', async () => {
+    const ws = new TestWorkflowService()
+    ws.alwaysDispatch()
+    const { runId } = await seedPendingStep(ws, 'Charge')
+
+    await assert.rejects(
+      () => ws.callFailedStep(runId, 'Charge', 'refundOrder'),
+      (error: Error) => error.name === 'WorkflowAsyncException',
+      'a freshly dispatched step pauses the workflow'
+    )
+
+    assert.equal(ws.dispatches, 1, 'the step should have been dispatched once')
+    assert.equal(
+      ws.compensations.length,
+      0,
+      'queued is not failed — the handler must not run'
+    )
+  })
+
+  test('a failed step with no onError simply throws', async () => {
+    const ws = new TestWorkflowService()
+    const { runId } = await seedFailedStep(ws, 'Charge')
+
+    await assert.rejects(() => ws.callFailedStep(runId, 'Charge', undefined))
+    assert.equal(
+      ws.compensations.length,
+      0,
+      'no handler configured means nothing to compensate'
+    )
+  })
+})

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

@@ -31,7 +31,9 @@ function capturingRpcService(): {
 
 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)
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: silentLogger,
+    } as any)
 
     const ws = new InMemoryWorkflowService()
     const runId = await ws.createRun('flow', {}, false, 'hash', {
@@ -56,19 +58,33 @@ describe('queued workflow steps carry the run 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')
+    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)
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: silentLogger,
+    } 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, 'noauth', 'someFn', {})
     const stepState = await ws.getStepState(runId, 'noauth')
 
     const rpc = capturingRpcService()
-    await (ws as any).invokeStepRpc(runId, 'noauth', stepState, 'someFn', {}, rpc.service)
+    await (ws as any).invokeStepRpc(
+      runId,
+      'noauth',
+      stepState,
+      'someFn',
+      {},
+      rpc.service
+    )
 
     assert.ok(
       !('pikkuUserId' in rpc.wire()),

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

@@ -14,6 +14,9 @@ export type {
   WorkflowWireDoInline,
   WorkflowWireSleep,
   WorkflowWireSuspend,
+  WorkflowWireApproval,
+  WorkflowApprovalOptions,
+  ApprovalOutcome,
   InputSource,
   OutputBinding,
   RpcStepMeta,
@@ -28,6 +31,7 @@ export type {
   SleepStepMeta,
   CancelStepMeta,
   SuspendStepMeta,
+  ApprovalStepMeta,
   SetStepMeta,
   SwitchCaseMeta,
   SwitchStepMeta,
@@ -282,8 +286,6 @@ export type CoreWorkflow<
   func: PikkuFunctionConfig
   /** Middleware chain for this workflow */
   middleware?: PikkuFunctionConfig['middleware']
-  /** Permission requirements */
-  permissions?: PikkuFunctionConfig['permissions']
   /** Tags for organization and filtering */
   tags?: string[]
 }