@pikku/core 0.12.37 → 0.12.39

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

@@ -1,4 +1,4 @@
-import { WorkflowAsyncException, WorkflowSuspendedException, } from '../pikku-workflow-service.js';
+import { WorkflowAsyncException, WorkflowSuspendedException, DEFAULT_STEP_RETRIES, } from '../pikku-workflow-service.js';
 import { pikkuState, getSingletonServices } from '../../../pikku-state.js';
 import { RPCNotFoundError } from '../../rpc/rpc-runner.js';
 export class ChildWorkflowStartedException extends Error {
@@ -22,6 +22,13 @@ function buildTemplateRegex(nodeId) {
         .join('.+');
     return new RegExp(`^${escaped}$`);
 }
+/** Strip a trailing revisit ordinal (`node#2` → `node`); leaves other names as-is. */
+function stripInstanceOrdinal(name) {
+    const hash = name.lastIndexOf('#');
+    if (hash <= 0)
+        return name;
+    return /^\d+$/.test(name.slice(hash + 1)) ? name.slice(0, hash) : name;
+}
 function remapStepNamesToNodeIds(stepNames, nodes, graphName) {
     const templatePatterns = new Map();
     for (const nodeId of Object.keys(nodes)) {
@@ -29,14 +36,16 @@ function remapStepNamesToNodeIds(stepNames, nodes, graphName) {
         if (regex)
             templatePatterns.set(nodeId, regex);
     }
-    if (templatePatterns.size === 0)
-        return stepNames;
     return stepNames.map((name) => {
         if (nodes[name])
             return name;
+        // Revisit instance (`node#N`) maps to its logical node.
+        const base = stripInstanceOrdinal(name);
+        if (base !== name && nodes[base])
+            return base;
         const matches = [];
         for (const [nodeId, regex] of templatePatterns) {
-            if (regex.test(name))
+            if (regex.test(base))
                 matches.push(nodeId);
         }
         if (matches.length > 1) {
@@ -48,6 +57,91 @@ function remapStepNamesToNodeIds(stepNames, nodes, graphName) {
         return name;
     });
 }
+const ENTRY_FROM = '__entry__';
+/** Whether `target` can reach `source` over `next` edges — i.e. an edge
+ *  source→target closes a cycle (a back-edge), vs a plain forward edge. */
+function closesCycle(source, target, nodes) {
+    const seen = new Set();
+    const stack = [target];
+    while (stack.length) {
+        const cur = stack.pop();
+        if (cur === source)
+            return true;
+        if (seen.has(cur))
+            continue;
+        seen.add(cur);
+        for (const next of normalizeNodeTargets(nodes[cur]?.next))
+            stack.push(next);
+    }
+    return false;
+}
+/**
+ * Decide which next steps to fire this tick. Two kinds of edge:
+ *  - forward edge → node-once: fire the target only if it has no instance yet,
+ *    so converging edges (joins) collapse to a single run (unchanged behavior).
+ *  - back-edge (target can reach the source, closing a cycle) → revisit: fire a
+ *    fresh ordinal instance (`target#1`, …), edge-once on `from → target` so it
+ *    doesn't re-fire every tick. Cycles terminate when branch routing stops
+ *    looping back; a node always records the predecessor it was reached from.
+ */
+function planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, graphName) {
+    const toLogical = (name) => remapStepNamesToNodeIds([name], nodes, graphName)[0];
+    const countByLogical = {};
+    const consumed = new Set();
+    for (const inst of instances) {
+        const logical = toLogical(inst.stepName);
+        countByLogical[logical] = (countByLogical[logical] ?? 0) + 1;
+        consumed.add(`${inst.fromStepName ?? ENTRY_FROM}->${logical}`);
+    }
+    const completed = instances.filter((i) => i.status === 'succeeded');
+    const completedLogical = new Set(completed.map((i) => toLogical(i.stepName)));
+    // Available edges: entry edges + each completed instance's resolved `next`.
+    const edges = [];
+    for (const entryId of entryNodeIds) {
+        edges.push({ fromKey: ENTRY_FROM, target: entryId });
+    }
+    for (const inst of completed) {
+        const fromLogical = toLogical(inst.stepName);
+        const node = nodes[fromLogical];
+        if (!node?.next)
+            continue;
+        for (const target of resolveNextFromConfig(node.next, branchByStep[inst.stepName])) {
+            edges.push({ from: inst.stepName, fromKey: inst.stepName, fromLogical, target });
+        }
+    }
+    const toFire = [];
+    let blockedWaiting = false;
+    for (const edge of edges) {
+        const target = edge.target;
+        const edgeKey = `${edge.fromKey}->${target}`;
+        if (consumed.has(edgeKey))
+            continue;
+        const visits = countByLogical[target] ?? 0;
+        const isBackEdge = edge.fromLogical !== undefined &&
+            closesCycle(edge.fromLogical, target, nodes);
+        // Forward edge into an already-started node = a join; node-once.
+        if (!isBackEdge && visits > 0) {
+            consumed.add(edgeKey);
+            continue;
+        }
+        if (!areDependenciesSatisfied(nodes[target] ?? {}, completedLogical)) {
+            blockedWaiting = true;
+            continue;
+        }
+        toFire.push({
+            logical: target,
+            instanceKey: visits === 0 ? target : `${target}#${visits}`,
+            fromStepName: edge.from,
+        });
+        countByLogical[target] = visits + 1;
+        consumed.add(edgeKey);
+    }
+    return {
+        toFire,
+        hasInFlight: instances.some((i) => i.status !== 'succeeded'),
+        blockedWaiting,
+    };
+}
 function remapBranchKeys(branchKeys, nodes, graphName) {
     const templatePatterns = new Map();
     for (const nodeId of Object.keys(nodes)) {
@@ -257,13 +351,15 @@ 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, nodeConfig) {
+async function queueGraphNode(workflowService, runId, _graphName, nodeId, rpcName, input, nodeConfig, fromStepName) {
+    // Default to the workflow-wide retry policy when the node sets none, so the
+    // persisted step retries match the queue `attempts` (see resolveStepJobOptions).
     const stepOptions = {
-        retries: nodeConfig?.retries ?? 0,
+        retries: nodeConfig?.retries ?? DEFAULT_STEP_RETRIES,
         retryDelay: nodeConfig?.retryDelay,
     };
-    await workflowService.insertStepState(runId, nodeId, rpcName, input, stepOptions);
-    await workflowService.queueStepWorker(runId, nodeId, rpcName, input, stepOptions);
+    await workflowService.insertStepState(runId, nodeId, rpcName, input, stepOptions, fromStepName);
+    await workflowService.queueStepWorker(runId, nodeId, rpcName, input, stepOptions, fromStepName);
 }
 export async function continueGraph(workflowService, runId, graphName, overrideMeta) {
     const meta = overrideMeta ?? getWorkflowMeta(graphName);
@@ -272,11 +368,12 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
     }
     const nodes = meta.nodes;
     validateGraphReferences(graphName, nodes, meta.entryNodeIds ?? []);
-    const { completedNodeIds: rawCompleted, failedNodeIds: rawFailed, branchKeys: rawBranch, } = await workflowService.getCompletedGraphState(runId);
-    const completedNodeIds = remapStepNamesToNodeIds(rawCompleted, nodes, graphName);
-    const completedNodeIdSet = new Set(completedNodeIds);
+    const { completedNodeIds: rawCompleted, failedNodeIds: rawFailed, branchKeys: branchByStep, } = await workflowService.getCompletedGraphState(runId);
+    // Validate step/branch names map to unambiguous nodes (planning keys
+    // physically; these calls only surface ambiguous template configs).
+    remapStepNamesToNodeIds(rawCompleted, nodes, graphName);
+    remapBranchKeys(branchByStep, nodes, graphName);
     const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName);
-    const branchKeys = remapBranchKeys(rawBranch, nodes, graphName);
     if (failedNodeIds.length > 0) {
         const failedNode = failedNodeIds[0];
         await workflowService.updateRunStatus(runId, 'failed', undefined, {
@@ -290,54 +387,36 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
     if (currentRun?.status === 'suspended') {
         return;
     }
-    const candidateNodes = new Set();
-    for (const nodeId of completedNodeIds) {
-        const node = nodes[nodeId];
-        if (!node?.next)
-            continue;
-        const nextNodes = resolveNextFromConfig(node.next, branchKeys[nodeId]);
-        for (const nextNode of nextNodes) {
-            candidateNodes.add(nextNode);
-        }
-    }
-    for (const entryId of meta.entryNodeIds ?? []) {
-        candidateNodes.add(entryId);
-    }
-    if (candidateNodes.size === 0 && completedNodeIds.length > 0) {
-        await workflowService.updateRunStatus(runId, 'completed');
-        return;
-    }
-    const unstartedNodes = await workflowService.getNodesWithoutSteps(runId, [
-        ...candidateNodes,
-    ]);
-    const nodesToQueue = unstartedNodes.filter((nodeId) => {
-        const node = nodes[nodeId];
-        return node && areDependenciesSatisfied(node, completedNodeIdSet);
-    });
-    if (nodesToQueue.length === 0) {
-        const allRpcNodes = Object.entries(nodes)
-            .filter(([_, n]) => n.rpcName)
-            .map(([id]) => id);
-        const allRpcCompleted = allRpcNodes.every((id) => completedNodeIdSet.has(id));
-        if (allRpcCompleted) {
+    const instances = await workflowService.getStepInstances(runId);
+    const plan = planGraphTransitions(nodes, instances, branchByStep, meta.entryNodeIds ?? [], graphName);
+    if (plan.toFire.length === 0) {
+        // Nothing left to fire and nothing running/blocked → the run is done.
+        if (!plan.hasInFlight && !plan.blockedWaiting) {
             await workflowService.updateRunStatus(runId, 'completed');
         }
         return;
     }
     const run = await workflowService.getRun(runId);
     const triggerInput = run?.input;
-    for (const nodeId of nodesToQueue) {
-        const node = nodes[nodeId];
+    for (const fire of plan.toFire) {
+        const node = nodes[fire.logical];
         if (!node?.rpcName)
             continue;
         const referencedNodeIds = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
         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, node);
+        await queueGraphNode(workflowService, runId, graphName, fire.instanceKey, node.rpcName, resolvedInput, node, fire.fromStepName);
     }
 }
-export async function executeGraphStep(workflowService, rpcService, runId, stepId, nodeId, rpcName, data, graphName) {
+/**
+ * Invoke a graph node's RPC with the graph + workflow wires, capturing any
+ * branch the node selects and persisting it. Shared by the queued
+ * (executeGraphStep) and inline (executeGraphNodeInline) executors so both build
+ * the wire and record the branch identically — only their child-workflow and
+ * onError handling differs around this call.
+ */
+async function invokeGraphNodeRpc(workflowService, rpcService, runId, stepId, nodeId, rpcName, input, graphName) {
     const wireState = {};
     const graphWire = {
         runId,
@@ -349,6 +428,16 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
         setState: (name, value) => workflowService.updateRunState(runId, name, value),
         getState: () => workflowService.getRunState(runId),
     };
+    const result = await rpcService.rpcWithWire(rpcName, input, {
+        graph: graphWire,
+        workflow: workflowService.createWorkflowWire(graphName, runId, rpcService),
+    });
+    if (wireState.branchKey) {
+        await workflowService.setBranchTaken(stepId, wireState.branchKey);
+    }
+    return result;
+}
+export async function executeGraphStep(workflowService, rpcService, runId, stepId, nodeId, rpcName, data, graphName) {
     try {
         let result;
         const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
@@ -377,13 +466,7 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
             }
         }
         else {
-            result = await rpcService.rpcWithWire(rpcName, data, {
-                graph: graphWire,
-                workflow: workflowService.createWorkflowWire(graphName, runId, rpcService),
-            });
-        }
-        if (wireState.branchKey) {
-            await workflowService.setBranchTaken(stepId, wireState.branchKey);
+            result = await invokeGraphNodeRpc(workflowService, rpcService, runId, stepId, nodeId, rpcName, data, graphName);
         }
         return result;
     }
@@ -427,24 +510,16 @@ export async function onGraphNodeComplete(workflowService, runId, graphName) {
 export async function runFromMeta(workflowService, runId, meta, _rpcService) {
     await continueGraph(workflowService, runId, meta.name, meta);
 }
-async function executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, input, nodes) {
+async function executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, instanceKey, input, nodes, fromStepName) {
     const node = nodes[nodeId];
     if (!node)
         return;
     const rpcName = node.rpcName;
-    const stepState = await workflowService.insertStepState(runId, nodeId, rpcName, input, { retries: node.retries ?? 0, retryDelay: node.retryDelay });
+    // Persist under the physical instance key (node, node#1 … for revisits) and
+    // record the predecessor — same as the queued path (queueGraphNode), so an
+    // inline graph run stores identical step rows + provenance.
+    const stepState = await workflowService.insertStepState(runId, instanceKey, rpcName, input, { retries: node.retries ?? 0, retryDelay: node.retryDelay }, fromStepName);
     await workflowService.setStepRunning(stepState.stepId);
-    const wireState = {};
-    const graphWire = {
-        runId,
-        graphName,
-        nodeId,
-        branch: (key) => {
-            wireState.branchKey = key;
-        },
-        setState: (name, value) => workflowService.updateRunState(runId, name, value),
-        getState: () => workflowService.getRunState(runId),
-    };
     try {
         let result;
         const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
@@ -467,13 +542,7 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
             result = childRun?.output;
         }
         else {
-            result = await rpcService.rpcWithWire(rpcName, input, {
-                graph: graphWire,
-                workflow: workflowService.createWorkflowWire(graphName, runId, rpcService),
-            });
-        }
-        if (wireState.branchKey) {
-            await workflowService.setBranchTaken(stepState.stepId, wireState.branchKey);
+            result = await invokeGraphNodeRpc(workflowService, rpcService, runId, stepState.stepId, nodeId, rpcName, input, graphName);
         }
         await workflowService.setStepResult(stepState.stepId, result);
     }
@@ -495,19 +564,25 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
             const errorNodes = Array.isArray(node.onError)
                 ? node.onError
                 : [node.onError];
-            await Promise.all(errorNodes.map((errorNodeId) => executeGraphNodeInline(workflowService, rpcService, runId, graphName, errorNodeId, { error: { message: error.message } }, nodes)));
+            await Promise.all(errorNodes.map((errorNodeId) => executeGraphNodeInline(workflowService, rpcService, runId, graphName, errorNodeId, errorNodeId, { error: { message: error.message } }, nodes, nodeId)));
             return;
         }
         throw error;
     }
 }
 async function continueGraphInline(workflowService, rpcService, runId, graphName, nodes, triggerInput, entryNodeIds) {
+    // Drive the run to completion in-process using the SAME planner as the queued
+    // path (continueGraph): each loop plans the next wave of transitions, executes
+    // them inline (vs queueGraphNode dispatch), then re-plans. Sharing the planner
+    // gives the inline path joins, cycle revisits and fromStepName provenance
+    // identical to the queue — instead of a second, weaker traversal.
     while (true) {
-        const { completedNodeIds: rawCompleted, failedNodeIds: rawFailed, branchKeys: rawBranch, } = await workflowService.getCompletedGraphState(runId);
-        const completedNodeIds = remapStepNamesToNodeIds(rawCompleted, nodes, graphName);
-        const completedNodeIdSet = new Set(completedNodeIds);
+        const { failedNodeIds: rawFailed, branchKeys: branchByStep, completedNodeIds: rawCompleted, } = await workflowService.getCompletedGraphState(runId);
+        // Validate step/branch names map to unambiguous nodes (planning keys
+        // physically; these calls only surface ambiguous template configs).
+        remapStepNamesToNodeIds(rawCompleted, nodes, graphName);
+        remapBranchKeys(branchByStep, nodes, graphName);
         const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName);
-        const branchKeys = remapBranchKeys(rawBranch, nodes, graphName);
         if (failedNodeIds.length > 0) {
             const failedNode = failedNodeIds[0];
             await workflowService.updateRunStatus(runId, 'failed', undefined, {
@@ -517,46 +592,33 @@ async function continueGraphInline(workflowService, rpcService, runId, graphName
             });
             return;
         }
-        const candidateNodes = new Set();
-        for (const nodeId of completedNodeIds) {
-            const node = nodes[nodeId];
-            if (!node?.next)
-                continue;
-            const nextNodes = resolveNextFromConfig(node.next, branchKeys[nodeId]);
-            for (const nextNode of nextNodes) {
-                candidateNodes.add(nextNode);
-            }
-        }
-        for (const entryId of entryNodeIds) {
-            candidateNodes.add(entryId);
-        }
-        if (candidateNodes.size === 0 && completedNodeIds.length > 0) {
-            await workflowService.updateRunStatus(runId, 'completed');
+        const run = await workflowService.getRun(runId);
+        if (run?.status === 'suspended') {
             return;
         }
-        const unstartedNodes = await workflowService.getNodesWithoutSteps(runId, [
-            ...candidateNodes,
-        ]);
-        const nodesToExecute = unstartedNodes.filter((nodeId) => {
-            const node = nodes[nodeId];
-            return node && areDependenciesSatisfied(node, completedNodeIdSet);
-        });
-        if (nodesToExecute.length === 0) {
-            if (completedNodeIds.length > 0 && unstartedNodes.length === 0) {
+        const instances = await workflowService.getStepInstances(runId);
+        const plan = planGraphTransitions(nodes, instances, branchByStep, entryNodeIds, graphName);
+        if (plan.toFire.length === 0) {
+            if (!plan.hasInFlight && !plan.blockedWaiting) {
                 await workflowService.updateRunStatus(runId, 'completed');
             }
             return;
         }
-        await Promise.all(nodesToExecute.map(async (nodeId) => {
-            const node = nodes[nodeId];
+        let executed = 0;
+        await Promise.all(plan.toFire.map(async (fire) => {
+            const node = nodes[fire.logical];
             if (!node?.rpcName)
                 return;
             const referencedNodeIds = extractReferencedNodeIds(node.input).filter((id) => !IGNORED_REFS.has(id));
             const fetchedResults = await workflowService.getNodeResults(runId, referencedNodeIds);
             const nodeResults = { trigger: triggerInput, ...fetchedResults };
             const resolvedInput = resolveSerializedInput(node.input, nodeResults);
-            await executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, resolvedInput, nodes);
+            executed++;
+            await executeGraphNodeInline(workflowService, rpcService, runId, graphName, fire.logical, fire.instanceKey, resolvedInput, nodes, fire.fromStepName);
         }));
+        // Nothing executable fired (e.g. nodes without an rpcName) → can't progress.
+        if (executed === 0)
+            return;
     }
 }
 export async function runWorkflowGraph(workflowService, graphName, triggerInput, rpcService, inline, startNode, wire, overrideMeta) {
@@ -600,7 +662,7 @@ export async function runWorkflowGraph(workflowService, graphName, triggerInput,
                     const resolvedInput = node.input && Object.keys(node.input).length > 0
                         ? resolveSerializedInput(node.input, triggerNodeResults)
                         : triggerInput;
-                    await executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, resolvedInput, nodes);
+                    await executeGraphNodeInline(workflowService, rpcService, runId, graphName, nodeId, nodeId, resolvedInput, nodes);
                 }));
                 await continueGraphInline(workflowService, rpcService, runId, graphName, nodes, triggerInput, entryNodes);
             }

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

@@ -1,7 +1,10 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowNotFoundError, WorkflowRunNotFoundError, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
+export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
+export type { RunTimeline, RunTimelineEvent, ReconstructedRunState, ReconstructedStep, RunPhase, } from './run-timeline.js';
 export { addWorkflow } from './dsl/workflow-runner.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';

package/dist/wirings/workflow/index.js

@@ -1,7 +1,10 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowNotFoundError, WorkflowRunNotFoundError, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
+// Time-travel: reconstruct run state at any point from durable history
+export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 // Internal registration functions (used by generated code)
 export { addWorkflow } from './dsl/workflow-runner.js';
 // Graph helpers (template, pikkuWorkflowGraph)

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

@@ -1,7 +1,17 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { PikkuWorkflowWire, StepState, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { PikkuWorkflowWire, StepState, StepStatus, 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';
+import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
+import type { JobOptions } from '../queue/queue.types.js';
+/**
+ * Default number of retries for a workflow step when none is specified. The
+ * workflow — not the queue — owns retry policy; a step inherits this unless it
+ * sets its own `retries` (including `retries: 0` to opt out entirely). Picked >0
+ * so a transient failure (a DB blip, a downstream restart, a deploy) is ridden
+ * out by default; safe because every step gets a stable `invocationId` to dedupe on.
+ */
+export declare const DEFAULT_STEP_RETRIES = 5;
 /**
  * Exception thrown when workflow needs to pause for async step
  */
@@ -26,6 +36,21 @@ export declare class WorkflowSuspendedException extends Error {
     readonly reason: string;
     constructor(runId: string, reason: string);
 }
+/**
+ * Thrown when a step (or the orchestrator) could not be enqueued — the queue
+ * itself failed (e.g. pg-boss is momentarily down), NOT the step's own logic.
+ * This is transient infrastructure failure: the run is left untouched (the step
+ * stays `pending`, the run stays running) and the orchestrator job is rethrown
+ * so the queue redelivers it and the workflow replays from its snapshot. Treat
+ * it as non-terminal — never mark the run `failed` for it.
+ */
+export declare class WorkflowDispatchException extends Error {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Error class for workflow not found
  */
@@ -99,6 +124,20 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * Used by the public API — the console addon provides the full verbose view.
      */
     getRunStatus(id: string): Promise<WorkflowRunStatus | null>;
+    /**
+     * Build the run's time-travel event stream from durable history.
+     * @param id - Run ID
+     * @returns Ordered timeline, or null if the run doesn't exist
+     */
+    getRunTimeline(id: string): Promise<RunTimeline | null>;
+    /**
+     * Reconstruct the run's state at a point in its timeline.
+     * @param id - Run ID
+     * @param at - A seq index (inclusive) or a Date (inclusive); omit for the
+     *             final state.
+     * @returns Reconstructed state, or null if the run doesn't exist
+     */
+    reconstructRunStateAt(id: string, at?: number | Date): Promise<ReconstructedRunState | null>;
     /**
      * Get workflow run history (all step attempts in chronological order)
      * @param runId - Run ID
@@ -124,8 +163,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
      */
-    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>;
+    insertStepState(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<StepState>;
+    protected abstract insertStepStateImpl(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<StepState>;
     /**
      * Get step state by cache key (read-only)
      * @param runId - Run ID
@@ -216,6 +255,17 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @returns Node IDs that don't have a step yet
      */
     abstract getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
+    /**
+     * List every step instance of a run (any status) with its predecessor.
+     * Drives bounded graph revisits: the runner counts instances per logical node
+     * and treats each `fromStepName → node` as a once-fired transition.
+     * @param runId - Run ID
+     */
+    abstract getStepInstances(runId: string): Promise<Array<{
+        stepName: string;
+        status: StepStatus;
+        fromStepName?: string;
+    }>>;
     /**
      * Get results for specific nodes
      * @param runId - Run ID
@@ -262,7 +312,17 @@ 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, stepOptions?: WorkflowStepOptions): Promise<void>;
+    /**
+     * Resolve a step's retry policy into queue job options. The workflow is the
+     * sole source of truth for retries: an explicitly-set `retries` (including 0)
+     * is always honored, an unset one defaults to {@link DEFAULT_STEP_RETRIES},
+     * and we ALWAYS pass `attempts` so the queue can never fall back to its own
+     * default — which would re-run a step the workflow said not to retry. Backoff
+     * defaults to exponential whenever there's at least one retry, so retries ride
+     * out a transient outage instead of firing instantly.
+     */
+    protected resolveStepJobOptions(stepOptions?: WorkflowStepOptions): JobOptions;
+    queueStepWorker(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<void>;
     /**
      * Execute a workflow sleep step completion
      * Sets the step result to null and resumes the workflow
@@ -289,7 +349,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @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>;
+    protected dispatchStep(runId: string, stepName: string, rpcName: string, data: unknown, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<boolean>;
     /**
      * Schedule a workflow sleep wakeup at the given duration.
      *
@@ -317,7 +377,20 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
     }): Promise<any>;
+    private stepOrdinals;
+    private stepLineage;
+    private resetStepOrdinals;
+    /** The step the DSL walk last reached (the predecessor for the next step). */
+    private lastStepName;
+    /**
+     * Physical, replay-stable key for the Nth reach of `logicalStepName` in a run:
+     * bare name for the first reach (ordinal 0, unchanged behavior), `name#N` for
+     * repeats — so the same literal step name can be invoked multiple times without
+     * the rows clobbering. Deterministic given a deterministic DSL body.
+     */
+    private nextStepKey;
     runWorkflowJob(runId: string, rpcService: any): Promise<void>;
+    private runWorkflowJobInner;
     private onChildWorkflowCompleted;
     private onChildWorkflowFailed;
     private runVersionMismatchFallback;
@@ -332,6 +405,23 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     orchestrateWorkflow(runId: string, rpcService: any): Promise<void>;
     private verifyQueueService;
+    /**
+     * Invoke a step's RPC with the workflow-step wire (step identity + provenance).
+     * Identical for the queue executor and the inline executor — the only thing
+     * that differs between transports is who calls it, not the call itself.
+     */
+    private invokeStepRpc;
+    /**
+     * Inline (straight-through) step execution with an in-process retry loop —
+     * shared by inline RPC steps and inline function steps. Same scaffolding
+     * (running → result, or fail → retry-attempt → backoff → retry) wrapped
+     * around a step-specific `doWork` body. Stays O(K): no suspend/replay.
+     *
+     * `onError` is an optional hook for terminal errors that must NOT retry
+     * (e.g. RPC-not-found → suspend the run for redeploy). If it throws, the
+     * loop exits immediately without recording a step error or retrying.
+     */
+    private runInlineRetryLoop;
     private rpcStep;
     private inlineStep;
     private sleepStep;