@pikku/core 0.12.79 → 0.12.82

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -1,168 +1,22 @@
-import { runPikkuFunc, addFunction } from '../../function/function-runner.js';
-import { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
-import { wireQueueWorker } from '../queue/queue-runner.js';
+import { runPikkuFunc } from '../../function/function-runner.js';
 import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-const resolveWorkflowMeta = (name) => {
-    const rootMeta = pikkuState(null, 'workflows', 'meta');
-    if (rootMeta[name]) {
-        return { meta: rootMeta[name], packageName: null, resolvedName: name };
-    }
-    const colonIndex = name.indexOf(':');
-    if (colonIndex !== -1) {
-        const namespace = name.substring(0, colonIndex);
-        const localName = name.substring(colonIndex + 1);
-        const addons = pikkuState(null, 'addons', 'packages');
-        const pkgConfig = addons?.get(namespace);
-        if (pkgConfig) {
-            const addonMeta = pikkuState(pkgConfig.package, 'workflows', 'meta');
-            if (addonMeta?.[localName]) {
-                return {
-                    meta: addonMeta[localName],
-                    packageName: pkgConfig.package,
-                    resolvedName: localName,
-                };
-            }
-        }
-    }
-    return null;
-};
-const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
-import { PikkuError, addError, isExpectedError, } from '../../errors/error-handler.js';
+import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
+import { isExpectedError } from '../../errors/error-handler.js';
+import { PikkuMissingMetaError } from '../../errors/errors.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
-import { ChildWorkflowStartedException } from './graph/graph-runner.js';
 import { deriveInvocationId } from './workflow-invocation-id.js';
+import { approvalDeciderFrom } from './workflow-approval-policy.js';
 import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
-export const DEFAULT_STEP_RETRIES = 5;
-export class WorkflowAsyncException extends Error {
-    runId;
-    stepName;
-    constructor(runId, stepName) {
-        super(`Workflow paused at step: ${stepName}`);
-        this.runId = runId;
-        this.stepName = stepName;
-        this.name = 'WorkflowAsyncException';
-    }
-}
-export class WorkflowCancelledException extends Error {
-    runId;
-    reason;
-    constructor(runId, reason) {
-        super(reason || 'Workflow cancelled');
-        this.runId = runId;
-        this.reason = reason;
-        this.name = 'WorkflowCancelledException';
-    }
-}
-export class WorkflowSuspendedException extends Error {
-    runId;
-    reason;
-    constructor(runId, reason) {
-        super(reason || 'Workflow suspended');
-        this.runId = runId;
-        this.reason = reason;
-        this.name = 'WorkflowSuspendedException';
-    }
-}
-export class WorkflowDispatchException extends Error {
-    runId;
-    stepName;
-    constructor(runId, stepName, options) {
-        super(`Failed to dispatch workflow step '${stepName}' (run ${runId})`, options);
-        this.runId = runId;
-        this.stepName = stepName;
-        this.name = 'WorkflowDispatchException';
-    }
-}
-export class WorkflowNotFoundError extends PikkuError {
-    constructor(name) {
-        super(`Workflow not found: ${name}`);
-    }
-}
-addError(WorkflowNotFoundError, {
-    status: 404,
-    message: 'Workflow not found.',
-});
-export class WorkflowRunNotFoundError extends PikkuError {
-    constructor(runId) {
-        super(`Workflow run not found: ${runId}`);
-    }
-}
-addError(WorkflowRunNotFoundError, {
-    status: 404,
-    message: 'Workflow run not found.',
-});
-export class WorkflowRunFailedError extends PikkuError {
-    payload;
-    constructor(message) {
-        super(`Workflow run failed: ${message ?? 'unknown'}`);
-        this.payload = { message };
-    }
-}
-addError(WorkflowRunFailedError, {
-    status: 422,
-    message: 'Workflow run failed.',
-});
-export class WorkflowRunCancelledError extends PikkuError {
-    constructor() {
-        super('Workflow was cancelled');
-    }
-}
-addError(WorkflowRunCancelledError, {
-    status: 409,
-    message: 'Workflow was cancelled.',
-});
-export class WorkflowApprovalResolvedError extends PikkuError {
-    payload;
-    constructor(reason, outcome) {
-        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) {
-        super(`Workflow step name must be a string. Received: ${typeof stepName}`);
-    }
-}
-const WORKFLOW_END_STATES = new Set([
-    'completed',
-    'failed',
-    'cancelled',
-    'suspended',
-]);
-const WORKFLOW_TERMINAL_STATES = new Set([
-    'completed',
-    'failed',
-    'cancelled',
-]);
-/** Idle window before a `running` run with nothing in flight is treated as stalled. */
-const DEFAULT_STALLED_RUN_MS = 5 * 60_000;
-/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
-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.
- */
-const DEFAULT_UNDISPATCHED_STEP_MS = 30_000;
-/** Steps re-driven per `relayUndispatchedSteps` call, so one tick is bounded. */
-const DEFAULT_UNDISPATCHED_STEP_LIMIT = 100;
-/** First wait before a step already re-dispatched once is re-dispatched again. */
-const REDISPATCH_BACKOFF_MS = 30_000;
-/** Ceiling on the doubling backoff, so a permanently stuck step still gets swept. */
-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. */
-const REDISPATCH_BACKOFF_MAX_ENTRIES = 10_000;
-const WORKFLOW_POLL_MIN_MS = 10;
-const WORKFLOW_POLL_FACTOR = 1.6;
-const WORKFLOW_CHILD_POLL_MAX_MS = 500;
+import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, } from './workflow-constants.js';
+import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepFunctionMismatchError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
+import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
+import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
+import { wireWorkflowQueueWorkers } from './workflow-queue-wiring.js';
+import { approvalStepNameFor, evaluateApprovalStep, recordApprovalDecision, } from './workflow-approval.js';
+import { auditApprovalDecision } from './workflow-approval-audit.js';
+import { recordSuspension, suspendStepNameFor } from './workflow-suspend.js';
+import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
 export class PikkuWorkflowService {
     runExtension;
     runContexts = new Map();
@@ -236,76 +90,12 @@ export class PikkuWorkflowService {
         return written;
     }
     wireQueueWorkers() {
-        const functions = pikkuState(null, 'function', 'functions');
-        const functionsMeta = pikkuState(null, 'function', 'meta');
-        const mkMeta = (funcId) => ({
-            pikkuFuncId: funcId,
-            sessionless: true,
-            functionType: 'helper',
-            inputSchemaName: null,
-            outputSchemaName: null,
+        wireWorkflowQueueWorkers({
+            strategy: this.queueStrategy,
+            concurrency: this.queueConcurrency,
+            groupConcurrency: this.queueGroupConcurrency,
+            getLogger: () => this.logger,
         });
-        const queueMeta = pikkuState(null, 'queue', 'meta');
-        const registerWorkflowFunc = (funcId, func, queueName, config) => {
-            if (functions.has(funcId))
-                return;
-            addFunction(funcId, func);
-            if (!queueMeta[queueName]) {
-                queueMeta[queueName] = { pikkuFuncId: funcId, name: queueName };
-            }
-            wireQueueWorker({ name: queueName, func, config });
-            if (!functionsMeta[funcId]) {
-                functionsMeta[funcId] = mkMeta(funcId);
-            }
-        };
-        const sharedGroups = this.queueStrategy === 'shared-groups';
-        const sharedQueueConfig = sharedGroups
-            ? {
-                batchSize: this.queueConcurrency,
-                groupConcurrency: this.queueGroupConcurrency,
-            }
-            : undefined;
-        registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator', sharedQueueConfig);
-        registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker', sharedQueueConfig);
-        const registerQueueWorkers = (queueMeta) => {
-            for (const [queueName, meta] of Object.entries(queueMeta)) {
-                if (functions.has(meta.pikkuFuncId))
-                    continue;
-                if (queueName.startsWith('wf-orchestrator-')) {
-                    registerWorkflowFunc(meta.pikkuFuncId, { func: pikkuWorkflowOrchestratorFunc }, queueName);
-                }
-                else if (queueName.startsWith('wf-step-')) {
-                    registerWorkflowFunc(meta.pikkuFuncId, { func: pikkuWorkflowWorkerFunc }, queueName);
-                }
-            }
-        };
-        if (!sharedGroups) {
-            registerQueueWorkers(pikkuState(null, 'queue', 'meta'));
-            const addons = pikkuState(null, 'addons', 'packages');
-            if (addons) {
-                for (const [, addon] of addons) {
-                    const addonQueueMeta = pikkuState(addon.package, 'queue', 'meta');
-                    if (addonQueueMeta) {
-                        registerQueueWorkers(addonQueueMeta);
-                    }
-                }
-            }
-        }
-        const workflowCount = Object.keys(pikkuState(null, 'workflows', 'meta') ?? {}).length;
-        const perWorkflowQueues = Object.keys(queueMeta).filter((name) => name.startsWith('wf-orchestrator-')).length;
-        if (workflowCount > 0 && perWorkflowQueues === 0) {
-            this.logger?.warn?.(`[pikku] ${workflowCount} workflow(s) registered but no per-workflow orchestrator queues were found in queue meta. ` +
-                `All workflows will share a single orchestrator queue, where one slow step blocks every other workflow behind it. ` +
-                `Check that the generated bootstrap imports the queue-workers meta (pikku-queue-workers-wirings-meta.gen.js).`);
-        }
-        if (!functions.has('pikkuWorkflowSleeper')) {
-            addFunction('pikkuWorkflowSleeper', {
-                func: pikkuWorkflowSleeperFunc,
-            });
-        }
-        if (!functionsMeta.pikkuWorkflowSleeper) {
-            functionsMeta.pikkuWorkflowSleeper = mkMeta('pikkuWorkflowSleeper');
-        }
     }
     async isInline(runId) {
         const context = this.runContexts.get(runId);
@@ -465,41 +255,6 @@ export class PikkuWorkflowService {
     async findStalledRunIds(_before, _limit) {
         return [];
     }
-    /**
-     * Re-drive runs whose next move was lost, and report which were resumed.
-     *
-     * Arming a step is two writes to two systems — the step row, then the queue
-     * or scheduler job — so a process that dies between them leaves a run that is
-     * `running` with nothing in flight. Nothing notices: the run parks on a step
-     * that will never complete and never error, so it neither finishes nor fails.
-     * (Seen on a `workflow.sleep()`: a deploy restart landed between the sleep
-     * step's insert and its timer, parking the run permanently.)
-     *
-     * Replay is the recovery — `resumeWorkflow` re-orchestrates from persisted
-     * step state, and every settled step is memoized, so resuming a run that was
-     * not actually stuck costs an orchestration pass and changes nothing. That
-     * idempotence is what makes an idle-time heuristic safe here; a run that is
-     * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
-     *
-     * This is not self-starting. Call it from a scheduled task at whatever
-     * interval suits the workload.
-     */
-    async recoverStalledRuns(options) {
-        const before = new Date(Date.now() - (options?.stalledAfterMs ?? DEFAULT_STALLED_RUN_MS));
-        const runIds = await this.findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
-        const resumed = [];
-        for (const runId of runIds) {
-            try {
-                await this.resumeWorkflow(runId);
-                resumed.push(runId);
-            }
-            catch (err) {
-                // One unresumable run must not stop the sweep from recovering the rest.
-                getSingletonServices()?.logger?.error(`Failed to resume stalled workflow run ${runId}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-        return { resumed };
-    }
     /**
      * Runs holding a step that has sat `pending` since before `before`, paired
      * with the step that flagged them.
@@ -516,89 +271,30 @@ export class PikkuWorkflowService {
     async findUndispatchedSteps(_before, _limit) {
         return [];
     }
+    redispatchBackoff = new RedispatchBackoff();
+    get sweepDeps() {
+        return {
+            resume: (runId) => this.resumeWorkflow(runId),
+            logger: getSingletonServices()?.logger,
+        };
+    }
     /**
-     * Re-drive steps whose dispatch was lost, and report which runs were nudged.
-     *
-     * Arming a step is two writes to two systems: the step row lands `pending`,
-     * then a queue or scheduler job is published. Nothing spans both, so a crash
-     * in between leaves a durable row that nothing will ever pick up — the run
-     * neither finishes nor fails. (Seen on a `workflow.sleep()`: a deploy restart
-     * landed between the sleep step's insert and its timer.)
-     *
-     * The row is the outbox record and this is the relay. Age is the only signal
-     * available — a step `pending` because its dispatch was lost is
-     * indistinguishable from one whose job is merely still queued — so a step
-     * past `undispatchedAfterMs` is re-dispatched regardless, and correctness
-     * rests on the claim rather than on the guess being right. A redundant
-     * dispatch costs one queue message: the loser reads `running` and returns
-     * without invoking anything.
-     *
-     * Re-dispatches back off per step (doubling from 30s, capped at 10m) so a
-     * genuine queue backlog is not amplified by a tick that keeps firing at the
-     * steps the backlog is already delaying. The backoff is per process and
-     * advisory — losing it on restart costs extra dispatches, never correctness.
-     *
-     * This is not self-starting. Call it from a scheduled task; ~30s suits a
-     * queue whose `pending`→`running` latency is well under that.
+     * Re-drive runs whose next move was lost. Not self-starting — call it from a
+     * scheduled task at whatever interval suits the workload.
+     */
+    async recoverStalledRuns(options) {
+        return sweepStalledRuns((before, limit) => this.findStalledRunIds(before, limit), options, this.sweepDeps);
+    }
+    /**
+     * Re-drive steps whose dispatch was lost. Not self-starting — call it from a
+     * scheduled task; ~30s suits a queue whose `pending`→`running` latency is
+     * well under that.
      */
     async relayUndispatchedSteps(options) {
-        const before = new Date(Date.now() -
-            (options?.undispatchedAfterMs ?? DEFAULT_UNDISPATCHED_STEP_MS));
-        const steps = await this.findUndispatchedSteps(before, options?.limit ?? DEFAULT_UNDISPATCHED_STEP_LIMIT);
-        // Backoff is keyed by run, not step, because the run is the unit of
-        // re-drive: `resumeWorkflow` replays the whole run and re-dispatches every
-        // step still owed a job. Holding off a single step while resuming its run
-        // would not suppress anything.
-        const now = Date.now();
-        const runIds = new Set();
-        for (const { runId } of steps) {
-            const eligibleAt = this.redispatchBackoff.get(runId);
-            if (eligibleAt !== undefined && eligibleAt > now) {
-                continue;
-            }
-            this.noteRedispatch(runId, now);
-            runIds.add(runId);
-        }
-        const redispatched = [];
-        for (const runId of runIds) {
-            try {
-                await this.resumeWorkflow(runId);
-                redispatched.push(runId);
-            }
-            catch (err) {
-                // One unresumable run must not stop the tick from relaying the rest.
-                getSingletonServices()?.logger?.error(`Failed to re-dispatch workflow run ${runId}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-        return { redispatched };
-    }
-    /** Advisory, per-process record of when a run may next be re-dispatched. */
-    redispatchBackoff = new Map();
-    redispatchDelays = new Map();
-    noteRedispatch(runId, now) {
-        const previous = this.redispatchDelays.get(runId);
-        const delay = Math.min(previous === undefined ? REDISPATCH_BACKOFF_MS : previous * 2, REDISPATCH_BACKOFF_MAX_MS);
-        // A run that settles is never returned again, so entries are only evicted by
-        // this bound — oldest first, which is also least recently re-dispatched.
-        if (this.redispatchBackoff.size >= REDISPATCH_BACKOFF_MAX_ENTRIES) {
-            const oldest = this.redispatchBackoff.keys().next();
-            if (!oldest.done) {
-                this.redispatchBackoff.delete(oldest.value);
-                this.redispatchDelays.delete(oldest.value);
-            }
-        }
-        this.redispatchDelays.set(runId, delay);
-        this.redispatchBackoff.set(runId, now + delay);
+        return sweepUndispatchedSteps((before, limit) => this.findUndispatchedSteps(before, limit), this.redispatchBackoff, options, this.sweepDeps);
     }
     resolveStepJobOptions(stepOptions) {
-        const retries = stepOptions?.retries ?? DEFAULT_STEP_RETRIES;
-        const retryDelay = stepOptions?.retryDelay;
-        const backoff = retryDelay !== undefined && retryDelay !== 'exponential'
-            ? { type: 'fixed', delay: getDurationInMilliseconds(retryDelay) }
-            : retries > 0 || retryDelay === 'exponential'
-                ? 'exponential'
-                : undefined;
-        return { attempts: retries + 1, ...(backoff ? { backoff } : {}) };
+        return stepJobOptions(stepOptions);
     }
     async queueStepWorker(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         const queueService = this.verifyQueueService();
@@ -676,6 +372,18 @@ export class PikkuWorkflowService {
             throw new WorkflowNotFoundError(name);
         }
         if (workflowMeta.source === 'graph') {
+            // A caller-supplied startNode must be one of the graph's declared entry
+            // nodes. startWorkflow is the boundary the public
+            // `/workflow/:name/graph/:nodeId` route and triggers enter through, so
+            // without this a request could name any dependency-free node — one whose
+            // input reads only `trigger` — and fire its RPC directly with
+            // attacker-chosen data, skipping every upstream eligibility, validation or
+            // approval node. (Internal resume/replay drives runWorkflowGraph directly
+            // and is unaffected.)
+            if (options?.startNode &&
+                !(workflowMeta.entryNodeIds ?? []).includes(options.startNode)) {
+                throw new Error(`Workflow graph '${name}': '${options.startNode}' is not a declared entry node`);
+            }
             const shouldInline = options?.inline || !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire, workflowMeta);
         }
@@ -859,6 +567,9 @@ export class PikkuWorkflowService {
             return;
         }
         const registrations = pikkuState(pkgName, 'workflows', 'registrations');
+        if (!workflowMeta) {
+            throw new PikkuMissingMetaError(`Missing generated metadata for workflow '${run.workflow}'`);
+        }
         const workflow = registrations.get(resolved?.resolvedName ?? run.workflow);
         if (!workflow) {
             throw new WorkflowNotFoundError(run.workflow);
@@ -869,11 +580,10 @@ export class PikkuWorkflowService {
                 : null;
             const workflowWire = this.createWorkflowWire(run.workflow, runId, rpcService, addonNs);
             workflowWire.pikkuUserId = run.wire?.pikkuUserId;
+            // No `rpc` yet — runPikkuFunc attaches it lazily for the invocation.
             const wire = {
                 workflow: workflowWire,
                 pikkuUserId: run.wire?.pikkuUserId,
-                session: rpcService?.wire?.session,
-                rpc: rpcService?.wire?.rpc,
             };
             this.runExtension?.decorateRunWire(wire, {
                 runId,
@@ -990,6 +700,11 @@ export class PikkuWorkflowService {
     async executeWorkflowStepInner(runId, stepName, rpcName, data, rpcService) {
         const claimed = await this.withStepLock(runId, stepName, async () => {
             const stepState = await this.getStepState(runId, stepName);
+            // knowledge: decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md
+            if (stepState.rpcName !== undefined &&
+                stepState.rpcName !== (rpcName ?? null)) {
+                throw new WorkflowStepFunctionMismatchError(runId, stepName);
+            }
             if (stepState.status === 'succeeded' || stepState.status === 'running') {
                 return null;
             }
@@ -1027,7 +742,7 @@ export class PikkuWorkflowService {
                 }
             }
             if (graphNodeId) {
-                result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, rpcName, data, run.workflow);
+                result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, workflowMeta.nodes[graphNodeId].rpcName, data, run.workflow);
             }
             else {
                 const subWorkflowMeta = meta[rpcName];
@@ -1037,7 +752,7 @@ export class PikkuWorkflowService {
                         id: rpcName,
                         parentRunId: runId,
                         parentStepId: stepState.stepId,
-                        pikkuUserId: rpcService.wire?.pikkuUserId,
+                        pikkuUserId: run.wire?.pikkuUserId,
                     };
                     const shouldInline = !getSingletonServices()?.queueService;
                     const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
@@ -1202,7 +917,7 @@ export class PikkuWorkflowService {
                     type: 'workflow',
                     id: rpcName,
                     parentRunId: runId,
-                    pikkuUserId: rpcService.wire?.pikkuUserId,
+                    pikkuUserId: (await this.getRunIdentity(runId))?.wire?.pikkuUserId,
                 };
                 const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: true });
                 await this.setStepChildRunId(currentStepState.stepId, childRunId);
@@ -1281,39 +996,10 @@ export class PikkuWorkflowService {
         await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(duration)));
         await this.setStepResult(stepState.stepId, null);
     }
-    getSuspendStepName(reason) {
-        return `__workflow_suspend:${reason}`;
-    }
     async suspendStep(runId, reason) {
         const fromStepName = this.lastStepName(runId);
-        const suspendStepName = this.nextStepKey(runId, this.getSuspendStepName(reason));
-        await this.withStepLock(runId, suspendStepName, async () => {
-            let stepState;
-            try {
-                stepState = await this.getStepState(runId, suspendStepName);
-            }
-            catch {
-                stepState = await this.insertStepState(runId, suspendStepName, 'pikkuWorkflowSuspend', {
-                    reason,
-                }, undefined, fromStepName);
-            }
-            if (!stepState.stepId) {
-                stepState = await this.insertStepState(runId, suspendStepName, 'pikkuWorkflowSuspend', {
-                    reason,
-                }, undefined, fromStepName);
-            }
-            if (stepState.status === 'succeeded') {
-                return;
-            }
-            if (stepState.status === 'pending') {
-                await this.setStepRunning(stepState.stepId);
-            }
-            await this.setStepResult(stepState.stepId, {
-                reason,
-                suspendedAt: new Date().toISOString(),
-            });
-            throw new WorkflowSuspendedException(runId, reason);
-        });
+        const suspendStepName = this.nextStepKey(runId, suspendStepNameFor(reason));
+        await this.withStepLock(runId, suspendStepName, () => recordSuspension(this.approvalStore, runId, reason, suspendStepName, fromStepName));
     }
     async scheduleRunWake(runId, delay) {
         try {
@@ -1331,96 +1017,27 @@ export class PikkuWorkflowService {
             this.logger?.warn(`Failed to schedule approval expiry wake for run ${runId}; expiry will still resolve on the next replay`, error);
         }
     }
-    getApprovalStepName(reason) {
-        return `__workflow_approval:${reason}`;
-    }
-    approvalStateKey(stepName) {
-        let hex = '';
-        for (const byte of new TextEncoder().encode(stepName)) {
-            hex += byte.toString(16).padStart(2, '0');
-        }
-        return `__approval_${hex}`;
+    get approvalStore() {
+        return {
+            getStepState: (runId, stepName) => this.getStepState(runId, stepName),
+            insertStepState: (runId, stepName, rpcName, input, output, fromStepName) => this.insertStepState(runId, stepName, rpcName, input, output, fromStepName),
+            setStepRunning: (stepId) => this.setStepRunning(stepId),
+            setStepResult: (stepId, result) => this.setStepResult(stepId, result),
+            getRunState: (runId) => this.getRunState(runId),
+            updateRunState: (runId, key, value) => this.updateRunState(runId, key, value),
+            resumeWorkflow: (runId) => this.resumeWorkflow(runId),
+            scheduleRunWake: (runId, delay) => this.scheduleRunWake(runId, delay),
+            getRunOwner: async (runId) => (await this.getRunIdentity(runId))?.wire?.pikkuUserId,
+            auditApproval: (event) => auditApprovalDecision(event),
+        };
     }
-    async approveStep(runId, reason, decision) {
-        const stepName = this.getApprovalStepName(reason);
-        const stateKey = this.approvalStateKey(stepName);
-        let resolved;
-        try {
-            resolved = await this.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;
-            throw new WorkflowApprovalResolvedError(reason, outcome?.status ?? 'decided');
-        }
-        const state = await this.getRunState(runId);
-        const record = (state[stateKey] ?? {});
-        await this.updateRunState(runId, stateKey, {
-            ...record,
-            decision,
-            decidedAt: new Date().toISOString(),
-            error: undefined,
-        });
-        await this.resumeWorkflow(runId);
+    async approveStep(runId, reason, decision, session) {
+        return recordApprovalDecision(this.approvalStore, runId, reason, decision, approvalDeciderFrom(session));
     }
     async approvalStep(runId, reason, options) {
         const fromStepName = this.lastStepName(runId);
-        const approvalStepName = this.nextStepKey(runId, this.getApprovalStepName(reason));
-        return await this.withStepLock(runId, approvalStepName, async () => {
-            let 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);
-            }
-            if (stepState.status === 'succeeded') {
-                return stepState.result;
-            }
-            const stateKey = this.approvalStateKey(approvalStepName);
-            let record = ((await this.getRunState(runId))[stateKey] ?? {});
-            if (stepState.status === 'pending') {
-                await this.setStepRunning(stepState.stepId);
-                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) {
-                    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 = {
-                    status: 'decided',
-                    data: validation.value,
-                };
-                await this.setStepResult(stepState.stepId, outcome);
-                return outcome;
-            }
-            if (record.expiresAt && Date.now() >= Date.parse(record.expiresAt)) {
-                const outcome = { status: 'expired' };
-                await this.setStepResult(stepState.stepId, outcome);
-                return outcome;
-            }
-            throw new WorkflowSuspendedException(runId, reason);
-        });
+        const approvalStepName = this.nextStepKey(runId, approvalStepNameFor(reason));
+        return await this.withStepLock(runId, approvalStepName, () => evaluateApprovalStep(this.approvalStore, runId, reason, approvalStepName, fromStepName, options));
     }
     createWorkflowWire(name, runId, rpcService, addonNamespace) {
         const workflowWire = {
@@ -1466,40 +1083,15 @@ export class PikkuWorkflowService {
         }
     }
     getConfig() {
-        const singletonServices = getSingletonServices();
-        const workflow = singletonServices.config?.workflow;
-        return {
-            retries: workflow?.retries ?? DEFAULT_STEP_RETRIES,
-            retryDelay: workflow?.retryDelay ?? 0,
-            orchestratorQueueName: workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
-            stepWorkerQueueName: workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',
-            sleeperRPCName: workflow?.sleeperRPCName ?? 'pikkuWorkflowSleeper',
-        };
+        return resolveWorkflowConfig();
     }
     getOrchestratorQueueName(workflowName) {
-        if (workflowName && this.queueStrategy !== 'shared-groups') {
-            const perWorkflow = `wf-orchestrator-${toKebab(workflowName)}`;
-            const meta = pikkuState(null, 'queue', 'meta');
-            if (meta[perWorkflow]) {
-                return perWorkflow;
-            }
-        }
-        return this.getConfig().orchestratorQueueName;
+        return orchestratorQueueName(this.queueStrategy, workflowName);
     }
     getStepWorkerQueueName(rpcName) {
-        if (rpcName && this.queueStrategy !== 'shared-groups') {
-            const perStep = `wf-step-${toKebab(rpcName)}`;
-            const meta = pikkuState(null, 'queue', 'meta');
-            if (meta[perStep]) {
-                return perStep;
-            }
-        }
-        return this.getConfig().stepWorkerQueueName;
+        return stepWorkerQueueName(this.queueStrategy, rpcName);
     }
     getJobGroup(id) {
-        if (!id || this.queueStrategy !== 'shared-groups') {
-            return undefined;
-        }
-        return { id, tier: id };
+        return jobGroupFor(this.queueStrategy, id);
     }
 }