@pikku/core 0.12.134 → 0.12.136

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

@@ -1,5 +1,4 @@
-import { runPikkuFunc } from '../../function/function-runner.js';
-import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../pikku-state.js';
+import { getSingletonServices, pikkuState } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { ChildWorkflowStartedException, continueGraph, executeGraphStep, runWorkflowGraph, stripInstanceOrdinal, } from './graph/graph-runner.js';
 import { isExpectedError } from '../../errors/error-handler.js';
@@ -8,8 +7,8 @@ import { RPCNotFoundError } from '../rpc/rpc-runner.js';
 import { deriveInvocationId } from './workflow-invocation-id.js';
 import { approvalDeciderFrom } from './workflow-approval-policy.js';
 import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
-import { DEFAULT_STEP_RETRIES, RUN_LEASE_RETRY_MS, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, isRunSettled, } from './workflow-constants.js';
-import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepNameNotString, WorkflowStepSupersededError, WorkflowSuspendedException, } from './workflow-errors.js';
+import { DEFAULT_STEP_RETRIES, RUN_LEASE_RETRY_MS, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, NO_COMPENSATE_STATE_PREFIX, forwardStepName, isCompensationStepName, milestoneStepName, isRunSettled, } from './workflow-constants.js';
+import { WorkflowAsyncException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepNameNotString, WorkflowStepSupersededError, } from './workflow-errors.js';
 import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
 import { storeWorkflowVersion } from './workflow-version-store.js';
 import { jobGroupFor, orchestratorQueueName, requireQueueService, resolveWorkflowConfig, stepDispatchTarget, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
@@ -22,6 +21,9 @@ import { holdWorkflowLease, isRunLeaseError, nullWhenStepHeld, } from './workflo
 import { summarizeRunStatus } from './workflow-run-status.js';
 import { runningStepLease, startStepLeaseRefresh, stepLeaseMsForQueue, } from './workflow-step-lease.js';
 import { runInlineRetryLoop } from './workflow-step-retry.js';
+import { runInlineChildStep, startQueuedChildStep, } from './workflow-child-step.js';
+import { runDslWorkflowPass } from './workflow-dsl-pass.js';
+import { childRunFailure, failRunOrUnwind, isUnwound, compensatingForStep, cancelAndUnwind, createUnwindHost, driveUnwind, recordHasCompensation, isChildWorkflowRecord, } from './workflow-compensation.js';
 import { runVersionMismatchFallback } from './workflow-version-fallback.js';
 import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
 export class PikkuWorkflowService {
@@ -426,12 +428,16 @@ export class PikkuWorkflowService {
                     error.name !== 'WorkflowSuspendedException' &&
                     error.name !== 'WorkflowDispatchException' &&
                     !isRunLeaseError(error)) {
-                    await this.updateRunStatus(runId, 'failed', undefined, {
+                    await this.markFailedUnlessUnwound(runId, {
                         name: error.name,
                         message: error.message,
                         stack: error.stack,
                     });
                     getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, isExpectedError(error) ? error.message : error);
+                    const settled = await this.getRun(runId);
+                    if (settled?.wire?.type === 'workflow' && isUnwound(settled.status)) {
+                        throw childRunFailure(settled) ?? error;
+                    }
                     throw error;
                 }
                 // A lease error says nothing about how the run went — a lost lease is
@@ -455,7 +461,9 @@ export class PikkuWorkflowService {
     async runToCompletion(name, input, rpcService, options) {
         const { runId } = await this.startWorkflow(name, input, options?.wire ?? { type: 'internal' }, rpcService, { inline: true });
         const run = await this.awaitRunEnd(runId, options?.pollIntervalMs ?? 1000);
-        if (run.status === 'failed') {
+        if (run.status === 'failed' ||
+            run.status === 'compensated' ||
+            run.status === 'compensation_failed') {
             throw new WorkflowRunFailedError(run.error?.message);
         }
         if (run.status === 'cancelled') {
@@ -565,6 +573,11 @@ export class PikkuWorkflowService {
         }
         if (isRunSettled(run.status))
             return;
+        if (run.status === 'compensating') {
+            const host = createUnwindHost(this.compensationApi(rpcService));
+            await this.withRunLease(runId, () => driveUnwind(host, runId));
+            return;
+        }
         const resolved = resolveWorkflowMeta(run.workflow);
         const workflowMeta = resolved?.meta;
         const pkgName = resolved?.packageName ?? null;
@@ -579,13 +592,12 @@ export class PikkuWorkflowService {
             // can fire the same next node; the run lease keeps them one at a time,
             // exactly as it does for a DSL run's replay.
             await this.withRunLease(runId, async () => {
-                await continueGraph(this, runId, run.workflow);
+                await continueGraph(this, runId, run.workflow, undefined, rpcService);
                 const updatedRun = await this.getRun(runId);
                 if (updatedRun?.status === 'completed') {
                     await this.onChildWorkflowCompleted(updatedRun, updatedRun.output);
                 }
-                else if (updatedRun?.status === 'failed' ||
-                    updatedRun?.status === 'cancelled') {
+                else if (updatedRun?.status === 'cancelled') {
                     await this.onChildWorkflowFailed(updatedRun, new Error(updatedRun.error?.message || 'Child workflow failed'));
                 }
             });
@@ -599,82 +611,14 @@ export class PikkuWorkflowService {
         if (!workflow) {
             throw new WorkflowNotFoundError(run.workflow);
         }
-        await this.withRunLease(runId, async () => {
-            const addonNs = run.workflow.includes(':')
-                ? run.workflow.substring(0, run.workflow.indexOf(':'))
-                : null;
-            const workflowWire = this.createWorkflowWire(run.workflow, runId, rpcService, addonNs);
-            workflowWire.pikkuUserId = run.wire?.pikkuUserId;
-            // No `rpc` yet — runPikkuFunc attaches it lazily for the invocation.
-            const wire = {
-                workflow: workflowWire,
-                pikkuUserId: run.wire?.pikkuUserId,
-            };
-            this.runExtension?.decorateRunWire(wire, {
-                runId,
-                workflowMeta,
-                workflowWire,
-            });
-            const lifecycle = {
-                runId,
-                run,
-                workflowMeta,
-                workflow,
-                wire,
-                packageName: pkgName,
-            };
-            let outcome = 'completed';
-            let failure;
-            try {
-                await this.runExtension?.onBeforeRunFunc(lifecycle);
-                const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
-                    singletonServices: getSingletonServices(),
-                    wire,
-                    createWireServices: getCreateWireServices(),
-                    data: () => run.input,
-                    packageName: pkgName ?? undefined,
-                });
-                await this.updateRunStatus(runId, 'completed', result);
-                await this.onChildWorkflowCompleted(run, result);
-            }
-            catch (error) {
-                failure = error;
-                if (error instanceof WorkflowAsyncException) {
-                    outcome = 'interrupted';
-                    throw error;
-                }
-                if (error instanceof WorkflowCancelledException) {
-                    outcome = 'failed';
-                    await this.updateRunStatus(runId, 'cancelled', undefined, {
-                        message: error.message || 'Workflow cancelled',
-                        stack: '',
-                        code: 'WORKFLOW_CANCELLED',
-                    });
-                    await this.onChildWorkflowFailed(run, error);
-                    throw error;
-                }
-                if (error instanceof WorkflowSuspendedException) {
-                    outcome = 'interrupted';
-                    await this.updateRunStatus(runId, 'suspended', undefined, {
-                        message: error.message || 'Workflow suspended',
-                        stack: '',
-                        code: 'WORKFLOW_SUSPENDED',
-                    });
-                    throw error;
-                }
-                outcome = 'failed';
-                await this.updateRunStatus(runId, 'failed', undefined, {
-                    message: error.message,
-                    stack: error.stack,
-                    code: error.code,
-                });
-                await this.onChildWorkflowFailed(run, error);
-                throw error;
-            }
-            finally {
-                await this.runExtension?.onAfterRunFunc(lifecycle, outcome, failure);
-            }
-        });
+        await this.withRunLease(runId, () => runDslWorkflowPass({
+            workflowWire: (addonNs) => this.createWorkflowWire(run.workflow, runId, rpcService, addonNs),
+            extension: this.runExtension,
+            updateRunStatus: (status, output, error) => this.updateRunStatus(runId, status, output, error),
+            onChildCompleted: (result) => this.onChildWorkflowCompleted(run, result),
+            onChildFailed: (error) => this.onChildWorkflowFailed(run, error),
+            failOrUnwind: (error) => this.failOrUnwind(run, error, rpcService),
+        }, run, workflowMeta, workflow, pkgName));
     }
     async onChildWorkflowCompleted(childRun, result) {
         const { parentRunId, parentStepId } = childRun.wire ?? {};
@@ -684,6 +628,9 @@ export class PikkuWorkflowService {
         await this.setStepResult(parentStepId, result);
         await this.resumeWorkflow(parentRunId);
     }
+    notifyChildWorkflowFailed(childRun, error) {
+        return this.onChildWorkflowFailed(childRun, error);
+    }
     async onChildWorkflowFailed(childRun, error) {
         const { parentRunId, parentStepId } = childRun.wire ?? {};
         if (!parentRunId || !parentStepId)
@@ -761,34 +708,20 @@ export class PikkuWorkflowService {
                 result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, workflowMeta.nodes[graphNodeId].rpcName, data, run.workflow);
             }
             else {
-                const subWorkflowMeta = meta[rpcName];
-                if (subWorkflowMeta) {
-                    const childWire = {
-                        type: 'workflow',
-                        id: rpcName,
-                        parentRunId: runId,
-                        parentStepId: stepState.stepId,
-                        pikkuUserId: run.wire?.pikkuUserId,
-                    };
-                    const shouldInline = !getSingletonServices()?.queueService;
-                    const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
-                    await this.setStepChildRunId(stepState.stepId, childRunId);
-                    if (shouldInline) {
-                        const childRun = await this.getRun(childRunId);
-                        if (childRun?.status === 'failed') {
-                            throw new Error(childRun.error?.message || 'Sub-workflow failed');
-                        }
-                        if (childRun?.status === 'cancelled') {
-                            throw new Error('Sub-workflow was cancelled');
-                        }
-                        result = childRun?.output;
-                    }
-                    else {
-                        throw new ChildWorkflowStartedException(runId, stepState.stepId, childRunId);
-                    }
+                if (meta[rpcName]) {
+                    result = await startQueuedChildStep({
+                        startWorkflow: (...args) => this.startWorkflow(...args),
+                        setStepChildRunId: (...args) => this.setStepChildRunId(...args),
+                        getRun: (id) => this.getRun(id),
+                    }, runId, stepState.stepId, rpcName, data, rpcService, run.wire?.pikkuUserId);
                 }
                 else {
-                    result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService, run);
+                    result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService, run, isCompensationStepName(stepName)
+                        ? compensatingForStep({
+                            ...(await this.getStepState(runId, forwardStepName(stepName))),
+                            stepName: forwardStepName(stepName),
+                        })
+                        : undefined);
                 }
             }
             await this.setStepResult(stepState.stepId, result, attempt);
@@ -848,7 +781,7 @@ export class PikkuWorkflowService {
                 getSingletonServices().logger.warn(`Workflow run ${runId} could not dispatch a step (queue unavailable); leaving run for orchestrator retry`, error);
                 throw error;
             }
-            await this.updateRunStatus(runId, 'failed', undefined, {
+            await this.markFailedUnlessUnwound(runId, {
                 message: error.message,
                 stack: error.stack,
                 code: error.code,
@@ -856,10 +789,18 @@ export class PikkuWorkflowService {
             throw error;
         }
     }
-    async invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService, knownRun) {
+    async invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService, knownRun, compensatingFor) {
         const run = knownRun ?? (await this.getRunIdentity(runId));
         return rpcService.rpcWithWire(rpcName, data, {
             ...(run?.wire?.pikkuUserId ? { pikkuUserId: run.wire.pikkuUserId } : {}),
+            ...(compensatingFor
+                ? {
+                    workflow: {
+                        ...this.createWorkflowWire(run?.workflow ?? '', runId, rpcService),
+                        compensatingFor,
+                    },
+                }
+                : {}),
             workflowStep: {
                 runId,
                 stepId: stepState.stepId,
@@ -878,18 +819,19 @@ export class PikkuWorkflowService {
             retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
             retryDelay: stepOptions?.retryDelay,
             actor: stepOptions?.actor,
-            onError: stepOptions?.onError,
         };
-        const stepState = await this.loadOrCreateStep(runId, stepName, () => this.insertStepState(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName));
+        const stepState = await this.loadOrCreateStep(runId, stepName, async () => {
+            if (stepOptions?.compensate === false) {
+                await this.updateRunState(runId, `${NO_COMPENSATE_STATE_PREFIX}${stepName}`, true);
+            }
+            return this.insertStepState(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName);
+        });
         if (stepState.status === 'succeeded') {
             return stepState.result;
         }
         if (stepState.status === 'failed') {
             const error = new Error(stepState.error?.message ||
                 `Step '${stepName}' failed after exhausting all retries`);
-            if (resolvedStepOptions.onError) {
-                await this.rpcStep(runId, `${stepName}:onError`, resolvedStepOptions.onError, { error: { message: error.message } }, rpcService, { retries: 0 });
-            }
             if (stepState.error) {
                 Object.assign(error, stepState.error);
             }
@@ -917,24 +859,12 @@ export class PikkuWorkflowService {
             if (resolvedStepOptions.actor) {
                 return resolvedStepOptions.actor.invoke(rpcName, data);
             }
-            const workflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
-            if (workflowMeta) {
-                const childWire = {
-                    type: 'workflow',
-                    id: rpcName,
-                    parentRunId: runId,
-                    pikkuUserId: (await this.getRunIdentity(runId))?.wire?.pikkuUserId,
-                };
-                const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: true });
-                await this.setStepChildRunId(currentStepState.stepId, childRunId);
-                const childRun = await this.awaitRunEnd(childRunId, WORKFLOW_CHILD_POLL_MAX_MS);
-                if (childRun.status === 'failed') {
-                    throw new Error(childRun.error?.message || 'Sub-workflow failed');
-                }
-                if (childRun.status === 'cancelled') {
-                    throw new Error('Sub-workflow was cancelled');
-                }
-                return childRun.output;
+            if (pikkuState(null, 'workflows', 'meta')[rpcName]) {
+                return runInlineChildStep({
+                    startWorkflow: (...args) => this.startWorkflow(...args),
+                    setStepChildRunId: (...args) => this.setStepChildRunId(...args),
+                    awaitRunEnd: (id) => this.awaitRunEnd(id, WORKFLOW_CHILD_POLL_MAX_MS),
+                }, runId, currentStepState.stepId, rpcName, data, rpcService, (await this.getRunIdentity(runId))?.wire?.pikkuUserId);
             }
             return this.invokeStepRpc(runId, stepName, currentStepState, rpcName, data, rpcService);
         }, async (error) => {
@@ -1020,14 +950,14 @@ export class PikkuWorkflowService {
     }
     get approvalStore() {
         return {
-            getStepState: (runId, stepName) => this.getStepState(runId, stepName),
-            insertStepState: (runId, stepName, rpcName, input, output, fromStepName) => this.insertStepState(runId, stepName, rpcName, input, output, fromStepName),
-            setStepRunning: (stepId) => this.setStepRunning(stepId),
-            setStepResult: (stepId, result) => this.setStepResult(stepId, result),
-            getRunState: (runId) => this.getRunState(runId),
-            updateRunState: (runId, key, value) => this.updateRunState(runId, key, value),
+            getStepState: (...args) => this.getStepState(...args),
+            insertStepState: (...args) => this.insertStepState(...args),
+            setStepRunning: (...args) => this.setStepRunning(...args),
+            setStepResult: (...args) => this.setStepResult(...args),
+            getRunState: (...args) => this.getRunState(...args),
+            updateRunState: (...args) => this.updateRunState(...args),
             resumeWorkflow: (runId) => this.resumeWorkflow(runId),
-            scheduleRunWake: (runId, delay) => this.scheduleRunWake(runId, delay),
+            scheduleRunWake: (...args) => this.scheduleRunWake(...args),
             getRunOwner: async (runId) => (await this.getRunIdentity(runId))?.wire?.pikkuUserId,
             auditApproval: (event) => auditApprovalDecision(event),
         };
@@ -1065,6 +995,12 @@ export class PikkuWorkflowService {
                 this.verifyStepName(reason);
                 await this.suspendStep(runId, reason);
             },
+            milestone: async (name) => {
+                this.verifyStepName(name);
+                await this.inlineStep(runId, milestoneStepName(name), async () => ({
+                    name,
+                }));
+            },
             approval: (async (reason, options) => {
                 this.verifyStepName(reason);
                 return await this.approvalStep(runId, reason, options);
@@ -1078,6 +1014,40 @@ export class PikkuWorkflowService {
         });
         return workflowWire;
     }
+    compensationApi(rpcService) {
+        return {
+            getRun: (...args) => this.getRun(...args),
+            getRunSteps: (...args) => this.getRunSteps(...args),
+            getRunState: (...args) => this.getRunState(...args),
+            updateRunStatus: (...args) => this.updateRunStatus(...args),
+            loadStep: (...args) => this.loadOrCreateStep(...args),
+            insertStepState: (...args) => this.insertStepState(...args),
+            dispatchStep: (...args) => this.dispatchStep(...args),
+            setStepScheduled: (id) => this.setStepScheduled(id),
+            setStepResult: (id, result) => this.setStepResult(id, result),
+            setStepError: (id, error) => this.setStepError(id, error),
+            runInline: (...args) => runInlineRetryLoop(this, ...args),
+            invoke: (runId, stepName, step, rpcName, data, compensatingFor) => this.invokeStepRpc(runId, stepName, step, rpcName, data, rpcService, undefined, compensatingFor),
+            failOrUnwind: (run, error) => this.failOrUnwind(run, error, rpcService),
+            notifyParent: (run, error) => this.onChildWorkflowFailed(run, error),
+            hasCompensation: recordHasCompensation,
+            isChildWorkflow: isChildWorkflowRecord,
+        };
+    }
+    async failOrUnwind(run, error, rpcService) {
+        const api = this.compensationApi(rpcService);
+        return failRunOrUnwind(api, run, error, () => this.onChildWorkflowFailed(run, error));
+    }
+    /** Stops an unfinished run, children first, and unwinds what it completed. */
+    async cancelRun(runId, rpcService, reason) {
+        const api = this.compensationApi(rpcService);
+        return cancelAndUnwind(api, createUnwindHost(api), runId, reason);
+    }
+    async markFailedUnlessUnwound(runId, error) {
+        if (isUnwound((await this.getRun(runId))?.status))
+            return;
+        await this.updateRunStatus(runId, 'failed', undefined, error);
+    }
     verifyStepName(stepName) {
         if (typeof stepName !== 'string') {
             throw new WorkflowStepNameNotString(stepName);

package/dist/wirings/workflow/run-timeline.d.ts

@@ -5,6 +5,7 @@ export interface RunTimelineEvent {
     at: Date;
     type: Extract<StepStatus, 'pending' | 'scheduled' | 'running' | 'succeeded' | 'failed'>;
     stepName: string;
+    compensating: boolean;
     attemptCount: number;
     fromStepName?: string;
     result?: unknown;
@@ -17,6 +18,7 @@ export type HistoryEntry = StepState & {
 export declare function buildRunTimeline(history: HistoryEntry[]): RunTimeline;
 export interface ReconstructedStep {
     stepName: string;
+    compensating: boolean;
     status: StepStatus;
     attemptCount: number;
     fromStepName?: string;

package/dist/wirings/workflow/run-timeline.js

@@ -1,3 +1,4 @@
+import { isCompensationStepName } from './workflow-constants.js';
 const LIFECYCLE_ORDER = {
     pending: 0,
     scheduled: 1,
@@ -10,6 +11,7 @@ export function buildRunTimeline(history) {
     history.forEach((entry, order) => {
         const base = {
             stepName: entry.stepName,
+            compensating: entry.compensating ?? isCompensationStepName(entry.stepName),
             attemptCount: entry.attemptCount,
             order,
         };
@@ -77,6 +79,7 @@ export function reconstructStateAt(timeline, at) {
         if (!step) {
             step = {
                 stepName: event.stepName,
+                compensating: event.compensating,
                 status: event.type,
                 attemptCount: event.attemptCount,
                 fromStepName: event.fromStepName,

package/dist/wirings/workflow/workflow-child-step.d.ts

@@ -0,0 +1,17 @@
+import type { PikkuRPC } from '../rpc/rpc-types.js';
+import type { WorkflowRun, WorkflowRunWire } from './workflow.types.js';
+interface ChildStepApi {
+    startWorkflow(name: string, input: unknown, wire: WorkflowRunWire, rpcService: PikkuRPC, options?: {
+        inline?: boolean;
+    }): Promise<{
+        runId: string;
+    }>;
+    setStepChildRunId(stepId: string, childRunId: string): Promise<void>;
+}
+export declare const runInlineChildStep: (api: ChildStepApi & {
+    awaitRunEnd(childRunId: string): Promise<WorkflowRun>;
+}, runId: string, stepId: string, workflowName: string, data: unknown, rpcService: PikkuRPC, pikkuUserId: string | undefined) => Promise<unknown>;
+export declare const startQueuedChildStep: (api: ChildStepApi & {
+    getRun(id: string): Promise<WorkflowRun | null>;
+}, runId: string, stepId: string, workflowName: string, data: unknown, rpcService: PikkuRPC, pikkuUserId: string | undefined) => Promise<unknown>;
+export {};

package/dist/wirings/workflow/workflow-child-step.js

@@ -0,0 +1,31 @@
+import { getSingletonServices } from '../../pikku-state.js';
+import { ChildWorkflowStartedException } from './graph/graph-runner.js';
+import { childRunFailure } from './workflow-compensation.js';
+export const runInlineChildStep = async (api, runId, stepId, workflowName, data, rpcService, pikkuUserId) => {
+    const { runId: childRunId } = await api.startWorkflow(workflowName, data, { type: 'workflow', id: workflowName, parentRunId: runId, pikkuUserId }, rpcService, { inline: true });
+    await api.setStepChildRunId(stepId, childRunId);
+    const childRun = await api.awaitRunEnd(childRunId);
+    const failure = childRunFailure(childRun);
+    if (failure)
+        throw failure;
+    return childRun.output;
+};
+export const startQueuedChildStep = async (api, runId, stepId, workflowName, data, rpcService, pikkuUserId) => {
+    const shouldInline = !getSingletonServices()?.queueService;
+    const { runId: childRunId } = await api.startWorkflow(workflowName, data, {
+        type: 'workflow',
+        id: workflowName,
+        parentRunId: runId,
+        parentStepId: stepId,
+        pikkuUserId,
+    }, rpcService, { inline: shouldInline });
+    await api.setStepChildRunId(stepId, childRunId);
+    if (!shouldInline) {
+        throw new ChildWorkflowStartedException(runId, stepId, childRunId);
+    }
+    const childRun = await api.getRun(childRunId);
+    const failure = childRun && childRunFailure(childRun);
+    if (failure)
+        throw failure;
+    return childRun?.output;
+};

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

@@ -0,0 +1,68 @@
+import type { SerializedError } from '../../errors/serialized-error.js';
+import type { CompensatingFor } from './dsl/workflow-dsl.types.js';
+import { type UnwindRecord } from './workflow-unwind-plan.js';
+import type { StepState, WorkflowRun, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
+export type CompensationStepOutcome = 'done' | 'waiting' | 'stuck';
+export interface UnwindHost {
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    getRunSteps(runId: string): Promise<UnwindRecord[]>;
+    getRunState(runId: string): Promise<Record<string, unknown>>;
+    hasCompensation(record: UnwindRecord): boolean;
+    isChildWorkflow(record: UnwindRecord): boolean;
+    runCompensationStep(runId: string, forward: UnwindRecord, compensatingFor: CompensatingFor): Promise<CompensationStepOutcome>;
+    finish(run: WorkflowRun, status: WorkflowStatus, output: unknown, error: SerializedError | undefined): Promise<void>;
+}
+export declare const canEnterCompensation: (status: string) => boolean;
+export declare const compensatingForStep: (forward: Pick<UnwindRecord, 'status' | 'result' | 'error' | 'stepName'>) => CompensatingFor;
+export declare const skippedSteps: (state: Record<string, unknown>) => Set<string>;
+export declare const wouldCompensate: (host: UnwindHost, runId: string) => Promise<boolean>;
+export declare const driveUnwind: (host: UnwindHost, runId: string) => Promise<'waiting' | 'finished'>;
+export declare const compensationRpcName: (rpcName: string) => string;
+export interface CompensationApi {
+    getRun(runId: string): Promise<WorkflowRun | null>;
+    getRunSteps(runId: string): Promise<UnwindRecord[]>;
+    getRunState(runId: string): Promise<Record<string, unknown>>;
+    updateRunStatus(runId: string, status: WorkflowStatus, output?: unknown, error?: SerializedError): Promise<void>;
+    loadStep(runId: string, stepName: string, create: () => Promise<StepState>): Promise<StepState>;
+    insertStepState(runId: string, stepName: string, rpcName: string | null, data: unknown, options: WorkflowStepOptions, fromStepName: string): Promise<StepState>;
+    dispatchStep(runId: string, stepName: string, rpcName: string, data: unknown, options: WorkflowStepOptions, fromStepName: string): Promise<boolean>;
+    setStepScheduled(stepId: string): Promise<void>;
+    runInline(stepState: StepState, retries: number, retryDelay: WorkflowStepOptions['retryDelay'], work: (current: StepState) => Promise<unknown>): Promise<unknown>;
+    invoke(runId: string, stepName: string, stepState: StepState, rpcName: string, data: unknown, compensatingFor: CompensatingFor): Promise<unknown>;
+    failOrUnwind(run: WorkflowRun, error: Error): Promise<unknown>;
+    setStepResult(stepId: string, result: unknown): Promise<void>;
+    setStepError(stepId: string, error: Error): Promise<void>;
+    notifyParent(run: WorkflowRun, error: Error): Promise<void>;
+    hasCompensation(record: UnwindRecord): boolean;
+    isChildWorkflow(record: UnwindRecord): boolean;
+}
+export declare const createUnwindHost: (api: CompensationApi) => UnwindHost;
+export declare const childCompensationError: (status: WorkflowStatus, output: unknown, error: SerializedError | undefined) => Error & {
+    childCompensation: ChildCompensationInfo;
+};
+export declare const functionHasCompensation: (rpcName: string) => boolean;
+export declare const isChildWorkflowRecord: (record: UnwindRecord) => boolean;
+export declare const recordHasCompensation: (record: UnwindRecord) => boolean;
+export interface ChildCompensationInfo {
+    status: WorkflowStatus;
+    restedAt?: string;
+    stuckSteps?: Array<{
+        stepName: string;
+        error: string;
+    }>;
+}
+export type UnwindCause = SerializedError & {
+    childCompensation?: ChildCompensationInfo;
+};
+export declare const childRunFailure: (childRun: WorkflowRun) => Error | null;
+export declare const beginUnwind: (api: CompensationApi, host: UnwindHost, run: WorkflowRun, cause: UnwindCause) => Promise<'unwinding' | 'finished' | 'not-needed'>;
+export declare const isUnwound: (status: string | undefined) => boolean;
+export declare const failRunOrUnwind: (api: CompensationApi, run: WorkflowRun, error: Error & {
+    code?: string;
+    childCompensation?: ChildCompensationInfo;
+}, onFailed: () => Promise<void>) => Promise<'unwinding' | 'finished' | 'failed'>;
+/**
+ * Child workflows are cancelled first so nothing keeps producing effects under
+ * a parent that is unwinding. A run with nothing to undo stays `cancelled`.
+ */
+export declare const cancelAndUnwind: (api: CompensationApi, host: UnwindHost, runId: string, reason?: string) => Promise<WorkflowStatus | undefined>;