@pikku/core 0.12.36 → 0.12.38

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

@@ -32,6 +32,15 @@ import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.js';
 import { ChildWorkflowStartedException } from './graph/graph-runner.js';
+import { deriveInvocationId } from './workflow-invocation-id.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 const DEFAULT_STEP_RETRIES = 5;
 /**
  * Exception thrown when workflow needs to pause for async step
  */
@@ -71,6 +80,24 @@ export class WorkflowSuspendedException extends Error {
         this.name = 'WorkflowSuspendedException';
     }
 }
+/**
+ * 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 class WorkflowDispatchException extends Error {
+    runId;
+    stepName;
+    constructor(runId, stepName, options) {
+        super(`Failed to dispatch workflow step '${stepName}' (run ${runId})`, options);
+        this.runId = runId;
+        this.stepName = stepName;
+        this.name = 'WorkflowDispatchException';
+    }
+}
 /**
  * Error class for workflow not found
  */
@@ -309,8 +336,8 @@ export class PikkuWorkflowService {
      * @param stepOptions - Step options (retries, retryDelay)
      * @returns Step state with generated stepId
      */
-    async insertStepState(runId, stepName, rpcName, data, stepOptions) {
-        const step = await this.insertStepStateImpl(runId, stepName, rpcName, data, stepOptions);
+    async insertStepState(runId, stepName, rpcName, data, stepOptions, fromStepName) {
+        const step = await this.insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName);
         await this.safeMirror(() => this.mirror.insertStepState(runId, { ...step, stepName, rpcName, data }));
         return step;
     }
@@ -423,29 +450,38 @@ export class PikkuWorkflowService {
             const run = await this.getRun(runId);
             workflowName = run?.workflow;
         }
-        await queueService.add(this.getOrchestratorQueueName(workflowName), {
-            runId,
-        });
+        // Carry an explicit retry policy on the orchestrator job too. Orchestrator
+        // runs are idempotent (they replay from the snapshot, returning cached step
+        // results), so redelivery is always safe — and it's what lets a transient
+        // dispatch/infra failure recover: the job is rethrown and retried instead of
+        // the run hanging. Passing `attempts` per-job overrides the queue default, so
+        // this holds even when the orchestrator queue is configured `retry_limit 0`.
+        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, this.resolveStepJobOptions());
     }
-    async queueStepWorker(runId, stepName, rpcName, data, stepOptions) {
-        const queueService = this.verifyQueueService();
-        const retries = stepOptions?.retries ?? 0;
+    /**
+     * 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.
+     */
+    resolveStepJobOptions(stepOptions) {
+        const retries = stepOptions?.retries ?? DEFAULT_STEP_RETRIES;
         const retryDelay = stepOptions?.retryDelay;
-        await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({
-            runId,
-            stepName,
-            rpcName,
-            data,
-        })), retries > 0 || retryDelay
-            ? {
-                attempts: retries + 1,
-                backoff: typeof retryDelay === 'number'
-                    ? { type: 'fixed', delay: retryDelay }
-                    : retryDelay === 'exponential'
-                        ? 'exponential'
-                        : undefined,
-            }
-            : undefined);
+        const backoff = typeof retryDelay === 'number'
+            ? { type: 'fixed', delay: retryDelay }
+            : retryDelay === 'exponential'
+                ? 'exponential'
+                : retries > 0
+                    ? 'exponential'
+                    : undefined;
+        return { attempts: retries + 1, ...(backoff ? { backoff } : {}) };
+    }
+    async queueStepWorker(runId, stepName, rpcName, data, stepOptions, fromStepName) {
+        const queueService = this.verifyQueueService();
+        await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), this.resolveStepJobOptions(stepOptions));
     }
     /**
      * Execute a workflow sleep step completion
@@ -483,7 +519,7 @@ export class PikkuWorkflowService {
      * @returns true if dispatch was async (caller should pause), false to fall
      *   through to the inline execution path.
      */
-    async dispatchStep(runId, stepName, rpcName, data, stepOptions) {
+    async dispatchStep(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         // Step execution is decided purely by the function's `inline` flag (default
         // true). Only a function explicitly marked `inline: false` dispatches via
         // the queue. The run-level inline state is intentionally NOT consulted
@@ -505,21 +541,16 @@ export class PikkuWorkflowService {
             getSingletonServices()?.logger.warn(`Workflow step '${stepName}' (function '${rpcName}') is marked 'inline: false' but no queue service is configured — running it inline instead of dispatching to a queue.`);
             return false;
         }
-        const retries = stepOptions?.retries ?? 0;
-        const retryDelay = stepOptions?.retryDelay;
-        await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({
-            runId,
-            stepName,
-            rpcName,
-            data,
-        })), {
-            attempts: retries + 1,
-            backoff: typeof retryDelay === 'number'
-                ? { type: 'fixed', delay: retryDelay }
-                : retryDelay === 'exponential'
-                    ? 'exponential'
-                    : undefined,
-        });
+        try {
+            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), this.resolveStepJobOptions(stepOptions));
+        }
+        catch (cause) {
+            // The queue is down/unreachable — NOT a step failure. Surface it as a
+            // transient dispatch error so the caller leaves the step `pending` and the
+            // orchestrator job is retried (replayed from snapshot) rather than the run
+            // being marked failed. `add` already throws on failure in every adapter.
+            throw new WorkflowDispatchException(runId, stepName, { cause });
+        }
         return true;
     }
     /**
@@ -587,7 +618,9 @@ export class PikkuWorkflowService {
             catch (error) {
                 if (error.name !== 'WorkflowAsyncException' &&
                     error.name !== 'WorkflowCancelledException' &&
-                    error.name !== 'WorkflowSuspendedException') {
+                    error.name !== 'WorkflowSuspendedException' &&
+                    // Transient queue failure — leave the run resumable, don't fail it.
+                    error.name !== 'WorkflowDispatchException') {
                     await this.updateRunStatus(runId, 'failed', undefined, {
                         name: error.name,
                         message: error.message,
@@ -596,6 +629,11 @@ export class PikkuWorkflowService {
                     getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, error);
                     throw error;
                 }
+                if (error.name === 'WorkflowDispatchException') {
+                    // Rethrow so the caller (poll loop / starter) sees the transient
+                    // failure; the run stays running and can be resumed.
+                    throw error;
+                }
             }
             finally {
                 this.inlineRuns.delete(runId);
@@ -626,7 +664,48 @@ export class PikkuWorkflowService {
             await new Promise((resolve) => setTimeout(resolve, pollInterval));
         }
     }
+    // Per-run, per-replay ordinal counters (runId → stepName → count).
+    stepOrdinals = new Map();
+    // Previous step key reached in the current DSL walk (runId → stepName), so a
+    // new step records where it came from. Rebuilt each replay alongside ordinals.
+    stepLineage = new Map();
+    resetStepOrdinals(runId) {
+        this.stepOrdinals.set(runId, new Map());
+        this.stepLineage.delete(runId);
+    }
+    /** The step the DSL walk last reached (the predecessor for the next step). */
+    lastStepName(runId) {
+        return this.stepLineage.get(runId);
+    }
+    /**
+     * 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.
+     */
+    nextStepKey(runId, logicalStepName) {
+        let perRun = this.stepOrdinals.get(runId);
+        if (!perRun) {
+            perRun = new Map();
+            this.stepOrdinals.set(runId, perRun);
+        }
+        const ordinal = perRun.get(logicalStepName) ?? 0;
+        perRun.set(logicalStepName, ordinal + 1);
+        const stepName = ordinal === 0 ? logicalStepName : `${logicalStepName}#${ordinal}`;
+        this.stepLineage.set(runId, stepName);
+        return stepName;
+    }
     async runWorkflowJob(runId, rpcService) {
+        // Fresh ordinal counters per replay so step keys are deterministic.
+        this.resetStepOrdinals(runId);
+        try {
+            await this.runWorkflowJobInner(runId, rpcService);
+        }
+        finally {
+            this.stepOrdinals.delete(runId);
+        }
+    }
+    async runWorkflowJobInner(runId, rpcService) {
         const run = await this.getRun(runId);
         if (!run) {
             throw new WorkflowRunNotFoundError(runId);
@@ -799,10 +878,22 @@ export class PikkuWorkflowService {
                 const workflowMeta = meta[run.workflow];
                 const isGraphWorkflow = workflowMeta?.source === 'graph' ||
                     workflowMeta?.source === 'dynamic-workflow';
-                if (isGraphWorkflow &&
-                    workflowMeta?.nodes &&
-                    stepName in workflowMeta.nodes) {
-                    result = await executeGraphStep(this, rpcService, runId, stepState.stepId, stepName, rpcName, data, run.workflow);
+                // Map the physical step key back to its logical node: a revisit instance
+                // is `node#N` (ordinal), which isn't a literal key in `nodes`.
+                let graphNodeId;
+                if (isGraphWorkflow && workflowMeta?.nodes) {
+                    if (stepName in workflowMeta.nodes) {
+                        graphNodeId = stepName;
+                    }
+                    else {
+                        const hash = stepName.lastIndexOf('#');
+                        const base = hash > 0 ? stepName.slice(0, hash) : undefined;
+                        if (base && base in workflowMeta.nodes)
+                            graphNodeId = base;
+                    }
+                }
+                if (graphNodeId) {
+                    result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, rpcName, data, run.workflow);
                 }
                 else {
                     // Check if rpcName refers to a sub-workflow
@@ -837,7 +928,11 @@ export class PikkuWorkflowService {
                             workflowStep: {
                                 runId,
                                 stepId: stepState.stepId,
+                                invocationId: deriveInvocationId(runId, stepName),
                                 attemptCount: stepState.attemptCount,
+                                fromInvocationId: stepState.fromStepName
+                                    ? deriveInvocationId(runId, stepState.fromStepName)
+                                    : undefined,
                             },
                         });
                     }
@@ -862,7 +957,7 @@ export class PikkuWorkflowService {
                 }
                 // Store error and mark failed
                 await this.setStepError(stepState.stepId, error);
-                const maxAttempts = (stepState.retries ?? 0) + 1;
+                const maxAttempts = (stepState.retries ?? DEFAULT_STEP_RETRIES) + 1;
                 const retriesExhausted = stepState.attemptCount >= maxAttempts;
                 if (retriesExhausted) {
                     // No more retries - resume orchestrator to mark workflow as failed
@@ -888,6 +983,13 @@ export class PikkuWorkflowService {
                 error.name === 'WorkflowSuspendedException') {
                 return;
             }
+            if (error.name === 'WorkflowDispatchException') {
+                // Transient: the queue was unreachable, not a workflow failure. Leave the
+                // run running and rethrow so the orchestrator job is redelivered and the
+                // workflow replays from its snapshot. Do NOT mark the run failed.
+                getSingletonServices().logger.warn(`Workflow run ${runId} could not dispatch a step (queue unavailable); leaving run for orchestrator retry`, error);
+                throw error;
+            }
             await this.updateRunStatus(runId, 'failed', undefined, {
                 message: error.message,
                 stack: error.stack,
@@ -902,7 +1004,18 @@ export class PikkuWorkflowService {
         }
         return getSingletonServices().queueService;
     }
-    async rpcStep(runId, stepName, rpcName, data, rpcService, stepOptions) {
+    async rpcStep(runId, logicalStepName, rpcName, data, rpcService, stepOptions) {
+        // Capture the predecessor before nextStepKey advances the lineage to us.
+        const fromStepName = this.lastStepName(runId);
+        const stepName = this.nextStepKey(runId, logicalStepName);
+        // Resolve the retry policy ONCE here so the value persisted on the step
+        // (which drives `retriesExhausted`) is the same one the queue dispatch turns
+        // into `attempts`. Without this the queue could retry N times while the
+        // engine thinks retries are already exhausted (or vice-versa).
+        const resolvedStepOptions = {
+            retries: stepOptions?.retries ?? DEFAULT_STEP_RETRIES,
+            retryDelay: stepOptions?.retryDelay,
+        };
         // Check if step already exists
         let stepState;
         try {
@@ -910,7 +1023,7 @@ export class PikkuWorkflowService {
         }
         catch {
             // Step doesn't exist - create it
-            stepState = await this.insertStepState(runId, stepName, rpcName, data, stepOptions);
+            stepState = await this.insertStepState(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName);
         }
         if (stepState.status === 'succeeded') {
             // Return cached result
@@ -930,18 +1043,22 @@ export class PikkuWorkflowService {
             // Step is already scheduled, pause workflow
             throw new WorkflowAsyncException(runId, stepName);
         }
-        // Step is pending - schedule it
-        await this.setStepScheduled(stepState.stepId);
         // Hand off to subclass-overridable transport. Default behavior enqueues
         // via the queue service; DO-style subclasses RPC to a step worker.
-        const dispatched = await this.dispatchStep(runId, stepName, rpcName, data, stepOptions);
+        // Dispatch BEFORE marking the step `scheduled`: if the queue is down,
+        // dispatchStep throws WorkflowDispatchException and the step stays `pending`,
+        // so the orchestrator's next replay re-dispatches it. Marking `scheduled`
+        // first would strand the step (replay sees `scheduled`, pauses, never
+        // re-enqueues the job that was never created).
+        const dispatched = await this.dispatchStep(runId, stepName, rpcName, data, resolvedStepOptions, fromStepName);
         if (dispatched) {
+            await this.setStepScheduled(stepState.stepId);
             throw new WorkflowAsyncException(runId, stepName);
         }
         {
             // Inline (no transport available) - execute locally with retry loop
-            const retries = stepOptions?.retries ?? 0;
-            const retryDelay = stepOptions?.retryDelay;
+            const retries = resolvedStepOptions.retries ?? this.getConfig().retries;
+            const retryDelay = resolvedStepOptions.retryDelay;
             let currentStepState = stepState;
             while (true) {
                 try {
@@ -982,7 +1099,11 @@ export class PikkuWorkflowService {
                             workflowStep: {
                                 runId,
                                 stepId: currentStepState.stepId,
+                                invocationId: deriveInvocationId(runId, stepName),
                                 attemptCount: currentStepState.attemptCount,
+                                fromInvocationId: currentStepState.fromStepName
+                                    ? deriveInvocationId(runId, currentStepState.fromStepName)
+                                    : undefined,
                             },
                         });
                     }
@@ -1017,7 +1138,9 @@ export class PikkuWorkflowService {
             }
         }
     }
-    async inlineStep(runId, stepName, fn, stepOptions) {
+    async inlineStep(runId, logicalStepName, fn, stepOptions) {
+        const fromStepName = this.lastStepName(runId);
+        const stepName = this.nextStepKey(runId, logicalStepName);
         // Check if step already exists
         let stepState;
         try {
@@ -1025,7 +1148,7 @@ export class PikkuWorkflowService {
         }
         catch {
             // Step doesn't exist - create it (inline, no RPC)
-            stepState = await this.insertStepState(runId, stepName, null, null, stepOptions);
+            stepState = await this.insertStepState(runId, stepName, null, null, stepOptions, fromStepName);
         }
         if (stepState.status === 'succeeded') {
             // Return cached result
@@ -1090,7 +1213,9 @@ export class PikkuWorkflowService {
             }
         }
     }
-    async sleepStep(runId, stepName, duration) {
+    async sleepStep(runId, logicalStepName, duration) {
+        const fromStepName = this.lastStepName(runId);
+        const stepName = this.nextStepKey(runId, logicalStepName);
         // Check if step already exists
         let stepState;
         try {
@@ -1098,9 +1223,7 @@ export class PikkuWorkflowService {
         }
         catch {
             // Step doesn't exist - create it (sleep step, no RPC)
-            stepState = await this.insertStepState(runId, stepName, null, {
-                duration,
-            });
+            stepState = await this.insertStepState(runId, stepName, null, { duration }, undefined, fromStepName);
         }
         if (stepState.status === 'succeeded') {
             // Sleep already completed, return immediately
@@ -1110,13 +1233,20 @@ export class PikkuWorkflowService {
             // Sleep is already scheduled, pause workflow
             throw new WorkflowAsyncException(runId, stepName);
         }
-        // Step is pending - schedule it
-        await this.setStepScheduled(stepState.stepId);
         // Hand off to subclass-overridable transport. Default behavior schedules
         // a delayed sleeper RPC via the scheduler service; DO-style subclasses
-        // override to use native timer primitives (e.g. setAlarm).
-        const scheduled = await this.scheduleSleep(runId, stepState.stepId, duration);
+        // override to use native timer primitives (e.g. setAlarm). Schedule BEFORE
+        // marking `scheduled` so a scheduler outage leaves the step `pending` for
+        // re-scheduling on replay instead of stranding it (see rpcStep).
+        let scheduled;
+        try {
+            scheduled = await this.scheduleSleep(runId, stepState.stepId, duration);
+        }
+        catch (cause) {
+            throw new WorkflowDispatchException(runId, stepName, { cause });
+        }
         if (scheduled) {
+            await this.setStepScheduled(stepState.stepId);
             throw new WorkflowAsyncException(runId, stepName);
         }
         // Inline mode - use setTimeout with actual duration
@@ -1138,7 +1268,8 @@ export class PikkuWorkflowService {
         return `__workflow_suspend:${reason}`;
     }
     async suspendStep(runId, reason) {
-        const suspendStepName = this.getSuspendStepName(reason);
+        const fromStepName = this.lastStepName(runId);
+        const suspendStepName = this.nextStepKey(runId, this.getSuspendStepName(reason));
         await this.withStepLock(runId, suspendStepName, async () => {
             let stepState;
             try {
@@ -1147,12 +1278,12 @@ export class PikkuWorkflowService {
             catch {
                 stepState = await this.insertStepState(runId, suspendStepName, 'pikkuWorkflowSuspend', {
                     reason,
-                });
+                }, undefined, fromStepName);
             }
             if (!stepState.stepId) {
                 stepState = await this.insertStepState(runId, suspendStepName, 'pikkuWorkflowSuspend', {
                     reason,
-                });
+                }, undefined, fromStepName);
             }
             if (stepState.status === 'succeeded') {
                 return;
@@ -1206,7 +1337,7 @@ export class PikkuWorkflowService {
         const singletonServices = getSingletonServices();
         const workflow = singletonServices.config?.workflow;
         return {
-            retries: workflow?.retries ?? 0,
+            retries: workflow?.retries ?? DEFAULT_STEP_RETRIES,
             retryDelay: workflow?.retryDelay ?? 0,
             orchestratorQueueName: workflow?.orchestratorQueueName ?? 'pikku-workflow-orchestrator',
             stepWorkerQueueName: workflow?.stepWorkerQueueName ?? 'pikku-workflow-step-worker',

package/dist/wirings/workflow/workflow-invocation-id.d.ts

@@ -0,0 +1,20 @@
+/**
+ * RFC 4122 v5 (SHA-1, name-based) UUID. Deterministic: the same name +
+ * namespace always yields the same UUID — no `uuid` dependency needed.
+ */
+export declare const uuidv5: (name: string, namespace?: string) => string;
+/**
+ * The stable identity of one step *invocation* within a run — the idempotency /
+ * dedupe key handed to a step. Unlike `stepId` (minted fresh per attempt), this
+ * stays identical across every retry of the same call, because it is derived
+ * purely from `runId` + `stepName`, both of which are stable across replays.
+ *
+ * Same inputs → same UUID, so a step can safely
+ * `INSERT … ON CONFLICT (invocation_id)` / pass it as a Stripe idempotency key,
+ * and a retry of a half-applied side effect is collapsed onto the first attempt.
+ *
+ * NOTE: calling the *same* `stepName` more than once in a run is not yet
+ * disambiguated here (the store still keys steps by `runId:stepName`); when
+ * per-invocation ordinals land, the ordinal becomes the third hash component.
+ */
+export declare const deriveInvocationId: (runId: string, stepName: string) => string;

package/dist/wirings/workflow/workflow-invocation-id.js

@@ -0,0 +1,38 @@
+import { createHash } from 'crypto';
+// Fixed namespace for pikku workflow step invocation IDs. Frozen — changing it
+// would alter every derived invocationId and break dedupe across a deploy.
+const PIKKU_WORKFLOW_NAMESPACE = '70696b6b-7500-5770-9f6c-6f77000a0001';
+const parseUuid = (uuid) => Buffer.from(uuid.replace(/-/g, ''), 'hex');
+const formatUuid = (bytes) => {
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+};
+/**
+ * RFC 4122 v5 (SHA-1, name-based) UUID. Deterministic: the same name +
+ * namespace always yields the same UUID — no `uuid` dependency needed.
+ */
+export const uuidv5 = (name, namespace = PIKKU_WORKFLOW_NAMESPACE) => {
+    const hash = createHash('sha1')
+        .update(parseUuid(namespace))
+        .update(name, 'utf8')
+        .digest();
+    const bytes = hash.subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+    return formatUuid(bytes);
+};
+/**
+ * The stable identity of one step *invocation* within a run — the idempotency /
+ * dedupe key handed to a step. Unlike `stepId` (minted fresh per attempt), this
+ * stays identical across every retry of the same call, because it is derived
+ * purely from `runId` + `stepName`, both of which are stable across replays.
+ *
+ * Same inputs → same UUID, so a step can safely
+ * `INSERT … ON CONFLICT (invocation_id)` / pass it as a Stripe idempotency key,
+ * and a retry of a half-applied side effect is collapsed onto the first attempt.
+ *
+ * NOTE: calling the *same* `stepName` more than once in a run is not yet
+ * disambiguated here (the store still keys steps by `runId:stepName`); when
+ * per-invocation ordinals land, the ordinal becomes the third hash component.
+ */
+export const deriveInvocationId = (runId, stepName) => uuidv5(`${runId}:${stepName}`);

package/dist/wirings/workflow/workflow-queue-workers.d.ts

@@ -11,6 +11,8 @@ export interface WorkflowStepInput {
     stepName: string;
     rpcName: string;
     data: unknown;
+    /** Predecessor step name (the walked transition); undefined for entry steps. */
+    fromStepName?: string;
 }
 export interface PikkuWorkflowOrchestratorInput {
     runId: string;

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

@@ -83,6 +83,9 @@ export interface StepState {
     retries?: number;
     /** Delay between retries */
     retryDelay?: string | number;
+    /** Step name of the predecessor that scheduled this step (the transition/edge
+     *  walked to reach it); undefined for entry steps. Reconstructs the path. */
+    fromStepName?: string;
     /** Creation timestamp */
     createdAt: Date;
     /** Last update timestamp */
@@ -269,6 +272,8 @@ export type WorkflowStepInput = {
     stepName: string;
     rpcName: string;
     data: any;
+    /** Predecessor step name (the walked transition); undefined for entry steps. */
+    fromStepName?: string;
 };
 export type WorkflowOrchestratorInput = {
     runId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.36",
+  "version": "0.12.38",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -54,6 +54,7 @@
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
+    "@types/json-schema": "^7.0.15",
     "cookie": "^1.1.1",
     "json-schema": "^0.4.0",
     "path-to-regexp": "^8.3.0",

package/src/dev/hot-reload.test.ts

@@ -32,6 +32,11 @@ const ensureRecursiveWatchAvailable = async (
   t: TestContext,
   dir: string
 ): Promise<boolean> => {
+  if ('bun' in process.versions) {
+    t.skip('tsx esm dynamic reload not supported under bun')
+    return false
+  }
+
   if (process.platform === 'darwin') {
     t.skip('recursive fs.watch is unreliable on darwin')
     return false

package/src/services/in-memory-workflow-service.ts

@@ -7,6 +7,7 @@ import type {
   WorkflowRunService,
   WorkflowRunWire,
   StepState,
+  StepStatus,
   WorkflowStatus,
   WorkflowVersionStatus,
   WorkflowStepOptions,
@@ -140,7 +141,8 @@ export class InMemoryWorkflowService
     stepName: string,
     rpcName: string | null,
     data: any,
-    stepOptions?: WorkflowStepOptions
+    stepOptions?: WorkflowStepOptions,
+    fromStepName?: string
   ): Promise<StepState> {
     const stepId = randomUUID()
     const now = new Date()
@@ -151,6 +153,7 @@ export class InMemoryWorkflowService
       attemptCount: 1,
       retries: stepOptions?.retries,
       retryDelay: stepOptions?.retryDelay,
+      fromStepName,
       createdAt: now,
       updatedAt: now,
       stepName,
@@ -281,6 +284,7 @@ export class InMemoryWorkflowService
       attemptCount: failedStep.attemptCount + 1,
       retries: failedStep.retries,
       retryDelay: failedStep.retryDelay,
+      fromStepName: failedStep.fromStepName,
       createdAt: now,
       updatedAt: now,
       stepName: stepName,
@@ -445,6 +449,26 @@ export class InMemoryWorkflowService
     return nodeIds.filter((id) => !existingSteps.has(id))
   }
 
+  async getStepInstances(runId: string): Promise<
+    Array<{ stepName: string; status: StepStatus; fromStepName?: string }>
+  > {
+    const prefix = `${runId}:`
+    const instances: Array<{
+      stepName: string
+      status: StepStatus
+      fromStepName?: string
+    }> = []
+    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: string,
     nodeIds: string[]