@pikku/core 0.12.19 → 0.12.21

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { PikkuWorkflowWire, StepState, WorkflowPlannedStep, WorkflowRun, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { PikkuWorkflowWire, StepState, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 /**
@@ -35,6 +35,12 @@ export declare class WorkflowNotFoundError extends PikkuError {
 export declare class WorkflowRunNotFoundError extends PikkuError {
     constructor(runId: string);
 }
+export declare class WorkflowRunFailedError extends PikkuError {
+    payload: {
+        message?: string;
+    };
+    constructor(message?: string);
+}
 export declare class WorkflowServiceNotInitialized extends Error {
 }
 export declare class WorkflowStepNameNotString extends Error {
@@ -48,7 +54,19 @@ export declare class WorkflowStepNameNotString extends Error {
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private inlineRuns;
     protected get logger(): import("../../services/logger.js").Logger;
-    constructor();
+    protected mirror?: WorkflowRunMirror;
+    constructor(options?: {
+        wireQueues?: boolean;
+        mirror?: WorkflowRunMirror;
+    });
+    private safeMirror;
+    rewireQueueWorkers(): void;
+    /**
+     * Wire the queue-based orchestrator/step/sleeper workers.
+     * Subclasses that orchestrate without queues (e.g. Durable Objects) should
+     * pass `wireQueues: false` to the base constructor and skip this entirely.
+     */
+    protected wireQueueWorkers(): void;
     /**
      * Check if a run is executing inline (without queues)
      */
@@ -62,7 +80,11 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     unregisterInlineRun(runId: string): void;
     registerWorkflowVersions(): Promise<void>;
-    abstract createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
+    createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
+        deterministic?: boolean;
+        plannedSteps?: WorkflowPlannedStep[];
+    }): Promise<string>;
+    protected abstract createRunImpl(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
         plannedSteps?: WorkflowPlannedStep[];
     }): Promise<string>;
@@ -90,7 +112,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @param id - Run ID
      * @param status - New status
      */
-    abstract updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    protected abstract updateRunStatusImpl(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
     /**
      * Insert initial step state (called by orchestrator)
      * Creates pending step in both workflow_step and workflow_step_history
@@ -101,7 +124,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
      */
-    abstract insertStepState(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions): Promise<StepState>;
+    insertStepState(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions): Promise<StepState>;
+    protected abstract insertStepStateImpl(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions): Promise<StepState>;
     /**
      * Get step state by cache key (read-only)
      * @param runId - Run ID
@@ -114,33 +138,38 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * Updates both workflow_step and workflow_step_history
      * @param stepId - Step ID
      */
-    abstract setStepRunning(stepId: string): Promise<void>;
+    setStepRunning(stepId: string): Promise<void>;
+    protected abstract setStepRunningImpl(stepId: string): Promise<void>;
     /**
      * Mark step as scheduled (queued for execution)
      * Updates both workflow_step and workflow_step_history
      * @param stepId - Step ID
      */
-    abstract setStepScheduled(stepId: string): Promise<void>;
+    setStepScheduled(stepId: string): Promise<void>;
+    protected abstract setStepScheduledImpl(stepId: string): Promise<void>;
     /**
      * Store step result and mark as succeeded
      * Updates both workflow_step and workflow_step_history
      * @param stepId - Step ID
      * @param result - Step result
      */
-    abstract setStepResult(stepId: string, result: any): Promise<void>;
+    setStepResult(stepId: string, result: any): Promise<void>;
+    protected abstract setStepResultImpl(stepId: string, result: any): Promise<void>;
     /**
      * Set the child workflow run ID on a step
      * @param stepId - Step ID
      * @param childRunId - Child workflow run ID
      */
-    abstract setStepChildRunId(stepId: string, childRunId: string): Promise<void>;
+    setStepChildRunId(stepId: string, childRunId: string): Promise<void>;
+    protected abstract setStepChildRunIdImpl(stepId: string, childRunId: string): Promise<void>;
     /**
      * Store step error and mark as failed
      * Updates both workflow_step and workflow_step_history
      * @param stepId - Step ID
      * @param error - Error object
      */
-    abstract setStepError(stepId: string, error: Error): Promise<void>;
+    setStepError(stepId: string, error: Error): Promise<void>;
+    protected abstract setStepErrorImpl(stepId: string, error: Error): Promise<void>;
     /**
      * Create a new retry attempt for a failed step
      * Inserts new pending step in both workflow_step and workflow_step_history
@@ -149,7 +178,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @param failedStepId - Failed step ID to copy from
      * @returns New step state for the retry attempt
      */
-    abstract createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    protected abstract createRetryAttemptImpl(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
     /**
      * Execute function within a run lock to prevent concurrent modifications
      * @param id - Run ID
@@ -198,22 +228,26 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @param stepId - Step ID
      * @param branchKey - Branch key selected by graph.branch()
      */
-    abstract setBranchTaken(stepId: string, branchKey: string): Promise<void>;
+    setBranchTaken(stepId: string, branchKey: string): Promise<void>;
+    protected abstract setBranchTakenImpl(stepId: string, branchKey: string): Promise<void>;
     /**
      * Update a state variable in the workflow run's state
      * @param runId - Run ID
      * @param name - Variable name
      * @param value - Value to store
      */
-    abstract updateRunState(runId: string, name: string, value: unknown): Promise<void>;
+    updateRunState(runId: string, name: string, value: unknown): Promise<void>;
+    protected abstract updateRunStateImpl(runId: string, name: string, value: unknown): Promise<void>;
     /**
      * Get the entire state object for a workflow run
      * @param runId - Run ID
      * @returns The state object with all variables
      */
     abstract getRunState(runId: string): Promise<Record<string, unknown>>;
-    abstract upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
-    abstract updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
+    upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
+    protected abstract upsertWorkflowVersionImpl(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
+    updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
+    protected abstract updateWorkflowVersionStatusImpl(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
     abstract getWorkflowVersion(name: string, graphHash: string): Promise<{
         graph: any;
         source: string;
@@ -228,7 +262,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @param runId - Run ID
      */
     resumeWorkflow(runId: string, workflowName?: string): Promise<void>;
-    queueStepWorker(runId: string, stepName: string, rpcName: string, data: any): Promise<void>;
+    queueStepWorker(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: WorkflowStepOptions): Promise<void>;
     /**
      * Execute a workflow sleep step completion
      * Sets the step result to null and resumes the workflow
@@ -241,6 +275,32 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @param retryDelay - Delay in milliseconds or duration string (optional)
      */
     protected scheduleOrchestratorRetry(runId: string, retryDelay?: number | string, workflowName?: string): Promise<void>;
+    /**
+     * Dispatch a workflow step to be executed asynchronously.
+     *
+     * Default implementation enqueues a step worker job via the queue service.
+     * Subclasses with non-queue transports (e.g. Durable Objects) override this
+     * to dispatch via their own mechanism (RPC to a step worker, etc.).
+     *
+     * On return, the workflow is paused via `WorkflowAsyncException` thrown by
+     * the caller; the step transport is responsible for calling back into the
+     * orchestrator (via `resumeWorkflow` or equivalent) when the step completes.
+     *
+     * @returns true if dispatch was async (caller should pause), false to fall
+     *   through to the inline execution path.
+     */
+    protected dispatchStep(runId: string, stepName: string, rpcName: string, data: unknown, stepOptions?: WorkflowStepOptions): Promise<boolean>;
+    /**
+     * Schedule a workflow sleep wakeup at the given duration.
+     *
+     * Default implementation uses the scheduler service to enqueue a delayed
+     * sleeper RPC. Subclasses with native timer primitives (e.g. Durable Object
+     * alarms) override this to schedule directly without going through queues.
+     *
+     * @returns true if the wakeup was scheduled remotely (caller should pause),
+     *   false to fall through to inline `setTimeout` behavior.
+     */
+    protected scheduleSleep(runId: string, stepId: string, duration: number | string): Promise<boolean>;
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -284,6 +344,11 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * Get the orchestrator queue name for a specific workflow.
      * Checks queue meta for a per-workflow queue first (e.g. wf-orchestrator-{name}),
      * falls back to the shared orchestrator queue.
+     *
+     * Reads from `queue.meta` (always populated globally) rather than
+     * `queue.registrations` (only populated for queues this unit consumes).
+     * In a per-unit deploy the orchestrator unit doesn't consume per-step
+     * queues — but it produces to them — so registrations would miss them.
      */
     protected getOrchestratorQueueName(workflowName?: string): string;
     protected getStepWorkerQueueName(rpcName?: string): string;

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

@@ -92,6 +92,17 @@ 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 WorkflowServiceNotInitialized extends Error {
 }
 export class WorkflowStepNameNotString extends Error {
@@ -115,7 +126,38 @@ export class PikkuWorkflowService {
     get logger() {
         return getSingletonServices()?.logger;
     }
-    constructor() {
+    mirror;
+    constructor(options = {}) {
+        const wireQueues = options.wireQueues ?? true;
+        this.mirror = options.mirror;
+        if (wireQueues) {
+            this.wireQueueWorkers();
+        }
+    }
+    async safeMirror(fn) {
+        if (!this.mirror)
+            return;
+        try {
+            await fn();
+        }
+        catch (err) {
+            try {
+                this.logger?.warn?.(`[pikku] WorkflowRunMirror write failed: ${err?.message ?? err}`);
+            }
+            catch {
+                // logger unavailable (e.g. singleton services not initialized) — swallow
+            }
+        }
+    }
+    rewireQueueWorkers() {
+        this.wireQueueWorkers();
+    }
+    /**
+     * Wire the queue-based orchestrator/step/sleeper workers.
+     * Subclasses that orchestrate without queues (e.g. Durable Objects) should
+     * pass `wireQueues: false` to the base constructor and skip this entirely.
+     */
+    wireQueueWorkers() {
         const functions = pikkuState(null, 'function', 'functions');
         const functionsMeta = pikkuState(null, 'function', 'meta');
         // Minimal meta for internal workflow functions (satisfies FunctionMeta)
@@ -170,6 +212,9 @@ export class PikkuWorkflowService {
                 func: pikkuWorkflowSleeperFunc,
             });
         }
+        if (!functionsMeta.pikkuWorkflowSleeper) {
+            functionsMeta.pikkuWorkflowSleeper = mkMeta('pikkuWorkflowSleeper');
+        }
     }
     /**
      * Check if a run is executing inline (without queues)
@@ -197,6 +242,11 @@ export class PikkuWorkflowService {
             await this.upsertWorkflowVersion(name, meta.graphHash, meta, meta.source);
         }
     }
+    async createRun(workflowName, input, inline, graphHash, wire, options) {
+        const runId = await this.createRunImpl(workflowName, input, inline, graphHash, wire, options);
+        await this.safeMirror(() => this.mirror.createRun(runId, workflowName, input, inline, graphHash, wire, options));
+        return runId;
+    }
     /**
      * Get minimal workflow run status with step summaries.
      * Used by the public API — the console addon provides the full verbose view.
@@ -240,6 +290,126 @@ export class PikkuWorkflowService {
                 : undefined,
         };
     }
+    /**
+     * Update workflow run status
+     * @param id - Run ID
+     * @param status - New status
+     */
+    async updateRunStatus(id, status, output, error) {
+        await this.updateRunStatusImpl(id, status, output, error);
+        await this.safeMirror(() => this.mirror.updateRunStatus(id, status, output, error));
+    }
+    /**
+     * Insert initial step state (called by orchestrator)
+     * Creates pending step in both workflow_step and workflow_step_history
+     * @param runId - Run ID
+     * @param stepName - Step cache key
+     * @param rpcName - RPC function name
+     * @param data - Step input data
+     * @param stepOptions - Step options (retries, retryDelay)
+     * @returns Step state with generated stepId
+     */
+    async insertStepState(runId, stepName, rpcName, data, stepOptions) {
+        const step = await this.insertStepStateImpl(runId, stepName, rpcName, data, stepOptions);
+        await this.safeMirror(() => this.mirror.insertStepState(runId, { ...step, stepName, rpcName, data }));
+        return step;
+    }
+    /**
+     * Mark step as running
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     */
+    async setStepRunning(stepId) {
+        await this.setStepRunningImpl(stepId);
+        await this.safeMirror(() => this.mirror.setStepRunning(stepId));
+    }
+    /**
+     * Mark step as scheduled (queued for execution)
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     */
+    async setStepScheduled(stepId) {
+        await this.setStepScheduledImpl(stepId);
+        await this.safeMirror(() => this.mirror.setStepScheduled(stepId));
+    }
+    /**
+     * Store step result and mark as succeeded
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     * @param result - Step result
+     */
+    async setStepResult(stepId, result) {
+        await this.setStepResultImpl(stepId, result);
+        await this.safeMirror(() => this.mirror.setStepResult(stepId, result));
+    }
+    /**
+     * Set the child workflow run ID on a step
+     * @param stepId - Step ID
+     * @param childRunId - Child workflow run ID
+     */
+    async setStepChildRunId(stepId, childRunId) {
+        await this.setStepChildRunIdImpl(stepId, childRunId);
+        await this.safeMirror(() => this.mirror.setStepChildRunId(stepId, childRunId));
+    }
+    /**
+     * Store step error and mark as failed
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     * @param error - Error object
+     */
+    async setStepError(stepId, error) {
+        await this.setStepErrorImpl(stepId, error);
+        const serialized = {
+            message: error.message,
+            stack: error.stack,
+            code: error.code,
+        };
+        await this.safeMirror(() => this.mirror.setStepError(stepId, serialized));
+    }
+    /**
+     * Create a new retry attempt for a failed step
+     * Inserts new pending step in both workflow_step and workflow_step_history
+     * Resets status to 'pending' with new stepId
+     * Copies metadata (rpcName, data, retries, retryDelay) from failed attempt
+     * @param failedStepId - Failed step ID to copy from
+     * @returns New step state for the retry attempt
+     */
+    async createRetryAttempt(failedStepId, status) {
+        const newStep = await this.createRetryAttemptImpl(failedStepId, status);
+        const stepName = newStep.stepName ?? '';
+        await this.safeMirror(() => this.mirror.createRetryAttempt(failedStepId, {
+            ...newStep,
+            stepName,
+        }));
+        return newStep;
+    }
+    /**
+     * Set the branch key for a graph node step
+     * @param stepId - Step ID
+     * @param branchKey - Branch key selected by graph.branch()
+     */
+    async setBranchTaken(stepId, branchKey) {
+        await this.setBranchTakenImpl(stepId, branchKey);
+        await this.safeMirror(() => this.mirror.setBranchTaken(stepId, branchKey));
+    }
+    /**
+     * Update a state variable in the workflow run's state
+     * @param runId - Run ID
+     * @param name - Variable name
+     * @param value - Value to store
+     */
+    async updateRunState(runId, name, value) {
+        await this.updateRunStateImpl(runId, name, value);
+        await this.safeMirror(() => this.mirror.updateRunState(runId, name, value));
+    }
+    async upsertWorkflowVersion(name, graphHash, graph, source, status) {
+        await this.upsertWorkflowVersionImpl(name, graphHash, graph, source, status);
+        await this.safeMirror(() => this.mirror.upsertWorkflowVersion(name, graphHash, graph, source, status));
+    }
+    async updateWorkflowVersionStatus(name, graphHash, status) {
+        await this.updateWorkflowVersionStatusImpl(name, graphHash, status);
+        await this.safeMirror(() => this.mirror.updateWorkflowVersionStatus(name, graphHash, status));
+    }
     // ============================================================================
     // Workflow Lifecycle Methods
     // ============================================================================
@@ -257,14 +427,25 @@ export class PikkuWorkflowService {
             runId,
         });
     }
-    async queueStepWorker(runId, stepName, rpcName, data) {
+    async queueStepWorker(runId, stepName, rpcName, data, stepOptions) {
         const queueService = this.verifyQueueService();
+        const retries = stepOptions?.retries ?? 0;
+        const retryDelay = stepOptions?.retryDelay;
         await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({
             runId,
             stepName,
             rpcName,
             data,
-        })));
+        })), retries > 0 || retryDelay
+            ? {
+                attempts: retries + 1,
+                backoff: typeof retryDelay === 'number'
+                    ? { type: 'fixed', delay: retryDelay }
+                    : retryDelay === 'exponential'
+                        ? 'exponential'
+                        : undefined,
+            }
+            : undefined);
     }
     /**
      * Execute a workflow sleep step completion
@@ -288,6 +469,58 @@ export class PikkuWorkflowService {
         }
         await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, retryDelay ? { delay: getDurationInMilliseconds(retryDelay) } : undefined);
     }
+    /**
+     * Dispatch a workflow step to be executed asynchronously.
+     *
+     * Default implementation enqueues a step worker job via the queue service.
+     * Subclasses with non-queue transports (e.g. Durable Objects) override this
+     * to dispatch via their own mechanism (RPC to a step worker, etc.).
+     *
+     * On return, the workflow is paused via `WorkflowAsyncException` thrown by
+     * the caller; the step transport is responsible for calling back into the
+     * orchestrator (via `resumeWorkflow` or equivalent) when the step completes.
+     *
+     * @returns true if dispatch was async (caller should pause), false to fall
+     *   through to the inline execution path.
+     */
+    async dispatchStep(runId, stepName, rpcName, data, stepOptions) {
+        if (this.isInline(runId) || !getSingletonServices()?.queueService) {
+            return false;
+        }
+        const retries = stepOptions?.retries ?? 0;
+        const retryDelay = stepOptions?.retryDelay;
+        await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({
+            runId,
+            stepName,
+            rpcName,
+            data,
+        })), {
+            attempts: retries + 1,
+            backoff: typeof retryDelay === 'number'
+                ? { type: 'fixed', delay: retryDelay }
+                : retryDelay === 'exponential'
+                    ? 'exponential'
+                    : undefined,
+        });
+        return true;
+    }
+    /**
+     * Schedule a workflow sleep wakeup at the given duration.
+     *
+     * Default implementation uses the scheduler service to enqueue a delayed
+     * sleeper RPC. Subclasses with native timer primitives (e.g. Durable Object
+     * alarms) override this to schedule directly without going through queues.
+     *
+     * @returns true if the wakeup was scheduled remotely (caller should pause),
+     *   false to fall through to inline `setTimeout` behavior.
+     */
+    async scheduleSleep(runId, stepId, duration) {
+        if (this.isInline(runId) || !getSingletonServices()?.schedulerService) {
+            return false;
+        }
+        await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, { runId, stepId });
+        return true;
+    }
     /**
      * Start a new workflow run
      * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
@@ -341,7 +574,13 @@ export class PikkuWorkflowService {
                 if (error.name !== 'WorkflowAsyncException' &&
                     error.name !== 'WorkflowCancelledException' &&
                     error.name !== 'WorkflowSuspendedException') {
+                    await this.updateRunStatus(runId, 'failed', undefined, {
+                        name: error.name,
+                        message: error.message,
+                        stack: error.stack,
+                    });
                     getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, error);
+                    throw error;
                 }
             }
             finally {
@@ -363,7 +602,7 @@ export class PikkuWorkflowService {
             }
             if (WORKFLOW_END_STATES.has(run.status)) {
                 if (run.status === 'failed') {
-                    throw new Error(run.error?.message || 'Workflow failed');
+                    throw new WorkflowRunFailedError(run.error?.message);
                 }
                 if (run.status === 'cancelled') {
                     throw new Error('Workflow was cancelled');
@@ -677,31 +916,14 @@ export class PikkuWorkflowService {
         }
         // Step is pending - schedule it
         await this.setStepScheduled(stepState.stepId);
-        // Enqueue step worker (unless inline mode)
-        if (!this.isInline(runId) && getSingletonServices().queueService) {
-            // Map step retry options to queue job options
-            const retries = stepOptions?.retries ?? 0;
-            const retryDelay = stepOptions?.retryDelay;
-            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({
-                runId,
-                stepName,
-                rpcName,
-                data,
-            })), {
-                // attempts includes initial attempt, retries doesn't
-                attempts: retries + 1,
-                // Map retry delay to backoff
-                backoff: typeof retryDelay === 'number'
-                    ? { type: 'fixed', delay: retryDelay }
-                    : retryDelay === 'exponential'
-                        ? 'exponential'
-                        : undefined,
-            });
-            // Pause workflow - step will callback when done
+        // Hand off to subclass-overridable transport. Default behavior enqueues
+        // via the queue service; DO-style subclasses RPC to a step worker.
+        const dispatched = await this.dispatchStep(runId, stepName, rpcName, data, stepOptions);
+        if (dispatched) {
             throw new WorkflowAsyncException(runId, stepName);
         }
-        else {
-            // Inline or no queue service - execute locally with retry loop
+        {
+            // Inline (no transport available) - execute locally with retry loop
             const retries = stepOptions?.retries ?? 0;
             const retryDelay = stepOptions?.retryDelay;
             let currentStepState = stepState;
@@ -873,22 +1095,16 @@ export class PikkuWorkflowService {
         }
         // Step is pending - schedule it
         await this.setStepScheduled(stepState.stepId);
-        // Check if inline mode or no scheduler service
-        if (!this.isInline(runId) && getSingletonServices().schedulerService) {
-            // Remote mode - schedule sleep via scheduler service
-            await getSingletonServices().schedulerService.scheduleRPC(duration, this.getConfig().sleeperRPCName, {
-                runId,
-                stepId: stepState.stepId,
-            });
-            // Pause workflow - sleep will callback when done
+        // Hand off to subclass-overridable transport. Default behavior schedules
+        // a delayed sleeper RPC via the scheduler service; DO-style subclasses
+        // override to use native timer primitives (e.g. setAlarm).
+        const scheduled = await this.scheduleSleep(runId, stepState.stepId, duration);
+        if (scheduled) {
             throw new WorkflowAsyncException(runId, stepName);
         }
-        else {
-            // Inline mode - use setTimeout with actual duration
-            await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(duration)));
-            await this.setStepResult(stepState.stepId, null);
-            return;
-        }
+        // Inline mode - use setTimeout with actual duration
+        await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(duration)));
+        await this.setStepResult(stepState.stepId, null);
     }
     getSuspendStepName(reason) {
         if (!reason) {
@@ -975,12 +1191,17 @@ export class PikkuWorkflowService {
      * Get the orchestrator queue name for a specific workflow.
      * Checks queue meta for a per-workflow queue first (e.g. wf-orchestrator-{name}),
      * falls back to the shared orchestrator queue.
+     *
+     * Reads from `queue.meta` (always populated globally) rather than
+     * `queue.registrations` (only populated for queues this unit consumes).
+     * In a per-unit deploy the orchestrator unit doesn't consume per-step
+     * queues — but it produces to them — so registrations would miss them.
      */
     getOrchestratorQueueName(workflowName) {
         if (workflowName) {
             const perWorkflow = `wf-orchestrator-${toKebab(workflowName)}`;
-            const registrations = pikkuState(null, 'queue', 'registrations');
-            if (registrations.has(perWorkflow)) {
+            const meta = pikkuState(null, 'queue', 'meta');
+            if (meta[perWorkflow]) {
                 return perWorkflow;
             }
         }
@@ -989,8 +1210,8 @@ export class PikkuWorkflowService {
     getStepWorkerQueueName(rpcName) {
         if (rpcName) {
             const perStep = `wf-step-${toKebab(rpcName)}`;
-            const registrations = pikkuState(null, 'queue', 'registrations');
-            if (registrations.has(perStep)) {
+            const meta = pikkuState(null, 'queue', 'meta');
+            if (meta[perStep]) {
                 return perStep;
             }
         }

package/dist/wirings/workflow/workflow.types.d.ts

@@ -143,6 +143,40 @@ export interface WorkflowRunService {
     }>>;
     deleteRun(id: string): Promise<boolean>;
 }
+/**
+ * Write-only companion to `WorkflowRunService`. An executor (a
+ * `PikkuWorkflowService` subclass) can be given a mirror; every write
+ * the executor makes to its own canonical store is then forwarded here,
+ * so an external read store (e.g. a DB queried by the console UI) stays
+ * in sync with DO/Redis/etc-driven runs.
+ *
+ * Mirror failures are logged but never fail the workflow — the mirror is
+ * an index, not the source of truth.
+ */
+export interface WorkflowRunMirror {
+    createRun(runId: string, workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
+        deterministic?: boolean;
+        plannedSteps?: WorkflowPlannedStep[];
+    }): Promise<void>;
+    updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    insertStepState(runId: string, step: StepState & {
+        stepName: string;
+        rpcName: string | null;
+        data: any;
+    }): Promise<void>;
+    setStepRunning(stepId: string): Promise<void>;
+    setStepScheduled(stepId: string): Promise<void>;
+    setStepResult(stepId: string, result: any): Promise<void>;
+    setStepChildRunId(stepId: string, childRunId: string): Promise<void>;
+    setStepError(stepId: string, error: SerializedError): Promise<void>;
+    createRetryAttempt(failedStepId: string, newStep: StepState & {
+        stepName: string;
+    }): Promise<void>;
+    setBranchTaken(stepId: string, branchKey: string): Promise<void>;
+    updateRunState(runId: string, name: string, value: unknown): Promise<void>;
+    upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
+    updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
+}
 /**
  * Core workflow definition
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.19",
+  "version": "0.12.21",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",