@pikku/core 0.12.78 → 0.12.80

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

@@ -1,154 +1,21 @@
-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 { assertWorkflowRunOwner } from './workflow-run-ownership.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;
-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 { recordSuspension, suspendStepNameFor } from './workflow-suspend.js';
+import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
 export class PikkuWorkflowService {
     runExtension;
     runContexts = new Map();
@@ -222,76 +89,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);
@@ -452,49 +255,45 @@ export class PikkuWorkflowService {
         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.)
+     * Runs holding a step that has sat `pending` since before `before`, paired
+     * with the step that flagged them.
      *
-     * 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.
+     * Returns nothing by default so a store that cannot express the query keeps
+     * working unchanged — and, because it does not opt in, gains no re-dispatches
+     * either. A store must have an atomic `withStepLock` before overriding this,
+     * or no concurrency for one to exclude: the relay makes duplicate dispatch
+     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
+     * duplicate from becoming a second execution. `kysely-postgres` and
+     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
+     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     */
+    async findUndispatchedSteps(_before, _limit) {
+        return [];
+    }
+    redispatchBackoff = new RedispatchBackoff();
+    get sweepDeps() {
+        return {
+            resume: (runId) => this.resumeWorkflow(runId),
+            logger: getSingletonServices()?.logger,
+        };
+    }
+    /**
+     * 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) {
-        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 };
+        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) {
+        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();
@@ -755,6 +554,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);
@@ -765,11 +567,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,
@@ -886,6 +687,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;
             }
@@ -923,7 +729,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];
@@ -933,7 +739,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 });
@@ -1098,7 +904,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);
@@ -1177,39 +983,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 {
@@ -1227,96 +1004,26 @@ 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),
+        };
     }
-    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) {
+        assertWorkflowRunOwner((await this.getRunIdentity(runId))?.wire, session);
+        return recordApprovalDecision(this.approvalStore, runId, reason, decision);
     }
     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 = {
@@ -1362,40 +1069,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);
     }
 }

package/dist/wirings/workflow/workflow-approval.d.ts

@@ -0,0 +1,39 @@
+import type { ApprovalOutcome, StepState, WorkflowApprovalOptions } from './workflow.types.js';
+/** The durable step name an approval point is recorded under. */
+export declare const approvalStepNameFor: (reason: string) => string;
+/**
+ * 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 declare const approvalStateKey: (stepName: string) => 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>;
+};
+/**
+ * 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.
+ */
+export declare const recordApprovalDecision: (store: ApprovalStore, runId: string, reason: string, decision: unknown) => Promise<void>;
+/**
+ * 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.
+ */
+export declare const evaluateApprovalStep: (store: ApprovalStore, runId: string, reason: string, approvalStepName: string, fromStepName: string | undefined, options: WorkflowApprovalOptions) => Promise<ApprovalOutcome<unknown>>;