@pikku/inspector 0.12.98 → 0.12.99

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.12.99
+
+### Patch Changes
+
+- ce3e5f5: Saga compensation for workflows. A function declares `compensate` inline; when a workflow step fails, completed steps are undone newest-first as durable `<step>:compensate` steps. New run statuses `compensating`, `compensated` and `compensation_failed`, `workflow.milestone(name)` to bound the unwind, `{ compensate: false }` to opt a call out, nested-workflow unwinding, and `PikkuWorkflowService.cancelRun` which unwinds too. Graph nodes replace `onError` with `recover` (`nodeId`, `nodeId[]` or `'ignore'`), exposing the error as `wire.graph.recoveringFrom`. **Breaking:** the DSL `onError` step option and the graph `onError` node field are removed; `getRunSteps` is now abstract on `PikkuWorkflowService`.
+- Updated dependencies [ce3e5f5]
+- Updated dependencies [fb36c37]
+  - @pikku/core@0.12.135
+
 ## 0.12.98
 
 ### Patch Changes

package/dist/add/add-functions.js

@@ -3,6 +3,7 @@ import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
 import { extractFunctionName, funcIdToTypeName, } from '../utils/extract-function-name.js';
 import { extractFunctionNode } from '../utils/extract-function-node.js';
 import { extractUsedWires } from '../utils/extract-services.js';
+import { getPropertyAssignmentInitializer } from '../utils/type-utils.js';
 import { collectInvokedRpcNames } from './add-rpc-invocations.js';
 import { collectStartedWorkflows } from './collect-started-workflows.js';
 import { formatVersionedId, parseVersionedId } from '@pikku/core/utils';
@@ -721,7 +722,43 @@ export const addFunctions = (logger, node, checker, state, options) => {
             services.optimized = false;
         }
     }
-    const wires = extractUsedWires(handler, 2);
+    let wires = extractUsedWires(handler, 2);
+    // `compensate` runs as the function's own sibling step, deployed wherever the
+    // function is, so what it needs is what the function needs.
+    const compensateInitializer = objectNode
+        ? getPropertyAssignmentInitializer(objectNode, 'compensate', true, checker)
+        : undefined;
+    const compensateNode = compensateInitializer &&
+        (ts.isArrowFunction(compensateInitializer) ||
+            ts.isFunctionExpression(compensateInitializer)
+            ? compensateInitializer
+            : undefined);
+    if (compensateNode) {
+        const compensateServices = compensateNode.parameters[0];
+        if (compensateServices) {
+            if (ts.isObjectBindingPattern(compensateServices.name)) {
+                for (const elem of compensateServices.name.elements) {
+                    const original = elem.propertyName && ts.isIdentifier(elem.propertyName)
+                        ? elem.propertyName.text
+                        : ts.isIdentifier(elem.name)
+                            ? elem.name.text
+                            : undefined;
+                    if (original && !services.services.includes(original)) {
+                        services.services.push(original);
+                    }
+                }
+            }
+            else if (ts.isIdentifier(compensateServices.name) &&
+                !compensateServices.name.text.startsWith('_')) {
+                services.optimized = false;
+            }
+        }
+        const compensateWires = extractUsedWires(compensateNode, 2);
+        wires = {
+            optimized: wires.optimized && compensateWires.optimized,
+            wires: [...new Set([...wires.wires, ...compensateWires.wires])],
+        };
+    }
     const invoked = collectInvokedRpcNames(handler.body);
     for (const call of invoked.dynamic) {
         logger.warn(`• ${pikkuFuncId} calls ${call} with a computed name — the deploy planner cannot bind its unit to the callee's, so the call fails with "No service binding" if the two are deployed apart. Use a literal RPC name.`);
@@ -1031,6 +1068,7 @@ export const addFunctions = (logger, node, checker, state, options) => {
         workflowQueued: workflowQueued === true ? true : undefined,
         workflowRetries: workflowRetries ?? undefined,
         workflowTimeout: workflowTimeout ?? undefined,
+        compensate: compensateInitializer ? true : undefined,
         scenarioStepSurfaces,
         scenarioStepRequiresActor,
         // `persona` is the default reading of an unmarked step, so it is left off

package/dist/add/add-workflow.js

@@ -80,11 +80,6 @@ export function collectInvokedRPCs(steps, rpcs) {
     for (const step of steps) {
         if (step.type === 'rpc' && step.rpcName) {
             rpcs.add(step.rpcName);
-            // The compensation handler is invoked at runtime too, so it has to be
-            // wired like any other step.
-            if (step.options?.onError) {
-                rpcs.add(step.options.onError);
-            }
         }
         else if (step.type === 'scenarioStep' && step.stepFunc) {
             // Steps are bundled like RPCs — the runner calls them through

package/dist/utils/workflow/derive-workflow-plan.js

@@ -70,6 +70,12 @@ function collectNamedSteps(steps) {
                     displayName: reasonToLabel(step.reason),
                 });
                 break;
+            case 'milestone':
+                planned.push({
+                    stepName: `__milestone__:${step.name}`,
+                    displayName: reasonToLabel(step.name),
+                });
+                break;
             case 'approval':
                 // Same as suspend, but namespaced `__workflow_approval:` to match the
                 // runtime's separate step key.

package/dist/utils/workflow/dsl/deserialize-dsl-workflow.js

@@ -142,7 +142,9 @@ function fanoutBodyToCode(entryNodeId, nodes, indent, itemVar) {
             const stepName = node.stepName || `Call ${node.rpcName}`;
             const input = (node.input || {});
             const inputCode = inputToCode(input, indent, itemVar);
-            const options = node.options ? optionsToCode(node.options) : '';
+            const options = node.options || node.compensate === false
+                ? optionsToCode(node.options ?? {}, node.compensate === false ? false : undefined)
+                : '';
             const doCall = `await workflow.do('${escapeSingleQuotes(stepName)}', '${node.rpcName}', ${inputCode}${options ? `, ${options}` : ''})`;
             lines.push(node.outputVar
                 ? `${indent}const ${node.outputVar} = ${doCall}`
@@ -163,19 +165,6 @@ function fanoutBodyToCode(entryNodeId, nodes, indent, itemVar) {
  */
 function collectChildNodeIds(nodes) {
     const owned = new Set();
-    // An error handler belongs to the step that routes to it, not to the main
-    // flow — emitting it top-level would turn compensation into a step that
-    // always runs.
-    for (const node of Object.values(nodes)) {
-        const onError = node.onError;
-        if (typeof onError === 'string') {
-            owned.add(onError);
-        }
-        else if (Array.isArray(onError)) {
-            for (const handlerId of onError)
-                owned.add(handlerId);
-        }
-    }
     const walk = (entry, exit) => {
         const seen = new Set();
         let currentId = entry;
@@ -231,20 +220,6 @@ function bindingPrefix(outputVar) {
         ? `const ${outputVar} = `
         : '';
 }
-/**
- * Resolve a node's `onError` node id back to the rpc name the DSL author wrote.
- */
-function onErrorRpcNameOf(node, nodes) {
-    const onError = node.onError;
-    const handlerId = Array.isArray(onError) ? onError[0] : onError;
-    if (typeof handlerId !== 'string') {
-        return undefined;
-    }
-    const handler = nodes[handlerId];
-    return handler && 'rpcName' in handler
-        ? handler.rpcName
-        : undefined;
-}
 /**
  * A duration is `string | number` ('5s' or 5000). Quoting a number would change
  * the value the runtime parses, so only strings get quotes.
@@ -267,17 +242,17 @@ function caseValueToCode(value) {
 /**
  * Convert options to code
  */
-function optionsToCode(options, onErrorRpcName) {
+function optionsToCode(options, compensate) {
     const parts = [];
-    if (onErrorRpcName) {
-        parts.push(`onError: '${escapeSingleQuotes(onErrorRpcName)}'`);
-    }
     if (options.retries !== undefined) {
         parts.push(`retries: ${options.retries}`);
     }
     if (options.retryDelay !== undefined) {
         parts.push(`retryDelay: ${durationToCode(options.retryDelay)}`);
     }
+    if (compensate === false) {
+        parts.push('compensate: false');
+    }
     return parts.length > 0 ? `{ ${parts.join(', ')} }` : '';
 }
 /**
@@ -422,9 +397,9 @@ function nodeToCode(node, nodes, indent, conditionalVars = new Set(), isInsideBr
         const outputVar = node.outputVar;
         let doCall = `await workflow.do('${stepName}', '${node.rpcName}', ${inputCode}`;
         // Add options if present
-        const onErrorRpc = onErrorRpcNameOf(node, nodes);
-        if (node.options || onErrorRpc) {
-            const optCode = optionsToCode(node.options ?? {}, onErrorRpc);
+        const noCompensate = node.compensate === false ? false : undefined;
+        if (node.options || noCompensate === false) {
+            const optCode = optionsToCode(node.options ?? {}, noCompensate);
             if (optCode) {
                 doCall += `, ${optCode}`;
             }
@@ -459,6 +434,10 @@ function nodeToCode(node, nodes, indent, conditionalVars = new Set(), isInsideBr
                 lines.push(`${indent}await workflow.suspend('${escapeSingleQuotes(String(flowNode.reason ?? ''))}')`);
                 lines.push('');
                 break;
+            case 'milestone':
+                lines.push(`${indent}await workflow.milestone('${escapeSingleQuotes(String(flowNode.reason ?? ''))}')`);
+                lines.push('');
+                break;
             case 'approval': {
                 const approvalCall = `await workflow.approval('${escapeSingleQuotes(String(flowNode.reason ?? ''))}')`;
                 lines.push(flowNode.outputVar
@@ -537,8 +516,8 @@ function nodeToCode(node, nodes, indent, conditionalVars = new Set(), isInsideBr
                     const input = (childNode.input || {});
                     const inputCode = inputToCode(input, indent + '  ');
                     let call = `workflow.do('${stepName}', '${childNode.rpcName}', ${inputCode}`;
-                    if (childNode.options) {
-                        const optCode = optionsToCode(childNode.options);
+                    if (childNode.options || childNode.compensate === false) {
+                        const optCode = optionsToCode(childNode.options ?? {}, childNode.compensate === false ? false : undefined);
                         if (optCode) {
                             call += `, ${optCode}`;
                         }
@@ -1021,14 +1000,20 @@ export function deserializeGraphWorkflow(workflow, options = {}) {
                 configParts.push(`next: ${nextCode}`);
             }
         }
-        // onError, retries and retryDelay are all honoured by the graph runner,
-        // so dropping them here silently changes how the workflow behaves.
-        if ('onError' in node && node.onError) {
-            const onErrorCode = nextToCode(node.onError, workflow.nodes, flowNodeIds);
-            if (onErrorCode) {
-                configParts.push(`onError: ${onErrorCode}`);
+        // recover, compensate, retries and retryDelay are all honoured by the
+        // graph runner, so dropping them here silently changes how the workflow
+        // behaves.
+        if ('recover' in node && node.recover) {
+            const recoverCode = node.recover === 'ignore'
+                ? `'ignore'`
+                : nextToCode(node.recover, workflow.nodes, flowNodeIds);
+            if (recoverCode) {
+                configParts.push(`recover: ${recoverCode}`);
             }
         }
+        if ('compensate' in node && node.compensate === false) {
+            configParts.push('compensate: false');
+        }
         if ('options' in node && node.options) {
             const { retries, retryDelay } = node.options;
             if (retries !== undefined) {

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, isScenarioExpectationCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowExpectEventuallyCall, isScenarioStepCall, isScenarioExpectationCall, getScenarioStepPhase, DYNAMIC_SCENARIO_STEP_TARGET, extractActorFromOptions, isWorkflowSleepCall, isWorkflowSuspendCall, isWorkflowMilestoneCall, isWorkflowApprovalCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
 /**
@@ -518,6 +518,9 @@ function extractExpressionStatement(statement, context) {
         if (isWorkflowSuspendCall(call, context.checker)) {
             return extractSuspendStep(call, context);
         }
+        if (isWorkflowMilestoneCall(call, context.checker)) {
+            return extractMilestoneStep(call, context);
+        }
         if (isWorkflowApprovalCall(call, context.checker)) {
             const step = extractApprovalStep(call, context, outputVar);
             // Unlike suspend, an approval yields a value, so a downstream step can
@@ -696,13 +699,13 @@ function extractStepOptions(optionsNode, context) {
                     // Ignore extraction errors for retryDelay
                 }
             }
-            else if (propName === 'onError') {
-                if (ts.isStringLiteral(prop.initializer)) {
-                    options.onError = prop.initializer.text;
+            else if (propName === 'compensate') {
+                if (prop.initializer.kind === ts.SyntaxKind.FalseKeyword) {
+                    options.compensate = false;
                 }
                 else {
                     context.errors.push({
-                        message: 'onError must be a literal RPC name so it can be wired and drawn in the graph.',
+                        message: "compensate on a call site can only be `false`: a step's compensation is declared on the function itself.",
                         node: prop.initializer,
                     });
                 }
@@ -786,6 +789,27 @@ function extractSuspendStep(call, context) {
         return null;
     }
 }
+/**
+ * Extract milestone step from workflow.milestone() call
+ */
+function extractMilestoneStep(call, context) {
+    const args = call.arguments;
+    if (args.length < 1)
+        return null;
+    try {
+        return {
+            type: 'milestone',
+            name: extractStringLiteral(args[0], context.checker),
+        };
+    }
+    catch (error) {
+        context.errors.push({
+            message: `Failed to extract milestone step: ${error instanceof Error ? error.message : String(error)}`,
+            node: call,
+        });
+        return null;
+    }
+}
 /**
  * Extract approval step from workflow.approval() call
  */
@@ -1146,6 +1170,13 @@ function extractFanoutBodyStep(stmt, childContext, body) {
             }
             return;
         }
+        if (isWorkflowMilestoneCall(call, childContext.checker)) {
+            const milestoneStep = extractMilestoneStep(call, childContext);
+            if (milestoneStep) {
+                body.push(milestoneStep);
+            }
+            return;
+        }
         if (isScenarioStepCall(call)) {
             const scenarioStep = extractScenarioStep(call, childContext);
             if (scenarioStep) {

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -57,6 +57,10 @@ export declare function isWorkflowSleepCall(node: ts.CallExpression, checker: ts
  * Check if a call expression is workflow.suspend()
  */
 export declare function isWorkflowSuspendCall(node: ts.CallExpression, _checker: ts.TypeChecker): boolean;
+/**
+ * Check if a call expression is workflow.milestone()
+ */
+export declare function isWorkflowMilestoneCall(node: ts.CallExpression, _checker: ts.TypeChecker): boolean;
 /**
  * Check if a call expression is workflow.approval()
  */

package/dist/utils/workflow/dsl/patterns.js

@@ -133,6 +133,17 @@ export function isWorkflowSuspendCall(node, _checker) {
     return (propAccess.name.text === 'suspend' &&
         isWorkflowWireIdentifier(propAccess.expression));
 }
+/**
+ * Check if a call expression is workflow.milestone()
+ */
+export function isWorkflowMilestoneCall(node, _checker) {
+    if (!ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const propAccess = node.expression;
+    return (propAccess.name.text === 'milestone' &&
+        isWorkflowWireIdentifier(propAccess.expression));
+}
 /**
  * Check if a call expression is workflow.approval()
  */

package/dist/utils/workflow/graph/convert-dsl-to-graph.js

@@ -85,21 +85,9 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
                     retries: step.options.retries,
                     retryDelay: step.options.retryDelay,
                 };
-            }
-            // An onError handler is written as an rpc name, but the graph routes to
-            // node ids — materialise a node for it so the console has something to
-            // draw the error edge to, exactly as in a hand-authored graph.
-            if (step.options?.onError) {
-                const handlerId = `${nodeId}_onError`;
-                node.onError = handlerId;
-                return [
-                    node,
-                    {
-                        nodeId: handlerId,
-                        rpcName: step.options.onError,
-                        stepName: `${step.stepName} (on error)`,
-                    },
-                ];
+                if (step.options.compensate === false) {
+                    node.compensate = false;
+                }
             }
             return [node];
         }
@@ -161,6 +149,15 @@ function convertStepToNode(step, index, steps, nodeIdPrefix = 'step') {
             };
             return [node];
         }
+        case 'milestone': {
+            const node = {
+                nodeId,
+                flow: 'milestone',
+                reason: step.name,
+                next: nextNodeId,
+            };
+            return [node];
+        }
         case 'approval': {
             // Unlike `suspend` — which has no output and so is deliberately absent
             // from the graph — an approval yields a value a later step can reference,

package/dist/utils/workflow/graph/serialize-workflow-graph.d.ts

@@ -18,7 +18,8 @@ export declare function serializeWorkflowGraph(definition: {
         } | ((ref: any) => unknown);
         mode?: 'parallel' | 'sequential';
         next?: string | string[] | Record<string, string | string[]>;
-        onError?: string | string[];
+        recover?: string | string[] | 'ignore';
+        compensate?: false;
         notes?: string;
     }>;
 }, options?: {
@@ -36,7 +37,8 @@ export declare function deserializeWorkflowGraph(serialized: SerializedWorkflowG
         rpcName: string;
         input: Record<string, unknown | DataRef>;
         next?: SerializedNext;
-        onError?: string | string[];
+        recover?: string | string[] | 'ignore';
+        compensate?: false;
     }>;
     entryNodeIds: string[];
 };

package/dist/utils/workflow/graph/serialize-workflow-graph.js

@@ -115,7 +115,8 @@ export function serializeWorkflowGraph(definition, options) {
             rpcName,
             input,
             next: serializeNext(node.next),
-            onError: node.onError,
+            recover: node.recover,
+            compensate: node.compensate,
         };
         const forEach = serializeForEach(node.forEach, createRef);
         if (forEach) {
@@ -158,7 +159,8 @@ export function deserializeWorkflowGraph(serialized) {
                 rpcName: funcNode.rpcName,
                 input: funcNode.input ?? {},
                 next: funcNode.next,
-                onError: funcNode.onError,
+                recover: funcNode.recover,
+                compensate: funcNode.compensate,
             };
         }
     }

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

@@ -66,7 +66,7 @@ export interface NodeOptions {
 /**
  * Flow node types for control flow (no RPC call)
  */
-export type FlowType = 'sleep' | 'suspend' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
+export type FlowType = 'sleep' | 'suspend' | 'milestone' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
 import type { ContextVariable, WorkflowContext, WorkflowPlannedStep } from '@pikku/core/workflow';
 import type { ScenarioStepPhase } from '@pikku/core/scenario';
 export type { ContextVariable, WorkflowContext };
@@ -80,8 +80,10 @@ interface BaseNode {
     stepName?: string;
     /** Next node(s) - simple, parallel, or conditional */
     next?: SerializedNext;
-    /** Error routing - node(s) to execute on error */
-    onError?: string | string[];
+    /** What to do when this node fails: run these nodes, or 'ignore' to carry on. */
+    recover?: string | string[] | 'ignore';
+    /** Leave this node out of the saga unwind. */
+    compensate?: false;
     /** Execution options */
     options?: NodeOptions;
     /** Free-text node documentation. Non-semantic — excluded from graphHash. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.98",
+  "version": "0.12.99",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -54,10 +54,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.132"
+    "@pikku/core": "^0.12.135"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.132",
+    "@pikku/core": "^0.12.135",
     "@types/node": "^24.13.3"
   },
   "engines": {