@pikku/core 0.12.37 → 0.12.38

package/CHANGELOG.md

@@ -1,3 +1,63 @@
+## 0.12.38
+
+### Patch Changes
+
+- 92cd5b1: feat(workflow): workflow-owned step retries + stable invocationId
+
+  The workflow — not the queue — now owns step retry policy, and each step
+  invocation gets a stable idempotency key.
+  - **Default `retries: 5` with exponential backoff.** A step with no `retries`
+    previously inherited the queue's bare default (e.g. pg-boss `retry_limit 2`,
+    no backoff) so retries fired instantly and couldn't outlast a transient
+    outage. Retries now default to 5 with backoff, resolved at the workflow layer.
+  - **`retries: 0` is honored.** Dispatch previously passed `undefined` options
+    for `retries: 0`, letting the queue re-run a non-idempotent step up to its own
+    default. The resolved policy now always sets `attempts` (`retries: 0` →
+    `attempts: 1`), so the queue never second-guesses the workflow. The persisted
+    step retries and the dispatched `attempts` are resolved together so
+    "retries exhausted" and "no more redeliveries" are the same event.
+  - **`workflowStep.invocationId`** — a deterministic, dependency-free
+    `uuidv5(runId:stepName)` handed to every step. Unlike `stepId` (minted per
+    attempt), it is identical across retries, so a step can dedupe on it
+    (`ON CONFLICT (invocationId)`, Stripe idempotency keys, etc.).
+  - **queue-bullmq**: `mapPikkuJobToBull` now maps `backoff` (previously dropped,
+    so a step's backoff silently never applied on Redis), and `registerQueues`
+    throws a clear error when no logger is available (matching queue-pg-boss).
+  - **Dispatch failures are recoverable, not fatal.** A step is now marked
+    `scheduled` only _after_ it is successfully handed to its transport (queue or
+    scheduler) — a failed hand-off leaves it `pending` so a replay re-dispatches
+    it, instead of stranding it in `scheduled` (replay would pause forever on a
+    job that was never enqueued). A transport outage (e.g. pg-boss momentarily
+    down) is surfaced as a new `WorkflowDispatchException`, which the orchestrator
+    treats as transient: the run is left running and the orchestrator job is
+    rethrown for redelivery (it replays idempotently from the snapshot) rather
+    than the whole run being marked `failed`. The orchestrator job now also
+    carries its own retry policy, so this holds even when the orchestrator queue
+    is configured `retry_limit 0`. A genuine step error still fails the run.
+  - **Same step name can be invoked multiple times in one run.** Step rows are now
+    keyed per _invocation_: the Nth reach of a step name in a replay resolves to a
+    physical key (`name` for the first, `name#N` for repeats), so a literal
+    duplicate name no longer clobbers the earlier step's state. The first reach
+    keeps the bare name, so existing rows, graph-node matching and `invocationId`s
+    are unchanged. Ordinals are derived deterministically from DSL execution order
+    and reset each replay.
+  - **Step provenance (`fromStepName`) + graph cycles.** Every step now records
+    the predecessor it was scheduled from (`fromStepName`; entry steps have none),
+    persisted on the step row across all stores (in-memory, kysely, redis,
+    mongodb, cloudflare DO) and carried in the queued payload. The DSL wire
+    exposes the derived `fromInvocationId` (`uuidv5(runId:fromStepName)`) so
+    consumers get the stable predecessor key without a second persisted id —
+    `fromStepName` is the source of truth (it is replay-deterministic; `stepId`,
+    minted per row, is not). This makes the walked path reconstructable even when
+    a node is reached more than once: in `a → b → a → c` the second `a` is a
+    distinct ordinal instance (`a#1`) whose `fromStepName` is `b`.
+    The graph runner now supports **cycles**: a forward edge into an
+    already-started node still collapses to a single run (joins/diamonds are
+    unchanged), but a _back-edge_ — one whose target can reach its source — fires
+    a fresh ordinal instance, so a node can loop back to itself. Termination is
+    the graph's responsibility (branch routing must converge); the engine enforces
+    no visit cap.
+
 ## 0.12.37
 
 ### Patch Changes

package/dist/services/in-memory-workflow-service.d.ts

@@ -1,6 +1,6 @@
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
 /**
  * In-memory implementation of WorkflowService for inline-only execution
  *
@@ -35,7 +35,7 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         stepName: string;
     }>>;
     protected updateRunStatusImpl(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
-    protected insertStepStateImpl(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions): Promise<StepState>;
+    protected insertStepStateImpl(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<StepState>;
     getStepState(runId: string, stepName: string): Promise<StepState>;
     protected setStepRunningImpl(stepId: string): Promise<void>;
     protected setStepScheduledImpl(stepId: string): Promise<void>;
@@ -65,6 +65,11 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         branchKeys: Record<string, string>;
     }>;
     getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
+    getStepInstances(runId: string): Promise<Array<{
+        stepName: string;
+        status: StepStatus;
+        fromStepName?: string;
+    }>>;
     getNodeResults(runId: string, nodeIds: string[]): Promise<Record<string, any>>;
     setBranchKey(runId: string, nodeId: string, branchKey: string): Promise<void>;
     protected setBranchTakenImpl(stepId: string, branchKey: string): Promise<void>;

package/dist/services/in-memory-workflow-service.js

@@ -78,7 +78,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
                 run.error = error;
         }
     }
-    async insertStepStateImpl(runId, stepName, rpcName, data, stepOptions) {
+    async insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         const stepId = randomUUID();
         const now = new Date();
         const step = {
@@ -87,6 +87,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             attemptCount: 1,
             retries: stepOptions?.retries,
             retryDelay: stepOptions?.retryDelay,
+            fromStepName,
             createdAt: now,
             updatedAt: now,
             stepName,
@@ -189,6 +190,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             attemptCount: failedStep.attemptCount + 1,
             retries: failedStep.retries,
             retryDelay: failedStep.retryDelay,
+            fromStepName: failedStep.fromStepName,
             createdAt: now,
             updatedAt: now,
             stepName: stepName,
@@ -317,6 +319,20 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
         return nodeIds.filter((id) => !existingSteps.has(id));
     }
+    async getStepInstances(runId) {
+        const prefix = `${runId}:`;
+        const instances = [];
+        for (const [key, step] of this.steps.entries()) {
+            if (!key.startsWith(prefix))
+                continue;
+            instances.push({
+                stepName: key.substring(prefix.length),
+                status: step.status,
+                fromStepName: step.fromStepName,
+            });
+        }
+        return instances;
+    }
     async getNodeResults(runId, nodeIds) {
         const results = {};
         for (const nodeId of nodeIds) {

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

@@ -271,10 +271,28 @@ export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepM
 export interface WorkflowStepWire {
     /** The workflow run ID */
     runId: string;
-    /** The unique step ID */
+    /**
+     * The step row ID. Whether it stays the same or is minted fresh per attempt is
+     * STORE-SPECIFIC (in-memory mints a new one each attempt; the SQL store reuses
+     * the row) — do NOT use it as a dedupe key. Use `invocationId`.
+     */
     stepId: string;
+    /**
+     * Stable identity of this step invocation — the idempotency / dedupe key.
+     * Identical across every retry of the same call (derived from runId + step
+     * name) regardless of storage backend, so a step can `ON CONFLICT (invocationId)`
+     * or pass it as an external idempotency key and have retries collapse onto the
+     * first attempt.
+     */
+    invocationId: string;
     /** Current attempt number (1-indexed, increments on retry) */
     attemptCount: number;
+    /**
+     * Invocation ID of the predecessor step this one was reached from (the walked
+     * transition/edge). Undefined for entry steps. Lets a step know its origin —
+     * e.g. in a cyclic graph `a → b → a → c`, the second `a` carries `b`'s id.
+     */
+    fromInvocationId?: string;
 }
 /**
  * Workflow wire object for DSL workflows

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,51 +387,26 @@ 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) {

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

@@ -1,7 +1,8 @@
 /**
  * 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 { 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,8 @@
 /**
  * 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';
 // 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,16 @@
 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 { 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 +35,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
  */
@@ -124,8 +148,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 +240,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 +297,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 +334,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 +362,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;