@pikku/core 0.12.38 → 0.12.39

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

@@ -29,10 +29,11 @@ const resolveWorkflowMeta = (name) => {
 };
 const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 import { continueGraph, executeGraphStep, runWorkflowGraph, runFromMeta, } from './graph/graph-runner.js';
-import { PikkuError, addError } from '../../errors/error-handler.js';
+import { PikkuError, addError, isExpectedError, } 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';
+import { buildRunTimeline, reconstructStateAt, } from './run-timeline.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
@@ -293,6 +294,7 @@ export class PikkuWorkflowService {
                     status: step.status,
                     startedAt: step.runningAt ?? step.createdAt,
                     completedAt: step.succeededAt ?? step.failedAt,
+                    attempts: step.attemptCount,
                 });
             }
         }
@@ -302,6 +304,7 @@ export class PikkuWorkflowService {
             duration: s.startedAt && s.completedAt
                 ? s.completedAt.getTime() - s.startedAt.getTime()
                 : undefined,
+            attempts: s.attempts,
         }));
         return {
             id: run.id,
@@ -317,6 +320,30 @@ export class PikkuWorkflowService {
                 : undefined,
         };
     }
+    /**
+     * 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
+     */
+    async getRunTimeline(id) {
+        const run = await this.getRun(id);
+        if (!run)
+            return null;
+        return buildRunTimeline(await this.getRunHistory(id));
+    }
+    /**
+     * 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
+     */
+    async reconstructRunStateAt(id, at) {
+        const timeline = await this.getRunTimeline(id);
+        if (!timeline)
+            return null;
+        return reconstructStateAt(timeline, at ?? timeline.length - 1);
+    }
     /**
      * Update workflow run status
      * @param id - Run ID
@@ -390,6 +417,7 @@ export class PikkuWorkflowService {
             message: error.message,
             stack: error.stack,
             code: error.code,
+            expected: isExpectedError(error),
         };
         await this.safeMirror(() => this.mirror.setStepError(stepId, serialized));
     }
@@ -626,7 +654,12 @@ export class PikkuWorkflowService {
                         message: error.message,
                         stack: error.stack,
                     });
-                    getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, error);
+                    // An expected failure (a PikkuError, e.g. a build gate tripping) —
+                    // its message is the whole story, so don't dump the stack. The
+                    // `expected` flag survives the step-boundary rehydration that strips
+                    // the class. Anything else is an uncaught/unexpected error: log it in
+                    // full so the trace is there to debug.
+                    getSingletonServices().logger.error(`Workflow ${name} (run ${runId}) failed:`, isExpectedError(error) ? error.message : error);
                     throw error;
                 }
                 if (error.name === 'WorkflowDispatchException') {
@@ -924,17 +957,7 @@ export class PikkuWorkflowService {
                         }
                     }
                     else {
-                        result = await rpcService.rpcWithWire(rpcName, data, {
-                            workflowStep: {
-                                runId,
-                                stepId: stepState.stepId,
-                                invocationId: deriveInvocationId(runId, stepName),
-                                attemptCount: stepState.attemptCount,
-                                fromInvocationId: stepState.fromStepName
-                                    ? deriveInvocationId(runId, stepState.fromStepName)
-                                    : undefined,
-                            },
-                        });
+                        result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService);
                     }
                 }
                 // Store result and mark succeeded
@@ -1004,6 +1027,63 @@ export class PikkuWorkflowService {
         }
         return getSingletonServices().queueService;
     }
+    /**
+     * 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.
+     */
+    async invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService) {
+        return rpcService.rpcWithWire(rpcName, data, {
+            workflowStep: {
+                runId,
+                stepId: stepState.stepId,
+                invocationId: deriveInvocationId(runId, stepName),
+                attemptCount: stepState.attemptCount,
+                fromInvocationId: stepState.fromStepName
+                    ? deriveInvocationId(runId, stepState.fromStepName)
+                    : undefined,
+            },
+        });
+    }
+    /**
+     * 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.
+     */
+    async runInlineRetryLoop(stepState, retries, retryDelay, doWork, onError) {
+        let currentStepState = stepState;
+        while (true) {
+            try {
+                await this.setStepRunning(currentStepState.stepId);
+                const result = await doWork(currentStepState);
+                await this.setStepResult(currentStepState.stepId, result);
+                return result;
+            }
+            catch (error) {
+                if (onError)
+                    await onError(error);
+                // Record the error (marks step as failed)
+                await this.setStepError(currentStepState.stepId, error);
+                if (currentStepState.attemptCount < retries) {
+                    // Create a new pending retry attempt, then back off if configured.
+                    currentStepState = await this.createRetryAttempt(currentStepState.stepId, 'pending');
+                    if (retryDelay) {
+                        await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(retryDelay)));
+                    }
+                    // Continue loop to retry
+                }
+                else {
+                    // No more retries, fail the workflow
+                    throw error;
+                }
+            }
+        }
+    }
     async rpcStep(runId, logicalStepName, rpcName, data, rpcService, stepOptions) {
         // Capture the predecessor before nextStepKey advances the lineage to us.
         const fromStepName = this.lastStepName(runId);
@@ -1055,88 +1135,50 @@ export class PikkuWorkflowService {
             await this.setStepScheduled(stepState.stepId);
             throw new WorkflowAsyncException(runId, stepName);
         }
-        {
-            // Inline (no transport available) - execute locally with retry loop
-            const retries = resolvedStepOptions.retries ?? this.getConfig().retries;
-            const retryDelay = resolvedStepOptions.retryDelay;
-            let currentStepState = stepState;
-            while (true) {
-                try {
-                    await this.setStepRunning(currentStepState.stepId);
-                    // Check if the name refers to a workflow
-                    const workflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
-                    let result;
-                    if (workflowMeta) {
-                        const childWire = {
-                            type: 'workflow',
-                            id: rpcName,
-                            parentRunId: runId,
-                            pikkuUserId: rpcService.wire?.pikkuUserId,
-                        };
-                        const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: true });
-                        await this.setStepChildRunId(currentStepState.stepId, childRunId);
-                        // Poll until child workflow completes
-                        while (true) {
-                            const childRun = await this.getRun(childRunId);
-                            if (!childRun) {
-                                throw new WorkflowRunNotFoundError(childRunId);
-                            }
-                            if (WORKFLOW_END_STATES.has(childRun.status)) {
-                                if (childRun.status === 'failed') {
-                                    throw new Error(childRun.error?.message || 'Sub-workflow failed');
-                                }
-                                if (childRun.status === 'cancelled') {
-                                    throw new Error('Sub-workflow was cancelled');
-                                }
-                                result = childRun.output;
-                                break;
-                            }
-                            await new Promise((resolve) => setTimeout(resolve, 500));
-                        }
-                    }
-                    else {
-                        result = await rpcService.rpcWithWire(rpcName, data, {
-                            workflowStep: {
-                                runId,
-                                stepId: currentStepState.stepId,
-                                invocationId: deriveInvocationId(runId, stepName),
-                                attemptCount: currentStepState.attemptCount,
-                                fromInvocationId: currentStepState.fromStepName
-                                    ? deriveInvocationId(runId, currentStepState.fromStepName)
-                                    : undefined,
-                            },
-                        });
-                    }
-                    await this.setStepResult(currentStepState.stepId, result);
-                    return result;
-                }
-                catch (error) {
-                    if (error instanceof RPCNotFoundError) {
-                        await this.updateRunStatus(runId, 'suspended', undefined, {
-                            message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
-                            code: 'RPC_NOT_FOUND',
-                        });
-                        throw error;
+        // Inline (no transport available) - execute locally with the shared retry
+        // loop. The body resolves to a sub-workflow result or a plain RPC result.
+        const retries = resolvedStepOptions.retries ?? this.getConfig().retries;
+        const retryDelay = resolvedStepOptions.retryDelay;
+        return this.runInlineRetryLoop(stepState, retries, retryDelay, async (currentStepState) => {
+            // Check if the name refers to a workflow
+            const workflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
+            if (workflowMeta) {
+                const childWire = {
+                    type: 'workflow',
+                    id: rpcName,
+                    parentRunId: runId,
+                    pikkuUserId: rpcService.wire?.pikkuUserId,
+                };
+                const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: true });
+                await this.setStepChildRunId(currentStepState.stepId, childRunId);
+                // Poll until child workflow completes
+                while (true) {
+                    const childRun = await this.getRun(childRunId);
+                    if (!childRun) {
+                        throw new WorkflowRunNotFoundError(childRunId);
                     }
-                    // Record the error (marks step as failed)
-                    await this.setStepError(currentStepState.stepId, error);
-                    // Check if we should retry
-                    if (currentStepState.attemptCount < retries) {
-                        // Create a new pending retry attempt
-                        currentStepState = await this.createRetryAttempt(currentStepState.stepId, 'pending');
-                        // Wait for retry delay if specified
-                        if (retryDelay) {
-                            await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(retryDelay)));
+                    if (WORKFLOW_END_STATES.has(childRun.status)) {
+                        if (childRun.status === 'failed') {
+                            throw new Error(childRun.error?.message || 'Sub-workflow failed');
                         }
-                        // Continue loop to retry
-                    }
-                    else {
-                        // No more retries, fail the workflow
-                        throw error;
+                        if (childRun.status === 'cancelled') {
+                            throw new Error('Sub-workflow was cancelled');
+                        }
+                        return childRun.output;
                     }
+                    await new Promise((resolve) => setTimeout(resolve, 500));
                 }
             }
-        }
+            return this.invokeStepRpc(runId, stepName, currentStepState, rpcName, data, rpcService);
+        }, async (error) => {
+            if (error instanceof RPCNotFoundError) {
+                await this.updateRunStatus(runId, 'suspended', undefined, {
+                    message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
+                    code: 'RPC_NOT_FOUND',
+                });
+                throw error;
+            }
+        });
     }
     async inlineStep(runId, logicalStepName, fn, stepOptions) {
         const fromStepName = this.lastStepName(runId);
@@ -1157,39 +1199,14 @@ export class PikkuWorkflowService {
         // Execute inline function
         const retries = stepOptions?.retries ?? this.getConfig().retries;
         const retryDelay = stepOptions?.retryDelay ?? this.getConfig().retryDelay;
-        let currentStepState = stepState;
         // Check if we're running inline (in-memory) or remote (queue-based)
         if (this.isInline(runId)) {
-            // Inline mode - execute with retry loop
-            while (true) {
-                try {
-                    await this.setStepRunning(currentStepState.stepId);
-                    const result = await fn();
-                    await this.setStepResult(currentStepState.stepId, result);
-                    return result;
-                }
-                catch (error) {
-                    // Record the error (marks step as failed)
-                    await this.setStepError(currentStepState.stepId, error);
-                    // Check if we should retry
-                    if (currentStepState.attemptCount < retries) {
-                        // Create a new pending retry attempt
-                        currentStepState = await this.createRetryAttempt(currentStepState.stepId, 'pending');
-                        // Wait for retry delay if specified
-                        if (retryDelay) {
-                            await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(retryDelay)));
-                        }
-                        // Continue loop to retry
-                    }
-                    else {
-                        // No more retries, fail the workflow
-                        throw error;
-                    }
-                }
-            }
+            // Inline mode - execute with the shared in-process retry loop.
+            return this.runInlineRetryLoop(stepState, retries, retryDelay, () => fn());
         }
         else {
-            // Remote mode - use queue-based retry
+            // Remote mode - single attempt, then suspend for orchestrator-driven retry.
+            let currentStepState = stepState;
             try {
                 await this.setStepRunning(currentStepState.stepId);
                 const result = await fn();

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.types.d.ts

@@ -112,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?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.38",
+  "version": "0.12.39",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

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'