@pikku/core 0.12.134 → 0.12.136

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

@@ -0,0 +1,282 @@
+import { DEFAULT_STEP_RETRIES, NO_COMPENSATE_STATE_PREFIX, WORKFLOW_TERMINAL_STATES, compensationStepName, } from './workflow-constants.js';
+import { pikkuState } from '../../pikku-state.js';
+import { resolveNamespace } from '../rpc/rpc-runner.js';
+import { runningStepLease } from './workflow-step-lease.js';
+import { planUnwind } from './workflow-unwind-plan.js';
+const ENTERABLE = new Set([
+    'running',
+    'suspended',
+    'failed',
+    'cancelled',
+    'completed',
+]);
+export const canEnterCompensation = (status) => ENTERABLE.has(status);
+export const compensatingForStep = (forward) => forward.status === 'succeeded'
+    ? { ok: true, output: forward.result, stepName: forward.stepName }
+    : {
+        ok: false,
+        output: null,
+        error: forward.error ?? { message: 'step failed' },
+        stepName: forward.stepName,
+    };
+export const skippedSteps = (state) => new Set(Object.keys(state)
+    .filter((k) => k.startsWith(NO_COMPENSATE_STATE_PREFIX) && state[k])
+    .map((k) => k.slice(NO_COMPENSATE_STATE_PREFIX.length)));
+export const wouldCompensate = async (host, runId) => {
+    const [records, state] = await Promise.all([
+        host.getRunSteps(runId),
+        host.getRunState(runId),
+    ]);
+    const plan = planUnwind({
+        records,
+        skip: skippedSteps(state),
+        hasCompensation: host.hasCompensation,
+        isChildWorkflow: host.isChildWorkflow,
+    });
+    return plan.candidates.length > 0 || plan.forwardInFlight || !!plan.restedAt;
+};
+export const driveUnwind = async (host, runId) => {
+    for (;;) {
+        const run = await host.getRun(runId);
+        if (!run || WORKFLOW_TERMINAL_STATES.has(run.status))
+            return 'finished';
+        const [records, state] = await Promise.all([
+            host.getRunSteps(runId),
+            host.getRunState(runId),
+        ]);
+        const plan = planUnwind({
+            records,
+            skip: skippedSteps(state),
+            hasCompensation: host.hasCompensation,
+            isChildWorkflow: host.isChildWorkflow,
+        });
+        if (plan.forwardInFlight)
+            return 'waiting';
+        if (plan.ready.length > 0) {
+            let progressed = false;
+            for (const forward of plan.ready) {
+                const outcome = await host.runCompensationStep(runId, forward, compensatingForStep(forward));
+                if (outcome !== 'waiting')
+                    progressed = true;
+            }
+            if (progressed)
+                continue;
+            return 'waiting';
+        }
+        if (!plan.settled)
+            return 'waiting';
+        if (plan.stuck.length > 0) {
+            await host.finish(run, 'compensation_failed', { stuckSteps: plan.stuck }, run.error);
+        }
+        else if (plan.compensated || plan.restedAt) {
+            const restedAt = plan.childRestedAt ?? plan.restedAt;
+            await host.finish(run, 'compensated', restedAt ? { restedAt } : undefined, run.error);
+        }
+        else {
+            await host.finish(run, 'failed', undefined, run.error);
+        }
+        return 'finished';
+    }
+};
+export const compensationRpcName = (rpcName) => `${rpcName}:compensate`;
+export const createUnwindHost = (api) => ({
+    getRun: (id) => api.getRun(id),
+    getRunSteps: (id) => api.getRunSteps(id),
+    getRunState: (id) => api.getRunState(id),
+    hasCompensation: (r) => api.hasCompensation(r),
+    isChildWorkflow: (r) => api.isChildWorkflow(r),
+    runCompensationStep: (runId, forward, compensatingFor) => api.isChildWorkflow(forward)
+        ? compensateChildStep(api, runId, forward)
+        : compensateFunctionStep(api, runId, forward, compensatingFor),
+    finish: async (run, status, output, error) => {
+        await api.updateRunStatus(run.id, status, output, error);
+        const settled = (await api.getRun(run.id)) ?? run;
+        await api.notifyParent(settled, childCompensationError(status, output, error));
+    },
+});
+export const childCompensationError = (status, output, error) => {
+    const source = output;
+    const message = status === 'compensation_failed'
+        ? `Sub-workflow compensation failed at ${source?.stuckSteps?.map((s) => s.stepName).join(', ')}`
+        : error?.message || 'Sub-workflow failed';
+    return Object.assign(new Error(message), {
+        childCompensation: { status, ...(source ?? {}) },
+    });
+};
+const compensateFunctionStep = async (api, runId, forward, compensatingFor) => {
+    const stepName = compensationStepName(forward.stepName);
+    const rpcName = compensationRpcName(forward.rpcName);
+    const options = {
+        retries: forward.retries ?? DEFAULT_STEP_RETRIES,
+    };
+    const state = await api.loadStep(runId, stepName, () => api.insertStepState(runId, stepName, rpcName, forward.data, options, forward.stepName));
+    if (state.status === 'succeeded')
+        return 'done';
+    if (state.status === 'failed')
+        return 'stuck';
+    if (state.status === 'scheduled')
+        return 'waiting';
+    const lease = runningStepLease(state);
+    if (lease === 'held')
+        return 'waiting';
+    const dispatched = await api.dispatchStep(runId, stepName, rpcName, forward.data, options, forward.stepName);
+    if (dispatched) {
+        if (lease !== 'lapsed')
+            await api.setStepScheduled(state.stepId);
+        return 'waiting';
+    }
+    try {
+        await api.runInline(state, options.retries, undefined, (current) => api.invoke(runId, stepName, current, rpcName, forward.data, compensatingFor));
+        return 'done';
+    }
+    catch {
+        return 'stuck';
+    }
+};
+const compensateChildStep = async (api, runId, forward) => {
+    const stepName = compensationStepName(forward.stepName);
+    const state = await api.loadStep(runId, stepName, () => api.insertStepState(runId, stepName, null, { childRunId: forward.childRunId }, { retries: 0 }, forward.stepName));
+    if (state.status === 'succeeded')
+        return 'done';
+    if (state.status === 'failed')
+        return 'stuck';
+    if (!forward.childRunId) {
+        await api.setStepResult(state.stepId, undefined);
+        return 'done';
+    }
+    const child = await api.getRun(forward.childRunId);
+    if (child?.status === 'completed') {
+        await api.failOrUnwind(child, new Error('unwind'));
+    }
+    const after = await api.getRun(forward.childRunId);
+    switch (after?.status) {
+        case 'compensated': {
+            const restedAt = after.output
+                ?.restedAt;
+            await api.setStepResult(state.stepId, restedAt ? { restedAt } : undefined);
+            return 'done';
+        }
+        case 'compensation_failed':
+            await api.setStepError(state.stepId, new Error('child compensation failed'));
+            return 'stuck';
+        case 'failed':
+            await api.setStepResult(state.stepId, undefined);
+            return 'done';
+        default:
+            return 'waiting';
+    }
+};
+export const functionHasCompensation = (rpcName) => {
+    const funcId = pikkuState(null, 'rpc', 'meta')[rpcName];
+    const local = pikkuState(null, 'function', 'meta')[typeof funcId === 'string' ? funcId : rpcName];
+    if (local)
+        return local.compensate === true;
+    const resolved = resolveNamespace(rpcName);
+    return resolved
+        ? pikkuState(resolved.package, 'function', 'meta')[resolved.function]
+            ?.compensate === true
+        : false;
+};
+export const isChildWorkflowRecord = (record) => !!record.rpcName &&
+    pikkuState(null, 'workflows', 'meta')[record.rpcName] !== undefined;
+export const recordHasCompensation = (record) => isChildWorkflowRecord(record)
+    ? !!record.childRunId
+    : !!record.rpcName && functionHasCompensation(record.rpcName);
+export const childRunFailure = (childRun) => {
+    switch (childRun.status) {
+        case 'failed':
+            return new Error(childRun.error?.message || 'Sub-workflow failed');
+        case 'cancelled':
+            return new Error('Sub-workflow was cancelled');
+        case 'compensated':
+        case 'compensation_failed':
+            return childCompensationError(childRun.status, childRun.output, childRun.error);
+        default:
+            return null;
+    }
+};
+/**
+ * The error carrying a child's compensation outcome does not survive a step
+ * boundary, so a queued parent finds it again from the failed child step.
+ */
+const failedChildCompensation = async (api, runId) => {
+    const steps = await api.getRunSteps(runId);
+    let rested;
+    for (const step of steps) {
+        if (step.status !== 'failed' || !step.childRunId)
+            continue;
+        const child = await api.getRun(step.childRunId);
+        if (child?.status === 'compensation_failed') {
+            return childCompensationError(child.status, child.output, child.error)
+                .childCompensation;
+        }
+        if (child?.status === 'compensated') {
+            rested ??= childCompensationError(child.status, child.output, child.error).childCompensation;
+        }
+    }
+    return rested;
+};
+export const beginUnwind = async (api, host, run, cause) => {
+    const child = cause.childCompensation ?? (await failedChildCompensation(api, run.id));
+    if (child?.status === 'compensation_failed') {
+        await host.finish(run, 'compensation_failed', { stuckSteps: child.stuckSteps }, cause);
+        return 'finished';
+    }
+    if (child?.status === 'compensated' && child.restedAt) {
+        await host.finish(run, 'compensated', { restedAt: child.restedAt }, cause);
+        return 'finished';
+    }
+    if (!(await wouldCompensate(host, run.id)))
+        return 'not-needed';
+    const fresh = await api.getRun(run.id);
+    if (!fresh || !canEnterCompensation(fresh.status))
+        return 'finished';
+    await api.updateRunStatus(run.id, 'compensating', undefined, cause);
+    return (await driveUnwind(host, run.id)) === 'waiting'
+        ? 'unwinding'
+        : 'finished';
+};
+export const isUnwound = (status) => status === 'compensating' ||
+    status === 'compensated' ||
+    status === 'compensation_failed';
+export const failRunOrUnwind = async (api, run, error, onFailed) => {
+    const cause = {
+        message: error.message,
+        stack: error.stack,
+        code: error.code,
+        ...(error.childCompensation
+            ? { childCompensation: error.childCompensation }
+            : {}),
+    };
+    const outcome = await beginUnwind(api, createUnwindHost(api), run, cause);
+    if (outcome !== 'not-needed')
+        return outcome;
+    await api.updateRunStatus(run.id, 'failed', undefined, cause);
+    await onFailed();
+    return '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 const cancelAndUnwind = async (api, host, runId, reason) => {
+    const run = await api.getRun(runId);
+    if (!run)
+        return undefined;
+    if (WORKFLOW_TERMINAL_STATES.has(run.status) || isUnwound(run.status)) {
+        return run.status;
+    }
+    for (const step of await host.getRunSteps(runId)) {
+        if (step.childRunId) {
+            await cancelAndUnwind(api, host, step.childRunId, reason);
+        }
+    }
+    const cause = {
+        message: reason || 'Workflow cancelled',
+        stack: '',
+        code: 'WORKFLOW_CANCELLED',
+    };
+    await api.updateRunStatus(runId, 'cancelled', undefined, cause);
+    await beginUnwind(api, host, run, cause);
+    return (await api.getRun(runId))?.status;
+};

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

@@ -3,6 +3,10 @@ export declare const DEFAULT_STEP_RETRIES = 5;
 export declare const WORKFLOW_END_STATES: ReadonlySet<string>;
 /** Statuses a run cannot leave at all. */
 export declare const WORKFLOW_TERMINAL_STATES: ReadonlySet<string>;
+export declare const NO_COMPENSATE_STATE_PREFIX = "noCompensate:";
+export declare const MILESTONE_STEP_PREFIX = "__milestone__:";
+export declare const milestoneStepName: (name: string) => string;
+export declare const isMilestoneStepName: (stepName: string) => boolean;
 /**
  * True for a run that will never move again, whatever arrives for it.
  *
@@ -68,3 +72,4 @@ export declare const isStepLeaseLive: (leaseExpiresAt: Date | null | undefined,
 export declare const RUN_LEASE_RETRY_MS = 1000;
 /** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
 export declare const REDISPATCH_BACKOFF_MAX_ENTRIES = 10000;
+export { COMPENSATION_STEP_SUFFIX, compensationStepName, forwardStepName, isCompensationStepName, } from '../../function/compensation-name.js';

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

@@ -5,13 +5,21 @@ export const WORKFLOW_END_STATES = new Set([
     'failed',
     'cancelled',
     'suspended',
+    'compensated',
+    'compensation_failed',
 ]);
 /** Statuses a run cannot leave at all. */
 export const WORKFLOW_TERMINAL_STATES = new Set([
     'completed',
     'failed',
     'cancelled',
+    'compensated',
+    'compensation_failed',
 ]);
+export const NO_COMPENSATE_STATE_PREFIX = 'noCompensate:';
+export const MILESTONE_STEP_PREFIX = '__milestone__:';
+export const milestoneStepName = (name) => `${MILESTONE_STEP_PREFIX}${name}`;
+export const isMilestoneStepName = (stepName) => stepName.startsWith(MILESTONE_STEP_PREFIX);
 /**
  * True for a run that will never move again, whatever arrives for it.
  *
@@ -77,3 +85,4 @@ export const isStepLeaseLive = (leaseExpiresAt, now = Date.now()) => leaseExpire
 export const RUN_LEASE_RETRY_MS = 1_000;
 /** Bound on the in-process backoff map, so a long-lived process cannot grow it without bound. */
 export const REDISPATCH_BACKOFF_MAX_ENTRIES = 10_000;
+export { COMPENSATION_STEP_SUFFIX, compensationStepName, forwardStepName, isCompensationStepName, } from '../../function/compensation-name.js';

package/dist/wirings/workflow/workflow-dsl-pass.d.ts

@@ -0,0 +1,12 @@
+import type { SerializedError } from '../../errors/serialized-error.js';
+import type { RunLifecycleContext, WorkflowRunExtension } from './workflow-run-engine.types.js';
+import type { PikkuWorkflowWire, WorkflowRun, WorkflowStatus } from './workflow.types.js';
+export interface DslPassDeps {
+    workflowWire: (addonNamespace: string | null) => PikkuWorkflowWire;
+    extension: WorkflowRunExtension | undefined;
+    updateRunStatus: (status: WorkflowStatus, output?: unknown, error?: SerializedError) => Promise<void>;
+    onChildCompleted: (result: unknown) => Promise<void>;
+    onChildFailed: (error: Error) => Promise<void>;
+    failOrUnwind: (error: Error) => Promise<'unwinding' | 'finished' | 'failed'>;
+}
+export declare const runDslWorkflowPass: (deps: DslPassDeps, run: WorkflowRun, workflowMeta: RunLifecycleContext['workflowMeta'], workflow: RunLifecycleContext['workflow'], pkgName: string | null) => Promise<void>;

package/dist/wirings/workflow/workflow-dsl-pass.js

@@ -0,0 +1,75 @@
+import { runPikkuFunc } from '../../function/function-runner.js';
+import { getCreateWireServices, getSingletonServices, } from '../../pikku-state.js';
+import { WorkflowAsyncException, WorkflowCancelledException, WorkflowSuspendedException, } from './workflow-errors.js';
+export const runDslWorkflowPass = async (deps, run, workflowMeta, workflow, pkgName) => {
+    const runId = run.id;
+    const addonNs = run.workflow.includes(':')
+        ? run.workflow.substring(0, run.workflow.indexOf(':'))
+        : null;
+    const workflowWire = deps.workflowWire(addonNs);
+    workflowWire.pikkuUserId = run.wire?.pikkuUserId;
+    const wire = {
+        workflow: workflowWire,
+        pikkuUserId: run.wire?.pikkuUserId,
+    };
+    deps.extension?.decorateRunWire(wire, {
+        runId,
+        workflowMeta,
+        workflowWire,
+    });
+    const lifecycle = {
+        runId,
+        run,
+        workflowMeta,
+        workflow,
+        wire,
+        packageName: pkgName,
+    };
+    let outcome = 'completed';
+    let failure;
+    try {
+        await deps.extension?.onBeforeRunFunc(lifecycle);
+        const result = await runPikkuFunc('workflow', workflowMeta.name, workflowMeta.pikkuFuncId, {
+            singletonServices: getSingletonServices(),
+            wire,
+            createWireServices: getCreateWireServices(),
+            data: () => run.input,
+            packageName: pkgName ?? undefined,
+        });
+        await deps.updateRunStatus('completed', result);
+        await deps.onChildCompleted(result);
+    }
+    catch (error) {
+        failure = error;
+        if (error instanceof WorkflowAsyncException) {
+            outcome = 'interrupted';
+            throw error;
+        }
+        if (error instanceof WorkflowCancelledException) {
+            outcome = 'failed';
+            await deps.updateRunStatus('cancelled', undefined, {
+                message: error.message || 'Workflow cancelled',
+                stack: '',
+                code: 'WORKFLOW_CANCELLED',
+            });
+            await deps.onChildFailed(error);
+            throw error;
+        }
+        if (error instanceof WorkflowSuspendedException) {
+            outcome = 'interrupted';
+            await deps.updateRunStatus('suspended', undefined, {
+                message: error.message || 'Workflow suspended',
+                stack: '',
+                code: 'WORKFLOW_SUSPENDED',
+            });
+            throw error;
+        }
+        outcome = 'failed';
+        if ((await deps.failOrUnwind(error)) === 'unwinding')
+            return;
+        throw error;
+    }
+    finally {
+        await deps.extension?.onAfterRunFunc(lifecycle, outcome, failure);
+    }
+};

package/dist/wirings/workflow/workflow-queue-routing.js

@@ -1,6 +1,6 @@
 import { getSingletonServices, pikkuState } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
-import { DEFAULT_STEP_RETRIES } from './workflow-constants.js';
+import { DEFAULT_STEP_RETRIES, forwardStepName } from './workflow-constants.js';
 const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 export const resolveWorkflowConfig = () => {
     const workflow = getSingletonServices().config?.workflow;
@@ -24,7 +24,7 @@ const dedicatedQueueName = (prefix, name, strategy, fallback) => {
     return pikkuState(null, 'queue', 'meta')[dedicated] ? dedicated : fallback;
 };
 export const orchestratorQueueName = (strategy, workflowName) => dedicatedQueueName('wf-orchestrator-', workflowName, strategy, resolveWorkflowConfig().orchestratorQueueName);
-export const stepWorkerQueueName = (strategy, rpcName) => dedicatedQueueName('wf-step-', rpcName, strategy, resolveWorkflowConfig().stepWorkerQueueName);
+export const stepWorkerQueueName = (strategy, rpcName) => dedicatedQueueName('wf-step-', rpcName && forwardStepName(rpcName), strategy, resolveWorkflowConfig().stepWorkerQueueName);
 /**
  * How a step reaches its worker: on the queue, or here in the orchestrator.
  *
@@ -43,7 +43,7 @@ export const stepWorkerQueueName = (strategy, rpcName) => dedicatedQueueName('wf
  * and has a queue to reach ever asks.
  */
 export const stepDispatchTarget = async (rpcName, stepName, parentIsInline) => {
-    const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName];
+    const rpcFuncId = pikkuState(null, 'rpc', 'meta')[forwardStepName(rpcName)];
     const rpcMeta = typeof rpcFuncId === 'string'
         ? pikkuState(null, 'function', 'meta')[rpcFuncId]
         : undefined;

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

@@ -1,6 +1,7 @@
+import { WORKFLOW_TERMINAL_STATES } from './workflow-constants.js';
 /** A run's status with each step folded to its latest attempt. */
 export function summarizeRunStatus(run, history) {
-    const terminalStatuses = new Set(['completed', 'failed', 'cancelled']);
+    const terminalStatuses = WORKFLOW_TERMINAL_STATES;
     const stepMap = new Map();
     for (const step of history) {
         const existing = stepMap.get(step.stepName);
@@ -33,5 +34,16 @@ export function summarizeRunStatus(run, history) {
         error: run.error
             ? { message: run.error.message ?? 'Unknown error' }
             : undefined,
+        ...compensationOutcome(run),
     };
 }
+function compensationOutcome(run) {
+    const output = run.output;
+    if (run.status === 'compensated' && output?.restedAt) {
+        return { restedAt: output.restedAt };
+    }
+    if (run.status === 'compensation_failed' && output?.stuckSteps) {
+        return { stuckSteps: output.stuckSteps };
+    }
+    return {};
+}

package/dist/wirings/workflow/workflow-status-stream.js

@@ -11,6 +11,8 @@ const TERMINAL = new Set([
     'completed',
     'failed',
     'cancelled',
+    'compensated',
+    'compensation_failed',
 ]);
 const DEFAULT_POLL_INTERVAL_MS = 500;
 /**

package/dist/wirings/workflow/workflow-unwind-plan.d.ts

@@ -0,0 +1,38 @@
+import type { SerializedError } from '../../errors/serialized-error.js';
+import type { StepStatus } from './workflow.types.js';
+export interface UnwindRecord {
+    stepName: string;
+    rpcName?: string | null;
+    status: StepStatus;
+    createdAt: Date;
+    updatedAt: Date;
+    succeededAt?: Date;
+    failedAt?: Date;
+    result?: unknown;
+    error?: SerializedError;
+    childRunId?: string;
+    data?: unknown;
+    retries?: number;
+}
+export type UnwindStepState = 'done' | 'rested' | 'stuck' | 'blocked' | 'running' | 'ready' | 'waiting';
+export interface UnwindPlan {
+    candidates: UnwindRecord[];
+    states: Map<string, UnwindStepState>;
+    ready: UnwindRecord[];
+    stuck: Array<{
+        stepName: string;
+        error: string;
+    }>;
+    restedAt?: string;
+    childRestedAt?: string;
+    forwardInFlight: boolean;
+    settled: boolean;
+    compensated: boolean;
+}
+export interface PlanUnwindInput {
+    records: UnwindRecord[];
+    skip: ReadonlySet<string>;
+    hasCompensation: (record: UnwindRecord) => boolean;
+    isChildWorkflow: (record: UnwindRecord) => boolean;
+}
+export declare function planUnwind(input: PlanUnwindInput): UnwindPlan;

package/dist/wirings/workflow/workflow-unwind-plan.js

@@ -0,0 +1,120 @@
+import { isCompensationStepName, isMilestoneStepName, } from './workflow-constants.js';
+const IN_FLIGHT = new Set([
+    'pending',
+    'scheduled',
+    'running',
+]);
+const startedAt = (record) => record.createdAt.getTime();
+const finishedAt = (record) => (record.succeededAt ?? record.failedAt ?? record.updatedAt).getTime();
+export function planUnwind(input) {
+    const forward = input.records.filter((r) => !isCompensationStepName(r.stepName) && !isMilestoneStepName(r.stepName));
+    const compRows = new Map(input.records
+        .filter((r) => isCompensationStepName(r.stepName))
+        .map((r) => [r.stepName, r]));
+    const milestones = input.records
+        .filter((r) => isMilestoneStepName(r.stepName) && r.status === 'succeeded')
+        .sort((a, b) => finishedAt(b) - finishedAt(a) ||
+        input.records.indexOf(b) - input.records.indexOf(a));
+    const lastMilestone = milestones[0];
+    const forwardInFlight = forward.some((r) => IN_FLIGHT.has(r.status) && input.hasCompensation(r));
+    let candidates = forward.filter((r) => {
+        if (!r.rpcName || input.skip.has(r.stepName))
+            return false;
+        if (r.status === 'failed' && input.isChildWorkflow(r))
+            return false;
+        if (r.status !== 'succeeded' && r.status !== 'failed')
+            return false;
+        return input.hasCompensation(r);
+    });
+    if (lastMilestone) {
+        const at = finishedAt(lastMilestone);
+        candidates = candidates.filter((r) => finishedAt(r) > at ||
+            (finishedAt(r) === at &&
+                input.records.indexOf(r) > input.records.indexOf(lastMilestone)));
+    }
+    candidates.sort((a, b) => finishedAt(b) - finishedAt(a) ||
+        input.records.indexOf(b) - input.records.indexOf(a));
+    const order = (r) => input.records.indexOf(r);
+    const states = new Map();
+    const resolving = new Set();
+    const dependents = (x) => candidates.filter((y) => y !== x &&
+        startedAt(y) >= finishedAt(x) &&
+        (finishedAt(y) > finishedAt(x) ||
+            (finishedAt(y) === finishedAt(x) && order(y) > order(x))));
+    const resolve = (x) => {
+        const cached = states.get(x.stepName);
+        if (cached)
+            return cached;
+        if (resolving.has(x.stepName))
+            return 'waiting';
+        resolving.add(x.stepName);
+        const comp = compRows.get(`${x.stepName}:compensate`);
+        let state;
+        if (comp?.status === 'succeeded') {
+            const restedAt = comp.result
+                ?.restedAt;
+            state = restedAt ? 'rested' : 'done';
+        }
+        else if (comp?.status === 'failed') {
+            state = 'stuck';
+        }
+        else if (comp?.status === 'scheduled') {
+            state = 'running';
+        }
+        else {
+            const deps = dependents(x).map(resolve);
+            if (deps.some((s) => s === 'stuck' || s === 'blocked' || s === 'rested')) {
+                state = 'blocked';
+            }
+            else if (deps.every((s) => s === 'done')) {
+                state = 'ready';
+            }
+            else {
+                state = 'waiting';
+            }
+        }
+        resolving.delete(x.stepName);
+        states.set(x.stepName, state);
+        return state;
+    };
+    for (const c of candidates)
+        resolve(c);
+    const ready = forwardInFlight
+        ? []
+        : candidates.filter((c) => states.get(c.stepName) === 'ready');
+    const stuck = candidates
+        .filter((c) => states.get(c.stepName) === 'stuck')
+        .map((c) => ({
+        stepName: c.stepName,
+        error: compRows.get(`${c.stepName}:compensate`)?.error?.message ??
+            'compensation failed',
+    }));
+    const rested = candidates.find((c) => states.get(c.stepName) === 'rested');
+    const childRestedAt = rested
+        ? compRows.get(`${rested.stepName}:compensate`)?.result?.restedAt
+        : undefined;
+    const open = candidates.some((c) => {
+        const s = states.get(c.stepName);
+        return s === 'ready' || s === 'waiting' || s === 'running';
+    });
+    const compensated = candidates.some((c) => {
+        const s = states.get(c.stepName);
+        return s === 'done' || s === 'rested';
+    });
+    return {
+        candidates,
+        states,
+        ready,
+        stuck,
+        restedAt: lastMilestone
+            ? milestoneNameOf(lastMilestone.stepName)
+            : undefined,
+        childRestedAt,
+        forwardInFlight,
+        settled: !forwardInFlight && !open,
+        compensated,
+    };
+}
+function milestoneNameOf(stepName) {
+    return stepName.slice(stepName.indexOf(':') + 1);
+}

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

@@ -4,7 +4,7 @@ import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 import type { LeaseService } from '../../services/lease-service.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, MilestoneStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -38,7 +38,7 @@ export interface WorkflowPlannedStep {
     stepName: string;
     displayName?: string;
 }
-export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled';
+export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled' | 'compensating' | 'compensated' | 'compensation_failed';
 export type WorkflowVersionStatus = 'draft' | 'active' | 'declined';
 export type StepStatus = 'pending' | 'running' | 'scheduled' | 'succeeded' | 'failed' | 'suspended';
 export interface WorkflowRun {
@@ -75,6 +75,8 @@ export interface StepState {
     createdAt: Date;
     updatedAt: Date;
     childRunId?: string;
+    /** True for the row that undoes `<stepName>` rather than running it. */
+    compensating?: boolean;
     /**
      * When the dispatch that claimed this step stops owning it. The holder pushes
      * it forward while it is still working, so a lapsed lease means the worker is
@@ -104,6 +106,11 @@ export interface WorkflowRunStatus {
     error?: {
         message: string;
     };
+    restedAt?: string;
+    stuckSteps?: Array<{
+        stepName: string;
+        error: string;
+    }>;
 }
 export interface WorkflowRunService {
     listRuns(options?: {