@pikku/core 0.12.79 → 0.12.82

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -210,6 +210,14 @@ export interface ScenarioBrowserProvider {
      * scenario cannot leave the next signed in as somebody else.
      */
     reset?(): Promise<void>;
+    /**
+     * Name the scenario about to run, so anything it captures is filed under it.
+     *
+     * Called before each scenario. A provider that is never told has to fall
+     * back to one shared label, which puts every run's artifacts in a single
+     * folder — findable only by timestamp.
+     */
+    beginScenario?(scenario: string): void;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must

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

@@ -0,0 +1,16 @@
+import type { ApprovalAuditEvent } from './workflow-approval.js';
+/** The audit type an answer to an approval gate is recorded under. */
+export declare const APPROVAL_AUDIT_TYPE = "workflow.approval.decided";
+/**
+ * Record an answer to an approval gate where it outlives the run.
+ *
+ * The step result carries the settled decision, but it is deleted with the run
+ * — `deleteRun` cascades to steps and to history — and a refused attempt never
+ * reaches a step at all. An approval is asked for precisely so it can be
+ * answered for afterwards, so the answer also goes to the audit sink, which
+ * holds no foreign key to the run.
+ *
+ * A project with no sink wired records nothing, and a sink that fails is logged
+ * rather than thrown: the trail must not be the reason a decision is lost.
+ */
+export declare const auditApprovalDecision: (event: ApprovalAuditEvent) => Promise<void>;

package/dist/wirings/workflow/workflow-approval-audit.js

@@ -0,0 +1,40 @@
+import { getSingletonServices } from '../../pikku-state.js';
+/** The audit type an answer to an approval gate is recorded under. */
+export const APPROVAL_AUDIT_TYPE = 'workflow.approval.decided';
+/**
+ * Record an answer to an approval gate where it outlives the run.
+ *
+ * The step result carries the settled decision, but it is deleted with the run
+ * — `deleteRun` cascades to steps and to history — and a refused attempt never
+ * reaches a step at all. An approval is asked for precisely so it can be
+ * answered for afterwards, so the answer also goes to the audit sink, which
+ * holds no foreign key to the run.
+ *
+ * A project with no sink wired records nothing, and a sink that fails is logged
+ * rather than thrown: the trail must not be the reason a decision is lost.
+ */
+export const auditApprovalDecision = async (event) => {
+    const services = getSingletonServices();
+    if (!services?.audit) {
+        return;
+    }
+    try {
+        await services.audit.audit({
+            type: APPROVAL_AUDIT_TYPE,
+            source: 'explicit',
+            outcome: event.outcome,
+            occurredAt: new Date().toISOString(),
+            wireType: 'workflow',
+            userIdentity: { pikkuUserId: event.decidedBy?.userId },
+            metadata: {
+                runId: event.runId,
+                reason: event.reason,
+                scopes: event.decidedBy?.scopes,
+                refusal: event.refusal,
+            },
+        });
+    }
+    catch (error) {
+        services.logger?.warn(`Failed to audit the decision on approval '${event.reason}' for run ${event.runId}`, error);
+    }
+};

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

@@ -0,0 +1,20 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { ApprovalDecider, WorkflowApprovalPolicy } from './dsl/workflow-dsl.types.js';
+export declare class WorkflowApprovalForbiddenError extends ForbiddenError {
+    payload: {
+        reason: string;
+        detail: string;
+    };
+    constructor(reason: string, detail: string);
+}
+export declare const approvalDeciderFrom: (session: CoreUserSession | undefined) => ApprovalDecider | undefined;
+/**
+ * Judge a decision against the gate's declared policy, returning the reason it
+ * is refused or `undefined` if it stands.
+ *
+ * Returns a message rather than throwing because the same judgement is needed
+ * in two places with different outcomes: refusing a live submission with a 403,
+ * and clearing an already-recorded decision on replay.
+ */
+export declare const approvalPolicyRefusal: (policy: WorkflowApprovalPolicy, owner: string | undefined, decider: ApprovalDecider | undefined) => string | undefined;

package/dist/wirings/workflow/workflow-approval-policy.js

@@ -0,0 +1,48 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import { addError } from '../../errors/error-handler.js';
+export class WorkflowApprovalForbiddenError extends ForbiddenError {
+    payload;
+    constructor(reason, detail) {
+        super(detail);
+        this.payload = { reason, detail };
+    }
+}
+addError(WorkflowApprovalForbiddenError, {
+    status: 403,
+    message: 'Not authorized to answer this approval.',
+});
+export const approvalDeciderFrom = (session) => session ? { userId: session.userId, scopes: session.scopes } : undefined;
+/**
+ * Judge a decision against the gate's declared policy, returning the reason it
+ * is refused or `undefined` if it stands.
+ *
+ * Returns a message rather than throwing because the same judgement is needed
+ * in two places with different outcomes: refusing a live submission with a 403,
+ * and clearing an already-recorded decision on replay.
+ */
+export const approvalPolicyRefusal = (policy, owner, decider) => {
+    if (policy.approverScope &&
+        !decider?.scopes?.includes(policy.approverScope)) {
+        return `Answering this approval requires the '${policy.approverScope}' scope`;
+    }
+    switch (policy.approvers ?? 'any') {
+        case 'owner':
+            if (!owner) {
+                return undefined;
+            }
+            if (!decider?.userId || decider.userId !== owner) {
+                return 'Only the user who started this run may answer this approval';
+            }
+            return undefined;
+        case 'not-initiator':
+            if (!decider?.userId) {
+                return 'Answering this approval requires a signed-in user';
+            }
+            if (owner && decider.userId === owner) {
+                return 'The user who started this run may not answer this approval';
+            }
+            return undefined;
+        case 'any':
+            return undefined;
+    }
+};

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

@@ -0,0 +1,67 @@
+import type { ApprovalOutcome, StepState, WorkflowApprovalOptions } from './workflow.types.js';
+import type { ApprovalDecider } from './dsl/workflow-dsl.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;
+/**
+ * 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>;
+};
+/**
+ * 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 declare const recordApprovalDecision: (store: ApprovalStore, runId: string, reason: string, decision: unknown, decidedBy?: ApprovalDecider) => 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.
+ *
+ * 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 declare const evaluateApprovalStep: (store: ApprovalStore, runId: string, reason: string, approvalStepName: string, fromStepName: string | undefined, options: WorkflowApprovalOptions) => Promise<ApprovalOutcome<unknown>>;

package/dist/wirings/workflow/workflow-approval.js

@@ -0,0 +1,177 @@
+import { getDurationInMilliseconds } from '../../time-utils.js';
+import { WorkflowApprovalResolvedError, WorkflowSuspendedException, } from './workflow-errors.js';
+import { approvalPolicyRefusal, WorkflowApprovalForbiddenError, } from './workflow-approval-policy.js';
+/** The durable step name an approval point is recorded under. */
+export const approvalStepNameFor = (reason) => `__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) => {
+    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 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, runId, reason, decision, decidedBy) => {
+    const stepName = approvalStepNameFor(reason);
+    const stateKey = approvalStateKey(stepName);
+    let resolved;
+    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;
+        throw new WorkflowApprovalResolvedError(reason, outcome?.status ?? 'decided');
+    }
+    const state = await store.getRunState(runId);
+    const record = (state[stateKey] ?? {});
+    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,
+    });
+    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, runId, reason, approvalStepName, fromStepName, options) => {
+    const insert = () => store.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', {
+        reason,
+        expiry: options.expiry,
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+    }, undefined, fromStepName);
+    let 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;
+    }
+    const stateKey = approvalStateKey(approvalStepName);
+    let record = ((await store.getRunState(runId))[stateKey] ?? {});
+    const policy = {
+        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 }],
+            });
+            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 = {
+            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 = { status: 'expired' };
+        await store.setStepResult(stepState.stepId, outcome);
+        return outcome;
+    }
+    throw new WorkflowSuspendedException(runId, reason);
+};

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

@@ -0,0 +1,26 @@
+export declare const DEFAULT_STEP_RETRIES = 5;
+/** Statuses from which a run never advances again on its own. */
+export declare const WORKFLOW_END_STATES: ReadonlySet<string>;
+/** Statuses a run cannot leave at all. */
+export declare const WORKFLOW_TERMINAL_STATES: ReadonlySet<string>;
+export declare const WORKFLOW_POLL_MIN_MS = 10;
+export declare const WORKFLOW_POLL_FACTOR = 1.6;
+export declare const WORKFLOW_CHILD_POLL_MAX_MS = 500;
+/** Idle window before a `running` run with nothing in flight is treated as stalled. */
+export declare const DEFAULT_STALLED_RUN_MS: number;
+/** Runs re-driven per `recoverStalledRuns` call, so one sweep is bounded. */
+export declare 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 declare const DEFAULT_UNDISPATCHED_STEP_MS = 30000;
+/** Steps re-driven per `relayUndispatchedSteps` call, so one tick is bounded. */
+export declare const DEFAULT_UNDISPATCHED_STEP_LIMIT = 100;
+/** First wait before a step already re-dispatched once is re-dispatched again. */
+export declare const REDISPATCH_BACKOFF_MS = 30000;
+/** Ceiling on the doubling backoff, so a permanently stuck step still gets swept. */
+export declare const REDISPATCH_BACKOFF_MAX_MS: number;
+/** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
+export declare const REDISPATCH_BACKOFF_MAX_ENTRIES = 10000;

package/dist/wirings/workflow/workflow-constants.js

@@ -0,0 +1,35 @@
+export const DEFAULT_STEP_RETRIES = 5;
+/** Statuses from which a run never advances again on its own. */
+export const WORKFLOW_END_STATES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+    'suspended',
+]);
+/** Statuses a run cannot leave at all. */
+export const WORKFLOW_TERMINAL_STATES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+]);
+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/dist/wirings/workflow/workflow-errors.d.ts

@@ -0,0 +1,58 @@
+import { PikkuError } from '../../errors/error-handler.js';
+import type { ApprovalOutcome } from './workflow.types.js';
+/**
+ * Thrown to unwind a run that cannot continue on this tick. Not a failure:
+ * the run resumes from its recorded step state.
+ */
+export declare class WorkflowAsyncException extends Error {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string);
+}
+export declare class WorkflowCancelledException extends Error {
+    readonly runId: string;
+    readonly reason?: string | undefined;
+    constructor(runId: string, reason?: string | undefined);
+}
+export declare class WorkflowSuspendedException extends Error {
+    readonly runId: string;
+    readonly reason: string;
+    constructor(runId: string, reason: string);
+}
+export declare class WorkflowDispatchException extends Error {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class WorkflowNotFoundError extends PikkuError {
+    constructor(name: string);
+}
+export declare class WorkflowRunNotFoundError extends PikkuError {
+    constructor(runId: string);
+}
+export declare class WorkflowRunFailedError extends PikkuError {
+    payload: {
+        message?: string;
+    };
+    constructor(message?: string);
+}
+export declare class WorkflowRunCancelledError extends PikkuError {
+    constructor();
+}
+export declare class WorkflowApprovalResolvedError extends PikkuError {
+    payload: {
+        reason: string;
+        outcome: ApprovalOutcome<unknown>['status'];
+    };
+    constructor(reason: string, outcome: ApprovalOutcome<unknown>['status']);
+}
+export declare class WorkflowStepFunctionMismatchError extends PikkuError {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string);
+}
+export declare class WorkflowStepNameNotString extends Error {
+    constructor(stepName: unknown);
+}

package/dist/wirings/workflow/workflow-errors.js

@@ -0,0 +1,112 @@
+import { PikkuError, addError } from '../../errors/error-handler.js';
+/**
+ * Thrown to unwind a run that cannot continue on this tick. Not a failure:
+ * the run resumes from its recorded step state.
+ */
+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 WorkflowStepFunctionMismatchError extends PikkuError {
+    runId;
+    stepName;
+    constructor(runId, stepName) {
+        super(`Workflow step '${stepName}' (run ${runId}) was dispatched with a different function`);
+        this.runId = runId;
+        this.stepName = stepName;
+    }
+}
+addError(WorkflowStepFunctionMismatchError, {
+    status: 409,
+    message: 'Workflow step was dispatched with a different function.',
+});
+export class WorkflowStepNameNotString extends Error {
+    constructor(stepName) {
+        super(`Workflow step name must be a string. Received: ${typeof stepName}`);
+    }
+}

package/dist/wirings/workflow/workflow-meta-resolver.d.ts

@@ -0,0 +1,11 @@
+import type { WorkflowRuntimeMeta } from './workflow.types.js';
+export type ResolvedWorkflowMeta = {
+    meta: WorkflowRuntimeMeta;
+    packageName: string | null;
+    resolvedName: string;
+};
+/**
+ * Resolves a workflow name against the root registry, then — for a
+ * `namespace:name` form — against the addon package that claims the namespace.
+ */
+export declare const resolveWorkflowMeta: (name: string) => ResolvedWorkflowMeta | null;

package/dist/wirings/workflow/workflow-meta-resolver.js

@@ -0,0 +1,31 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Resolves a workflow name against the root registry, then — for a
+ * `namespace:name` form — against the addon package that claims the namespace.
+ */
+export 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) {
+        return null;
+    }
+    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) {
+        return null;
+    }
+    const addonMeta = pikkuState(pkgConfig.package, 'workflows', 'meta');
+    if (!addonMeta?.[localName]) {
+        return null;
+    }
+    return {
+        meta: addonMeta[localName],
+        packageName: pkgConfig.package,
+        resolvedName: localName,
+    };
+};

package/dist/wirings/workflow/workflow-queue-routing.d.ts

@@ -0,0 +1,8 @@
+import type { JobGroup, JobOptions } from '../queue/queue.types.js';
+import type { WorkflowServiceConfig, WorkflowStepOptions } from './workflow.types.js';
+export type WorkflowQueueStrategy = 'per-workflow' | 'shared-groups';
+export declare const resolveWorkflowConfig: () => WorkflowServiceConfig;
+export declare const orchestratorQueueName: (strategy: WorkflowQueueStrategy, workflowName?: string) => string;
+export declare const stepWorkerQueueName: (strategy: WorkflowQueueStrategy, rpcName?: string) => string;
+export declare const jobGroupFor: (strategy: WorkflowQueueStrategy, id?: string) => JobGroup | undefined;
+export declare const stepJobOptions: (stepOptions?: WorkflowStepOptions) => JobOptions;