@pikku/core 0.12.20 → 0.12.22

package/dist/wirings/cli/command-parser.js

@@ -2,6 +2,12 @@
 function toCamelCase(str) {
     return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
+/** Convert camelCase to kebab-case for display: "autoApply" → "auto-apply".
+ *  Flags are stored camelCase (matching the function input field) but shown
+ *  kebab; the parser accepts both forms via toCamelCase. */
+function toKebabCase(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
 /**
  * Parses raw CLI arguments into structured data for a specific program
  */
@@ -77,6 +83,15 @@ export function parseCLIArguments(args, programName, allMeta) {
         }
         return result;
     }
+    // A group/parent command — has subcommands but no runnable function of its
+    // own — cannot be executed directly. Surface a routable error so the runner
+    // shows its subcommand help instead of attempting to run a missing function.
+    if (!commandMeta.pikkuFuncId &&
+        commandMeta.subcommands &&
+        Object.keys(commandMeta.subcommands).length > 0) {
+        result.errors.push(`Missing subcommand: ${result.commandPath.join(' ')}`);
+        return result;
+    }
     // Collect all available options (global + inherited)
     const availableOptions = collectAvailableOptions(meta, result.commandPath);
     // Parse remaining arguments as positionals and options
@@ -289,7 +304,7 @@ function applyOptionDefaults(optionDefs, options, result) {
         }
         // Check required
         if (def.required && !(name in options)) {
-            result.errors.push(`Missing required option: --${name}`);
+            result.errors.push(`Missing required option: --${toKebabCase(name)}`);
         }
         // Validate choices
         if (def.choices && name in options) {
@@ -297,12 +312,12 @@ function applyOptionDefaults(optionDefs, options, result) {
             if (Array.isArray(value)) {
                 for (const v of value) {
                     if (!def.choices.includes(v)) {
-                        result.errors.push(`Invalid value for --${name}: ${v}. Valid choices: ${def.choices.join(', ')}`);
+                        result.errors.push(`Invalid value for --${toKebabCase(name)}: ${v}. Valid choices: ${def.choices.join(', ')}`);
                     }
                 }
             }
             else if (!def.choices.includes(value)) {
-                result.errors.push(`Invalid value for --${name}: ${value}. Valid choices: ${def.choices.join(', ')}`);
+                result.errors.push(`Invalid value for --${toKebabCase(name)}: ${value}. Valid choices: ${def.choices.join(', ')}`);
             }
         }
     }
@@ -390,7 +405,7 @@ function formatOptions(options, lines) {
         else {
             line += '    ';
         }
-        line += `--${name}`;
+        line += `--${toKebabCase(name)}`;
         if (opt.default !== undefined && typeof opt.default !== 'boolean') {
             line += ` <value>`;
         }

package/dist/wirings/http/http-runner.js

@@ -239,8 +239,10 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         response.setMode('stream');
         response.header('Content-Type', 'text/event-stream');
         response.header('Cache-Control', 'no-cache');
+        let sseState;
+        const channelId = createWeakUID();
         channel = {
-            channelId: requestId,
+            channelId,
             openingData: await data(),
             send: (data) => {
                 response.arrayBuffer(isSerializable(data) ? JSON.stringify(data) : data);
@@ -253,7 +255,36 @@ const executeRoute = async (services, matchedRoute, http, options) => {
                 response.close?.();
             },
             state: 'open',
+            setState: (s) => {
+                sseState = s;
+            },
+            getState: () => sseState,
+            clearState: () => {
+                sseState = undefined;
+            },
         };
+        // Register the SSE channel with the eventHub (if present) so that
+        // eventHub.publish() can deliver messages to SSE subscribers.
+        // The channel handler wraps the SSE channel to match PikkuChannelHandler.
+        if (singletonServices.eventHub?.onChannelOpened) {
+            const channelRef = channel;
+            const channelHandler = {
+                getChannel: () => channelRef,
+                send: (data, isBinary) => {
+                    if (isBinary)
+                        channelRef.sendBinary(data);
+                    else
+                        channelRef.send(data);
+                },
+                sendBinary: (data) => channelRef.sendBinary(data),
+            };
+            singletonServices.eventHub.onChannelOpened(channelHandler);
+            const originalClose = channel.close;
+            channel.close = () => {
+                singletonServices.eventHub.onChannelClosed(channelId);
+                originalClose();
+            };
+        }
     }
     const wire = {
         traceId: requestId,
@@ -264,22 +295,45 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         getSession: () => userSession.get(),
         hasSessionChanged: () => userSession.sessionChanged,
     };
-    result = await runPikkuFunc('http', `${meta.method}:${meta.route}`, meta.pikkuFuncId, {
-        singletonServices,
-        createWireServices,
-        auth: route.auth !== false,
-        data,
-        inheritedMiddleware: meta.middleware,
-        wireMiddleware: route.middleware,
-        inheritedPermissions: meta.permissions,
-        wirePermissions: route.permissions,
-        coerceDataFromSchema: options.coerceDataFromSchema,
-        tags: route.tags,
-        wire,
-        sessionService: userSession,
-        packageName: meta.packageName,
-    });
-    if (!matchedRoute.route.sse) {
+    try {
+        result = await runPikkuFunc('http', `${meta.method}:${meta.route}`, meta.pikkuFuncId, {
+            singletonServices,
+            createWireServices,
+            auth: route.auth !== false,
+            data,
+            inheritedMiddleware: meta.middleware,
+            wireMiddleware: route.middleware,
+            inheritedPermissions: meta.permissions,
+            wirePermissions: route.permissions,
+            coerceDataFromSchema: options.coerceDataFromSchema,
+            tags: route.tags,
+            wire,
+            sessionService: userSession,
+            packageName: meta.packageName,
+        });
+    }
+    catch (e) {
+        if (matchedRoute.route.sse) {
+            singletonServices.logger.error(e instanceof Error ? e.message : e);
+            try {
+                const errorResponse = getErrorResponse(e);
+                http?.response?.arrayBuffer(JSON.stringify({
+                    type: 'error',
+                    errorText: errorResponse?.message ?? 'Internal server error',
+                }));
+                http?.response?.arrayBuffer(JSON.stringify({ type: 'done' }));
+            }
+            catch { }
+            channel?.close();
+            return wireServices ? { result, wireServices } : { result };
+        }
+        throw e;
+    }
+    if (matchedRoute.route.sse) {
+        // Flush headers after middleware has run so CORS/auth headers are included
+        http?.response?.flushHeaders?.();
+    }
+    else {
         if (result instanceof Response) {
             await applyWebResponse(http.response, result);
         }
@@ -405,25 +459,7 @@ export const fetchData = async (request, response, { skipUserSession = false, re
         return result;
     }
     catch (e) {
-        if (matchedRoute?.route.sse) {
-            // For SSE routes, send error through the stream since the response is already in stream mode
-            scopedLogger.error(e instanceof Error ? e.message : e);
-            try {
-                const errorResponse = getErrorResponse(e);
-                response.arrayBuffer(JSON.stringify({
-                    type: 'error',
-                    errorText: errorResponse?.message ?? 'Internal server error',
-                }));
-                response.arrayBuffer(JSON.stringify({ type: 'done' }));
-            }
-            catch (streamErr) {
-                scopedLogger.error(`SSE error while sending error payload: ${streamErr instanceof Error ? streamErr.message : String(streamErr)}`);
-            }
-            response.close?.();
-        }
-        else {
-            handleHTTPError(e, http, requestId, scopedLogger, logWarningsForStatusCodes, respondWith404, bubbleErrors, exposeErrors);
-        }
+        handleHTTPError(e, http, requestId, scopedLogger, logWarningsForStatusCodes, respondWith404, bubbleErrors, exposeErrors);
     }
     finally {
         // Clean up any session-specific services created during processing

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

@@ -177,6 +177,7 @@ export interface PikkuHTTPResponse<Out = unknown> {
     redirect(location: string, status?: number): this;
     close?: () => void;
     setMode?: (mode: 'stream') => void;
+    flushHeaders?: () => void;
 }
 /**
  * Single route configuration - supports all wireHTTP options

package/dist/wirings/http/pikku-fetch-http-request.js

@@ -89,7 +89,9 @@ export class PikkuFetchHTTPRequest {
         const merged = {};
         for (const part of parts) {
             for (const [key, value] of Object.entries(part)) {
-                if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+                if (key === '__proto__' ||
+                    key === 'constructor' ||
+                    key === 'prototype') {
                     continue;
                 }
                 if (key in merged && !valuesAreEquivalent(merged[key], value)) {

package/dist/wirings/http/web-request.js

@@ -57,17 +57,46 @@ export function toWebRequest(req, baseUrl) {
     });
 }
 const SKIP_RESPONSE_HEADERS = new Set(['content-length', 'transfer-encoding']);
+function collectSetCookieHeaders(webResponse) {
+    const seen = new Set();
+    const values = [];
+    const add = (cookie) => {
+        if (!cookie || seen.has(cookie)) {
+            return;
+        }
+        seen.add(cookie);
+        values.push(cookie);
+    };
+    const headersWithGetSetCookie = webResponse.headers;
+    if (typeof headersWithGetSetCookie.getSetCookie === 'function') {
+        for (const cookie of headersWithGetSetCookie.getSetCookie()) {
+            add(cookie);
+        }
+    }
+    else {
+        webResponse.headers.forEach((value, name) => {
+            if (name.toLowerCase() === 'set-cookie') {
+                add(value);
+            }
+        });
+    }
+    return values;
+}
 /**
  * Applies a Web API Response to a PikkuHTTPResponse.
  * Copies status, headers (including Set-Cookie), redirects, and body.
  */
 export async function applyWebResponse(res, webResponse) {
     res.status(webResponse.status);
+    const setCookieValues = collectSetCookieHeaders(webResponse);
     webResponse.headers.forEach((value, name) => {
         const lower = name.toLowerCase();
         if (SKIP_RESPONSE_HEADERS.has(lower)) {
             return;
         }
+        if (lower === 'set-cookie') {
+            return;
+        }
         if (lower === 'location') {
             res.redirect(value, webResponse.status);
         }
@@ -75,6 +104,9 @@ export async function applyWebResponse(res, webResponse) {
             res.header(name, value);
         }
     });
+    if (setCookieValues.length > 0) {
+        res.header('Set-Cookie', setCookieValues);
+    }
     const body = await webResponse.text();
     if (body) {
         if (res.send) {

package/dist/wirings/rpc/rpc-runner.js

@@ -1,6 +1,5 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { pikkuState } from '../../pikku-state.js';
-import { ForbiddenError } from '../../errors/errors.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
 export class RPCNotFoundError extends PikkuError {
@@ -63,6 +62,16 @@ const resolvePikkuFunction = (rpcName, packageName = null) => {
             rpcMeta = rpc[baseName];
         }
     }
+    if (!rpcMeta) {
+        const rootFunctions = pikkuState(null, 'function', 'meta');
+        const rootFunctionMeta = rootFunctions?.[rpcName];
+        if (rootFunctionMeta) {
+            return {
+                pikkuFuncId: rootFunctionMeta.pikkuFuncId || rpcName,
+                packageName: null,
+            };
+        }
+    }
     if (!rpcMeta) {
         throw new RPCNotFoundError(rpcName);
     }
@@ -89,13 +98,14 @@ export class ContextAwareRPCService {
             }
         }
         else {
-            functionMeta = pikkuState(null, 'function', 'meta')[funcName];
+            const resolved = resolvePikkuFunction(funcName, this.packageName);
+            functionMeta = pikkuState(resolved.packageName, 'function', 'meta')[resolved.pikkuFuncId];
         }
         if (!functionMeta) {
             throw new RPCNotFoundError(funcName);
         }
         if (!functionMeta.expose) {
-            throw new ForbiddenError();
+            throw new RPCNotFoundError(funcName);
         }
         return await this.rpc(funcName, data);
     }

package/dist/wirings/workflow/graph/graph-node.d.ts

@@ -26,6 +26,10 @@ export interface GraphNodeDef<RPCMap extends Record<string, RPCHandler>, NodeIds
     next?: NextConfig<NodeIds>;
     /** Error handling - node(s) to execute on error */
     onError?: NodeIds | NodeIds[];
+    /** Maximum retry attempts allowed (excludes the initial attempt) */
+    retries?: number;
+    /** Delay between retries — milliseconds, duration string, or 'exponential' */
+    retryDelay?: string | number;
 }
 /**
  * Helper to create a type-safe graph definition with RPC autocomplete.
@@ -87,6 +91,8 @@ type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends R
         next?: NextConfig<Extract<keyof FuncMap, string>>;
         input?: (ref: <N extends Extract<keyof FuncMap, string>, P extends keyof ComputeNodeOutputs<FuncMap, RPCMap>[N] & string>(nodeId: N, path: P) => TypedRef<ComputeNodeOutputs<FuncMap, RPCMap>[N][P]>) => InputWithRefs<ComputeNodeInputs<FuncMap, RPCMap>[K]>;
         onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[];
+        retries?: number;
+        retryDelay?: string | number;
     };
 };
 /**
@@ -113,5 +119,7 @@ export declare function graph<NodeIds extends string = string>(nodes: Record<Nod
     next?: NextConfig<NodeIds>;
     input?: (ref: (nodeId: NodeIds, path: string) => RefValue) => Record<string, unknown>;
     onError?: NodeIds | NodeIds[];
+    retries?: number;
+    retryDelay?: string | number;
 }>): Record<NodeIds, GraphNodeConfig<NodeIds>>;
 export {};

package/dist/wirings/workflow/graph/graph-node.js

@@ -20,6 +20,8 @@ export function createGraph() {
                 input: def?.input,
                 next: def?.next,
                 onError: def?.onError,
+                retries: def?.retries,
+                retryDelay: def?.retryDelay,
             };
         }
         return result;
@@ -52,6 +54,8 @@ export function graph(nodes) {
             input: def.input,
             next: def.next,
             onError: def.onError,
+            retries: def.retries,
+            retryDelay: def.retryDelay,
         };
     }
     return result;

package/dist/wirings/workflow/graph/graph-runner.js

@@ -257,11 +257,13 @@ function areDependenciesSatisfied(node, completedNodeIds) {
     const deps = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
     return deps.every((dep) => completedNodeIds.has(dep));
 }
-async function queueGraphNode(workflowService, runId, _graphName, nodeId, rpcName, input) {
-    await workflowService.insertStepState(runId, nodeId, rpcName, input, {
-        retries: 0,
-    });
-    await workflowService.queueStepWorker(runId, nodeId, rpcName, input);
+async function queueGraphNode(workflowService, runId, _graphName, nodeId, rpcName, input, nodeConfig) {
+    const stepOptions = {
+        retries: nodeConfig?.retries ?? 0,
+        retryDelay: nodeConfig?.retryDelay,
+    };
+    await workflowService.insertStepState(runId, nodeId, rpcName, input, stepOptions);
+    await workflowService.queueStepWorker(runId, nodeId, rpcName, input, stepOptions);
 }
 export async function continueGraph(workflowService, runId, graphName, overrideMeta) {
     const meta = overrideMeta ?? getWorkflowMeta(graphName);
@@ -332,7 +334,7 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
         const fetchedResults = await workflowService.getNodeResults(runId, referencedNodeIds);
         const nodeResults = { trigger: triggerInput, ...fetchedResults };
         const resolvedInput = resolveSerializedInput(node.input, nodeResults);
-        await queueGraphNode(workflowService, runId, graphName, nodeId, node.rpcName, resolvedInput);
+        await queueGraphNode(workflowService, runId, graphName, nodeId, node.rpcName, resolvedInput, node);
     }
 }
 export async function executeGraphStep(workflowService, rpcService, runId, stepId, nodeId, rpcName, data, graphName) {
@@ -410,7 +412,7 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
                 for (const errorNodeId of errorNodes) {
                     const errorNode = meta.nodes[errorNodeId];
                     if (errorNode) {
-                        await queueGraphNode(workflowService, runId, graphName, errorNodeId, errorNode.rpcName, { error: { message: error.message } });
+                        await queueGraphNode(workflowService, runId, graphName, errorNodeId, errorNode.rpcName, { error: { message: error.message } }, errorNode);
                     }
                 }
                 throw error;
@@ -430,7 +432,7 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
     if (!node)
         return;
     const rpcName = node.rpcName;
-    const stepState = await workflowService.insertStepState(runId, nodeId, rpcName, input, { retries: 3 });
+    const stepState = await workflowService.insertStepState(runId, nodeId, rpcName, input, { retries: node.retries ?? 0, retryDelay: node.retryDelay });
     await workflowService.setStepRunning(stepState.stepId);
     const wireState = {};
     const graphWire = {
@@ -486,7 +488,7 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
                 message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
                 code: 'RPC_NOT_FOUND',
             });
-            return;
+            throw new WorkflowSuspendedException(runId, 'RPC_NOT_FOUND');
         }
         await workflowService.setStepError(stepState.stepId, error);
         if (node?.onError) {
@@ -627,7 +629,7 @@ export async function runWorkflowGraph(workflowService, graphName, triggerInput,
             const resolvedInput = node.input && Object.keys(node.input).length > 0
                 ? resolveSerializedInput(node.input, triggerNodeResults)
                 : triggerInput;
-            await queueGraphNode(workflowService, runId, graphName, nodeId, node.rpcName, resolvedInput);
+            await queueGraphNode(workflowService, runId, graphName, nodeId, node.rpcName, resolvedInput, node);
         }
         if (inline) {
             workflowService.unregisterInlineRun(runId);

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

@@ -45,6 +45,10 @@ export interface GraphNodeConfig<NodeIds extends string = string> {
     next?: NextConfig<NodeIds>;
     /** Error routing - node(s) to execute on error */
     onError?: NodeIds | NodeIds[];
+    /** Maximum retry attempts allowed (excludes the initial attempt) */
+    retries?: number;
+    /** Delay between retries — milliseconds, duration string, or 'exponential' */
+    retryDelay?: string | number;
 }
 /**
  * Graph wire context - available to functions running in a workflow graph

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

@@ -8,5 +8,5 @@ export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGr
 export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowService, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

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;