@pikku/core 0.12.37 → 0.12.39

package/dist/wirings/workflow/run-timeline.d.ts

@@ -0,0 +1,85 @@
+import type { SerializedError } from '../../types/core.types.js';
+import type { StepState, StepStatus } from './workflow.types.js';
+/**
+ * Time-travel over a workflow run.
+ *
+ * A run's durable history (`getRunHistory`) is one row per step *attempt*, each
+ * carrying lifecycle timestamps (created/scheduled/running/succeeded/failed).
+ * `buildRunTimeline` explodes those rows into a flat, chronologically-ordered
+ * event stream, and `reconstructStateAt` folds the stream up to any point to
+ * recover what the run "knew" then — the same step cache a replay would hold:
+ * per-step status, accumulated results, and the walked path.
+ *
+ * These are pure functions over history — no IO — so they're trivially testable
+ * and transport-independent (the same fold works for Redis/Kysely/in-memory).
+ */
+/** A single observable transition of one step attempt. */
+export interface RunTimelineEvent {
+    /** Monotonic 0-based position in the timeline. */
+    seq: number;
+    /** When it happened. */
+    at: Date;
+    /** The step's new status at this event (matches StepStatus lifecycle). */
+    type: Extract<StepStatus, 'pending' | 'scheduled' | 'running' | 'succeeded' | 'failed'>;
+    /** Physical step name (includes revisit ordinal, e.g. `attempt#2`). */
+    stepName: string;
+    /** Which attempt this event belongs to (1-based). */
+    attemptCount: number;
+    /** Predecessor that scheduled this step — only on the `pending` (created)
+     *  event; undefined for entry steps. Reconstructs the walked edge. */
+    fromStepName?: string;
+    /** Result snapshot — only on `succeeded`. */
+    result?: unknown;
+    /** Error snapshot — only on `failed`. */
+    error?: SerializedError;
+}
+export type RunTimeline = RunTimelineEvent[];
+type HistoryEntry = StepState & {
+    stepName: string;
+};
+/**
+ * Build the ordered event stream for a run from its raw history.
+ *
+ * History is expected oldest-first but is sorted defensively by (timestamp,
+ * lifecycle, original index) so simultaneous timestamps stay deterministic.
+ */
+export declare function buildRunTimeline(history: HistoryEntry[]): RunTimeline;
+/** A step's reconstructed state at a point in the timeline. */
+export interface ReconstructedStep {
+    stepName: string;
+    status: StepStatus;
+    attemptCount: number;
+    fromStepName?: string;
+    result?: unknown;
+    error?: SerializedError;
+}
+/** Coarse run phase derived purely from step states (not the run's output). */
+export type RunPhase = 'pending' | 'running' | 'failed' | 'idle';
+/** The whole run's reconstructed state at a point in the timeline. */
+export interface ReconstructedRunState {
+    /** seq of the last applied event, or -1 if the point precedes all events. */
+    seq: number;
+    /** Wall-clock time of the last applied event. */
+    at?: Date;
+    /** Per-step latest state, in first-seen (walked) order. */
+    steps: ReconstructedStep[];
+    /** Outputs available to downstream steps — the replay step cache at this
+     *  point (succeeded steps only). */
+    results: Record<string, unknown>;
+    /** Step names in the order they were first created — the walked path. */
+    path: string[];
+    /** Derived phase: `running` if any step is in-flight, else `failed` if a step
+     *  is failed with no in-flight work, else `idle` (between transitions). */
+    phase: RunPhase;
+}
+/**
+ * Fold the timeline up to `at` and return the run's state at that point.
+ *
+ * `at` is either a seq index (inclusive — apply events `0..at`) or a `Date`
+ * (inclusive — apply every event at or before that instant). A point before the
+ * first event yields the empty initial state.
+ */
+export declare function reconstructStateAt(timeline: RunTimeline, at: number | Date): ReconstructedRunState;
+/** Reconstruct the final state (fold the whole timeline). */
+export declare function reconstructFinalState(timeline: RunTimeline): ReconstructedRunState;
+export {};

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

@@ -0,0 +1,153 @@
+/** Lifecycle tiebreak for events that share a timestamp. */
+const LIFECYCLE_ORDER = {
+    pending: 0,
+    scheduled: 1,
+    running: 2,
+    succeeded: 3,
+    failed: 3,
+};
+/**
+ * Build the ordered event stream for a run from its raw history.
+ *
+ * History is expected oldest-first but is sorted defensively by (timestamp,
+ * lifecycle, original index) so simultaneous timestamps stay deterministic.
+ */
+export function buildRunTimeline(history) {
+    const raw = [];
+    history.forEach((entry, order) => {
+        const base = {
+            stepName: entry.stepName,
+            attemptCount: entry.attemptCount,
+            order,
+        };
+        // The created event always exists; it carries provenance.
+        raw.push({
+            ...base,
+            at: entry.createdAt,
+            type: 'pending',
+            fromStepName: entry.fromStepName,
+        });
+        // Intermediate events are optional enrichment — emit only if the backend
+        // recorded their timestamp.
+        if (entry.scheduledAt) {
+            raw.push({ ...base, at: entry.scheduledAt, type: 'scheduled' });
+        }
+        if (entry.runningAt) {
+            raw.push({ ...base, at: entry.runningAt, type: 'running' });
+        }
+        // The terminal event is driven by the row's authoritative status (the
+        // lifecycle timestamps aren't populated by every backend — Kysely leaves
+        // them null), falling back to updatedAt when the specific stamp is absent.
+        if (entry.status === 'succeeded') {
+            raw.push({
+                ...base,
+                at: entry.succeededAt ?? entry.updatedAt,
+                type: 'succeeded',
+                result: entry.result,
+            });
+        }
+        else if (entry.status === 'failed') {
+            raw.push({
+                ...base,
+                at: entry.failedAt ?? entry.updatedAt,
+                type: 'failed',
+                error: entry.error,
+            });
+        }
+    });
+    raw.sort((a, b) => {
+        const ta = a.at.getTime();
+        const tb = b.at.getTime();
+        if (ta !== tb)
+            return ta - tb;
+        const la = LIFECYCLE_ORDER[a.type];
+        const lb = LIFECYCLE_ORDER[b.type];
+        if (la !== lb)
+            return la - lb;
+        return a.order - b.order;
+    });
+    return raw.map(({ order: _order, ...event }, seq) => ({ ...event, seq }));
+}
+const IN_FLIGHT = new Set([
+    'pending',
+    'scheduled',
+    'running',
+]);
+/**
+ * Fold the timeline up to `at` and return the run's state at that point.
+ *
+ * `at` is either a seq index (inclusive — apply events `0..at`) or a `Date`
+ * (inclusive — apply every event at or before that instant). A point before the
+ * first event yields the empty initial state.
+ */
+export function reconstructStateAt(timeline, at) {
+    const cutoff = (event) => typeof at === 'number'
+        ? event.seq <= at
+        : event.at.getTime() <= at.getTime();
+    const steps = new Map();
+    const path = [];
+    let lastSeq = -1;
+    let lastAt;
+    for (const event of timeline) {
+        if (!cutoff(event))
+            break;
+        lastSeq = event.seq;
+        lastAt = event.at;
+        let step = steps.get(event.stepName);
+        if (!step) {
+            step = {
+                stepName: event.stepName,
+                status: event.type,
+                attemptCount: event.attemptCount,
+                fromStepName: event.fromStepName,
+            };
+            steps.set(event.stepName, step);
+            path.push(event.stepName);
+        }
+        step.status = event.type;
+        step.attemptCount = event.attemptCount;
+        if (event.fromStepName !== undefined) {
+            step.fromStepName = event.fromStepName;
+        }
+        // A retry's created event reopens the step — drop the prior outcome.
+        if (event.type === 'pending') {
+            delete step.result;
+            delete step.error;
+        }
+        if (event.type === 'succeeded') {
+            step.result = event.result;
+            step.error = undefined;
+        }
+        if (event.type === 'failed') {
+            step.error = event.error;
+        }
+    }
+    const orderedSteps = path.map((name) => steps.get(name));
+    const results = {};
+    for (const step of orderedSteps) {
+        if (step.status === 'succeeded') {
+            results[step.stepName] = step.result;
+        }
+    }
+    return {
+        seq: lastSeq,
+        at: lastAt,
+        steps: orderedSteps,
+        results,
+        path,
+        phase: derivePhase(orderedSteps),
+    };
+}
+/** Reconstruct the final state (fold the whole timeline). */
+export function reconstructFinalState(timeline) {
+    return reconstructStateAt(timeline, timeline.length - 1);
+}
+function derivePhase(steps) {
+    if (steps.length === 0)
+        return 'pending';
+    if (steps.some((s) => IN_FLIGHT.has(s.status)))
+        return 'running';
+    if (steps.some((s) => s.status === 'failed'))
+        return 'failed';
+    return 'idle';
+}

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 */
@@ -109,6 +112,8 @@ export interface WorkflowRunStatus {
         name: string;
         status: StepStatus;
         duration?: number;
+        /** Number of attempts for this step (1 = first try; > 1 means it retried). */
+        attempts?: number;
     }>;
     output?: unknown;
     error?: {
@@ -269,6 +274,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.37",
+  "version": "0.12.39",
   "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/errors/error-handler.ts

@@ -16,6 +16,16 @@ export class PikkuError extends Error {
   }
 }
 
+/**
+ * Whether an error is a deliberate, expected failure rather than an uncaught
+ * bug. A `PikkuError` always counts; so does any error carrying `expected:
+ * true` — used to keep the marker alive when an error is serialized across a
+ * workflow step boundary and rehydrated as a plain `Error`. Callers log the
+ * message alone for expected errors and the full stack for everything else.
+ */
+export const isExpectedError = (error: unknown): boolean =>
+  error instanceof PikkuError || (error as any)?.expected === true
+
 /**
  * Interface for error details.
  */

package/src/index.ts

@@ -93,6 +93,7 @@ export type {
 export { runQueueJob } from './wirings/queue/queue-runner.js'
 export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js'
 export { NotFoundError } from './errors/errors.js'
+export { PikkuError, isExpectedError } from './errors/error-handler.js'
 export type { EventHubService } from './wirings/channel/eventhub-service.js'
 export type { QueueService } from './wirings/queue/queue.types.js'
 export type { JWTService } from './services/jwt-service.js'

package/src/services/in-memory-queue-service.test.ts

@@ -0,0 +1,97 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryQueueService } from './in-memory-queue-service.js'
+import { wireQueueWorker } from '../wirings/queue/queue-runner.js'
+import { resetPikkuState, pikkuState } from '../pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: { error() {}, info() {}, warn() {}, debug() {} },
+  } as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: async () => ({}),
+  } as any)
+})
+
+// Register a queue worker whose handler runs `behavior` (which may throw) and
+// counts invocations. Returns the live call counter.
+const registerWorker = (
+  queueName: string,
+  behavior: (count: number) => void
+) => {
+  const calls = { count: 0 }
+  const funcId = `queue_${queueName}`
+  pikkuState(null, 'queue', 'meta')[queueName] = { pikkuFuncId: funcId, name: queueName }
+  pikkuState(null, 'function', 'meta')[funcId] = {
+    pikkuFuncId: funcId,
+    inputSchemaName: null,
+    outputSchemaName: null,
+    sessionless: true,
+  } as any
+  wireQueueWorker({
+    name: queueName,
+    func: {
+      auth: false,
+      func: async () => {
+        calls.count++
+        behavior(calls.count)
+      },
+    },
+  } as any)
+  return calls
+}
+
+const waitUntil = async (
+  predicate: () => boolean,
+  timeoutMs = 2000
+): Promise<boolean> => {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (predicate()) return true
+    await new Promise((r) => setTimeout(r, 10))
+  }
+  return predicate()
+}
+
+describe('InMemoryQueueService retry', () => {
+  test('redelivers a transiently-failing job until it succeeds', async () => {
+    const calls = registerWorker('flaky', (count) => {
+      if (count <= 2) throw new Error(`transient ${count}`)
+    })
+    const queue = new InMemoryQueueService()
+
+    await queue.add('flaky', {}, { attempts: 5, delay: 0 })
+
+    // Succeeds on the 3rd attempt; must not exceed the configured attempts.
+    assert.equal(await waitUntil(() => calls.count >= 3), true)
+    await new Promise((r) => setTimeout(r, 150))
+    assert.equal(calls.count, 3, 'should stop retrying once the job succeeds')
+  })
+
+  test('stops after `attempts` when a job always fails', async () => {
+    const calls = registerWorker('always-fails', () => {
+      throw new Error('boom')
+    })
+    const queue = new InMemoryQueueService()
+
+    await queue.add('always-fails', {}, { attempts: 3, delay: 0 })
+
+    assert.equal(await waitUntil(() => calls.count >= 3), true)
+    await new Promise((r) => setTimeout(r, 150))
+    assert.equal(calls.count, 3, 'must not redeliver beyond `attempts`')
+  })
+
+  test('runs once and does not retry when no attempts are configured', async () => {
+    const calls = registerWorker('no-retry', () => {
+      throw new Error('boom')
+    })
+    const queue = new InMemoryQueueService()
+
+    await queue.add('no-retry', {}, { delay: 0 })
+
+    await new Promise((r) => setTimeout(r, 150))
+    assert.equal(calls.count, 1, 'a job without attempts runs exactly once')
+  })
+})

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

@@ -5,6 +5,13 @@ import type {
 } from '../wirings/queue/queue.types.js'
 import { runQueueJob } from '../wirings/queue/queue-runner.js'
 
+/**
+ * In-process queue for local/dev runs. Schedules jobs on the macrotask queue
+ * (setTimeout) so dispatch is genuinely asynchronous — the same timing shape as
+ * a real queue — and redelivers a failed job up to `options.attempts` times with
+ * backoff, so a transiently-failing workflow step recovers exactly as it would
+ * on pg-boss/bullmq instead of being silently dropped on its first error.
+ */
 export class InMemoryQueueService implements QueueService {
   readonly supportsResults = false
   private jobCounter = 0
@@ -15,31 +22,59 @@ export class InMemoryQueueService implements QueueService {
     options?: JobOptions
   ): Promise<string> {
     const jobId = `inmem-${++this.jobCounter}`
+    const maxAttempts = Math.max(1, options?.attempts ?? 1)
+    let attemptsMade = 0
+    const createdAt = new Date()
 
-    const job: QueueJob<T> = {
-      id: jobId,
-      queueName,
-      data,
-      status: () => 'active',
-      pikkuUserId: options?.pikkuUserId,
-    }
-
-    const delay = options?.delay ?? 100 + Math.floor(Math.random() * 201)
-
-    setTimeout(async () => {
+    const runAttempt = async () => {
+      attemptsMade++
+      const job: QueueJob<T> = {
+        id: jobId,
+        queueName,
+        data,
+        status: () => 'active',
+        metadata: () => ({ attemptsMade, maxAttempts, createdAt }),
+        pikkuUserId: options?.pikkuUserId,
+      }
       try {
         await runQueueJob({ job })
       } catch (e: any) {
-        console.error(
-          `[InMemoryQueue] Job ${jobId} on ${queueName} failed:`,
-          e.message
-        )
+        if (attemptsMade < maxAttempts) {
+          // Transient failure — redeliver with backoff, mirroring a real queue.
+          setTimeout(runAttempt, this.backoffDelay(options?.backoff, attemptsMade))
+        } else {
+          console.error(
+            `[InMemoryQueue] Job ${jobId} on ${queueName} failed after ${attemptsMade} attempt(s):`,
+            e.message
+          )
+        }
       }
-    }, delay)
+    }
+
+    const delay = options?.delay ?? 100 + Math.floor(Math.random() * 201)
+    setTimeout(runAttempt, delay)
 
     return jobId
   }
 
+  /** Delay before the next redelivery, honoring the job's backoff policy. */
+  private backoffDelay(
+    backoff: JobOptions['backoff'],
+    attemptsMade: number
+  ): number {
+    const baseDelay = typeof backoff === 'object' ? (backoff.delay ?? 50) : 50
+    if (
+      backoff === 'exponential' ||
+      (typeof backoff === 'object' && backoff?.type === 'exponential')
+    ) {
+      return Math.min(2 ** (attemptsMade - 1) * baseDelay, 2000)
+    }
+    if (typeof backoff === 'object' && backoff?.type === 'fixed') {
+      return backoff.delay ?? 50
+    }
+    return 50
+  }
+
   async getJob(): Promise<null> {
     return null
   }

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

@@ -1,5 +1,6 @@
 import { randomUUID } from 'crypto'
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js'
+import { isExpectedError } from '../errors/error-handler.js'
 import type { SerializedError } from '../types/core.types.js'
 import type {
   WorkflowPlannedStep,
@@ -7,6 +8,7 @@ import type {
   WorkflowRunService,
   WorkflowRunWire,
   StepState,
+  StepStatus,
   WorkflowStatus,
   WorkflowVersionStatus,
   WorkflowStepOptions,
@@ -140,7 +142,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 +154,7 @@ export class InMemoryWorkflowService
       attemptCount: 1,
       retries: stepOptions?.retries,
       retryDelay: stepOptions?.retryDelay,
+      fromStepName,
       createdAt: now,
       updatedAt: now,
       stepName,
@@ -227,6 +231,7 @@ export class InMemoryWorkflowService
           name: error.name,
           message: error.message,
           stack: error.stack,
+          expected: isExpectedError(error),
         }
         step.failedAt = new Date()
         step.updatedAt = new Date()
@@ -281,6 +286,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 +451,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[]

package/src/services/workflow-service.ts

@@ -8,6 +8,10 @@ import type {
   WorkflowStatus,
   WorkflowVersionStatus,
 } from '../wirings/workflow/workflow.types.js'
+import type {
+  RunTimeline,
+  ReconstructedRunState,
+} from '../wirings/workflow/run-timeline.js'
 
 /**
  * Interface for workflow orchestration
@@ -29,6 +33,11 @@ export interface WorkflowService {
   getRun(id: string): Promise<WorkflowRun | null>
   getRunStatus(id: string): Promise<WorkflowRunStatus | null>
   getRunHistory(runId: string): Promise<Array<StepState & { stepName: string }>>
+  getRunTimeline(id: string): Promise<RunTimeline | null>
+  reconstructRunStateAt(
+    id: string,
+    at?: number | Date
+  ): Promise<ReconstructedRunState | null>
   updateRunStatus(
     id: string,
     status: WorkflowStatus,