@workflow/world-postgres 4.1.0-beta.29 → 4.1.0-beta.31

package/dist/storage.js

@@ -1,121 +1,67 @@
-import { WorkflowAPIError } from '@workflow/errors';
-import { EventSchema, HookSchema, StepSchema, WorkflowRunSchema, } from '@workflow/world';
-import { and, desc, eq, gt, lt, sql } from 'drizzle-orm';
+import { RunNotSupportedError, WorkflowAPIError } from '@workflow/errors';
+import { EventSchema, HookSchema, isLegacySpecVersion, requiresNewerWorld, SPEC_VERSION_CURRENT, StepSchema, WorkflowRunSchema, } from '@workflow/world';
+import { and, desc, eq, gt, lt, notInArray, sql } from 'drizzle-orm';
 import { monotonicFactory } from 'ulid';
 import { Schema } from './drizzle/index.js';
 import { compact } from './util.js';
 /**
- * Serialize a StructuredError object into a JSON string
+ * Parse legacy errorJson (text column with JSON-stringified StructuredError).
+ * Used for backwards compatibility when reading from deprecated error column.
  */
-function serializeRunError(data) {
-    if (!data.error) {
-        return data;
+function parseErrorJson(errorJson) {
+    if (!errorJson)
+        return null;
+    try {
+        const parsed = JSON.parse(errorJson);
+        if (typeof parsed === 'object' && parsed.message !== undefined) {
+            return {
+                message: parsed.message,
+                stack: parsed.stack,
+                code: parsed.code,
+            };
+        }
+        // Not a structured error object, treat as plain string
+        return { message: String(parsed) };
+    }
+    catch {
+        // Not JSON, treat as plain string error message
+        return { message: errorJson };
     }
-    const { error, ...rest } = data;
-    return {
-        ...rest,
-        error: JSON.stringify({
-            message: error.message,
-            stack: error.stack,
-            code: error.code,
-        }),
-    };
 }
 /**
- * Deserialize error JSON string (or legacy flat fields) into a StructuredError object
- * Handles backwards compatibility:
- * - If error is a JSON string with {message, stack, code} → parse into StructuredError
- * - If error is a plain string → treat as error message
- * - If errorStack/errorCode exist (legacy) → combine into StructuredError
+ * Deserialize run data, handling legacy error fields.
+ * The error field should already be deserialized from CBOR or fallback to errorJson.
+ * This function only handles very old legacy fields (errorStack, errorCode).
  */
 function deserializeRunError(run) {
-    const { error, errorStack, errorCode, ...rest } = run;
-    if (!error && !errorStack && !errorCode) {
-        return run;
-    }
-    // Try to parse as structured error JSON
-    if (error) {
-        try {
-            const parsed = JSON.parse(error);
-            if (typeof parsed === 'object' && parsed.message !== undefined) {
-                return {
-                    ...rest,
-                    error: {
-                        message: parsed.message,
-                        stack: parsed.stack,
-                        code: parsed.code,
-                    },
-                };
-            }
-        }
-        catch {
-            // Not JSON, treat as plain string
-        }
+    const { errorStack, errorCode, ...rest } = run;
+    // If no legacy fields, return as-is (error is already a StructuredError or undefined)
+    if (!errorStack && !errorCode) {
+        return rest;
     }
-    // Backwards compatibility: handle legacy separate fields or plain string error
+    // Very old legacy: separate errorStack/errorCode fields
+    const existingError = rest.error;
     return {
         ...rest,
         error: {
-            message: error || '',
-            stack: errorStack,
-            code: errorCode,
+            message: existingError?.message || '',
+            stack: existingError?.stack || errorStack,
+            code: existingError?.code || errorCode,
         },
     };
 }
 /**
- * Serialize a StructuredError object into a JSON string for steps
- */
-function serializeStepError(data) {
-    if (!data.error) {
-        return data;
-    }
-    const { error, ...rest } = data;
-    return {
-        ...rest,
-        error: JSON.stringify({
-            message: error.message,
-            stack: error.stack,
-            code: error.code,
-        }),
-    };
-}
-/**
- * Deserialize error JSON string (or legacy flat fields) into a StructuredError object for steps
+ * Deserialize step data, mapping DB columns to interface fields.
+ * The error field should already be deserialized from CBOR or fallback to errorJson.
  */
 function deserializeStepError(step) {
-    const { error, ...rest } = step;
-    if (!error) {
-        return step;
-    }
-    // Try to parse as structured error JSON
-    if (error) {
-        try {
-            const parsed = JSON.parse(error);
-            if (typeof parsed === 'object' && parsed.message !== undefined) {
-                return {
-                    ...rest,
-                    error: {
-                        message: parsed.message,
-                        stack: parsed.stack,
-                        code: parsed.code,
-                    },
-                };
-            }
-        }
-        catch {
-            // Not JSON, treat as plain string
-        }
-    }
-    // Backwards compatibility: handle legacy separate fields or plain string error
+    const { startedAt, ...rest } = step;
     return {
         ...rest,
-        error: {
-            message: error || '',
-        },
+        startedAt,
     };
 }
 export function createRunsStorage(drizzle) {
-    const ulid = monotonicFactory();
     const { runs } = Schema;
     const get = drizzle
         .select()
@@ -124,7 +70,7 @@ export function createRunsStorage(drizzle) {
         .limit(1)
         .prepare('workflow_runs_get');
     return {
-        async get(id, params) {
+        get: (async (id, params) => {
             const [value] = await get.execute({ id });
             if (!value) {
                 throw new WorkflowAPIError(`Run not found: ${id}`, { status: 404 });
@@ -132,29 +78,13 @@ export function createRunsStorage(drizzle) {
             value.output ||= value.outputJson;
             value.input ||= value.inputJson;
             value.executionContext ||= value.executionContextJson;
+            value.error ||= parseErrorJson(value.errorJson);
             const deserialized = deserializeRunError(compact(value));
             const parsed = WorkflowRunSchema.parse(deserialized);
             const resolveData = params?.resolveData ?? 'all';
             return filterRunData(parsed, resolveData);
-        },
-        async cancel(id, params) {
-            // TODO: we might want to guard this for only specific statuses
-            const [value] = await drizzle
-                .update(Schema.runs)
-                .set({ status: 'cancelled', completedAt: sql `now()` })
-                .where(eq(runs.runId, id))
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Run not found: ${id}`, { status: 404 });
-            }
-            // Clean up all hooks for this run when cancelling
-            await drizzle.delete(Schema.hooks).where(eq(Schema.hooks.runId, id));
-            const deserialized = deserializeRunError(compact(value));
-            const parsed = WorkflowRunSchema.parse(deserialized);
-            const resolveData = params?.resolveData ?? 'all';
-            return filterRunData(parsed, resolveData);
-        },
-        async list(params) {
+        }),
+        list: (async (params) => {
             const limit = params?.pagination?.limit ?? 20;
             const fromCursor = params?.pagination?.cursor;
             const all = await drizzle
@@ -168,6 +98,10 @@ export function createRunsStorage(drizzle) {
             const resolveData = params?.resolveData ?? 'all';
             return {
                 data: values.map((v) => {
+                    v.output ||= v.outputJson;
+                    v.input ||= v.inputJson;
+                    v.executionContext ||= v.executionContextJson;
+                    v.error ||= parseErrorJson(v.errorJson);
                     const deserialized = deserializeRunError(compact(v));
                     const parsed = WorkflowRunSchema.parse(deserialized);
                     return filterRunData(parsed, resolveData);
@@ -175,87 +109,593 @@ export function createRunsStorage(drizzle) {
                 hasMore,
                 cursor: values.at(-1)?.runId ?? null,
             };
-        },
-        async create(data) {
-            const runId = `wrun_${ulid()}`;
-            const [value] = await drizzle
-                .insert(runs)
-                .values({
-                runId,
-                input: data.input,
-                executionContext: data.executionContext,
-                deploymentId: data.deploymentId,
-                status: 'pending',
-                workflowName: data.workflowName,
-            })
-                .onConflictDoNothing()
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Run ${runId} already exists`, {
-                    status: 409,
-                });
-            }
-            return deserializeRunError(compact(value));
-        },
-        async update(id, data) {
-            // Fetch current run to check if startedAt is already set
-            const [currentRun] = await drizzle
-                .select()
-                .from(runs)
-                .where(eq(runs.runId, id))
-                .limit(1);
-            if (!currentRun) {
-                throw new WorkflowAPIError(`Run not found: ${id}`, { status: 404 });
-            }
-            // Serialize the error field if present
-            const serialized = serializeRunError(data);
-            const updates = {
-                ...serialized,
-                output: data.output,
-            };
-            // Only set startedAt the first time transitioning to 'running'
-            if (data.status === 'running' && !currentRun.startedAt) {
-                updates.startedAt = new Date();
-            }
-            const isBecomingTerminal = data.status === 'completed' ||
-                data.status === 'failed' ||
-                data.status === 'cancelled';
-            if (isBecomingTerminal) {
-                updates.completedAt = new Date();
-            }
-            const [value] = await drizzle
-                .update(runs)
-                .set(updates)
-                .where(eq(runs.runId, id))
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Run not found: ${id}`, { status: 404 });
-            }
-            // If transitioning to a terminal status, clean up all hooks for this run
-            if (isBecomingTerminal) {
-                await drizzle.delete(Schema.hooks).where(eq(Schema.hooks.runId, id));
-            }
-            return deserializeRunError(compact(value));
-        },
+        }),
     };
 }
 function map(obj, fn) {
     return obj ? fn(obj) : undefined;
 }
+/**
+ * Handle events for legacy runs (pre-event-sourcing, specVersion < 2).
+ * Legacy runs use different behavior:
+ * - run_cancelled: Skip event storage, directly update run
+ * - wait_completed: Store event only (no entity mutation)
+ * - hook_received: Store event only (hooks exist via old system, no entity mutation)
+ * - Other events: Throw error (not supported for legacy runs)
+ */
+async function handleLegacyEventPostgres(drizzle, runId, eventId, data, currentRun, params) {
+    const resolveData = params?.resolveData ?? 'all';
+    switch (data.eventType) {
+        case 'run_cancelled': {
+            // Legacy: Skip event storage, directly update run to cancelled
+            const now = new Date();
+            // Update run status to cancelled
+            await drizzle
+                .update(Schema.runs)
+                .set({
+                status: 'cancelled',
+                completedAt: now,
+                updatedAt: now,
+            })
+                .where(eq(Schema.runs.runId, runId));
+            // Delete all hooks for this run
+            await drizzle.delete(Schema.hooks).where(eq(Schema.hooks.runId, runId));
+            // Fetch updated run for return value
+            const [updatedRun] = await drizzle
+                .select()
+                .from(Schema.runs)
+                .where(eq(Schema.runs.runId, runId))
+                .limit(1);
+            // Return without event (legacy behavior skips event storage)
+            // Type assertion: EventResult expects WorkflowRun, filterRunData may return WorkflowRunWithoutData
+            return {
+                run: updatedRun
+                    ? filterRunData(deserializeRunError(compact(updatedRun)), resolveData)
+                    : undefined,
+            };
+        }
+        case 'wait_completed':
+        case 'hook_received': {
+            // Legacy: Store event only (no entity mutation)
+            // - wait_completed: for replay purposes
+            // - hook_received: hooks exist via old system, just record the event
+            const [insertedEvent] = await drizzle
+                .insert(Schema.events)
+                .values({
+                runId,
+                eventId,
+                correlationId: data.correlationId,
+                eventType: data.eventType,
+                eventData: 'eventData' in data ? data.eventData : undefined,
+                specVersion: SPEC_VERSION_CURRENT,
+            })
+                .returning({ createdAt: Schema.events.createdAt });
+            const event = EventSchema.parse({
+                ...data,
+                ...insertedEvent,
+                runId,
+                eventId,
+            });
+            return { event: filterEventData(event, resolveData) };
+        }
+        default:
+            throw new Error(`Event type '${data.eventType}' not supported for legacy runs ` +
+                `(specVersion: ${currentRun.specVersion || 'undefined'}). ` +
+                `Please upgrade @workflow packages.`);
+    }
+}
 export function createEventsStorage(drizzle) {
     const ulid = monotonicFactory();
     const { events } = Schema;
+    // Prepared statements for validation queries (performance optimization)
+    const getRunForValidation = drizzle
+        .select({
+        status: Schema.runs.status,
+        specVersion: Schema.runs.specVersion,
+    })
+        .from(Schema.runs)
+        .where(eq(Schema.runs.runId, sql.placeholder('runId')))
+        .limit(1)
+        .prepare('events_get_run_for_validation');
+    const getStepForValidation = drizzle
+        .select({
+        status: Schema.steps.status,
+        startedAt: Schema.steps.startedAt,
+        retryAfter: Schema.steps.retryAfter,
+    })
+        .from(Schema.steps)
+        .where(and(eq(Schema.steps.runId, sql.placeholder('runId')), eq(Schema.steps.stepId, sql.placeholder('stepId'))))
+        .limit(1)
+        .prepare('events_get_step_for_validation');
+    const getHookByToken = drizzle
+        .select({ hookId: Schema.hooks.hookId })
+        .from(Schema.hooks)
+        .where(eq(Schema.hooks.token, sql.placeholder('token')))
+        .limit(1)
+        .prepare('events_get_hook_by_token');
     return {
         async create(runId, data, params) {
             const eventId = `wevt_${ulid()}`;
+            // For run_created events, generate runId server-side if null or empty
+            let effectiveRunId;
+            if (data.eventType === 'run_created' && (!runId || runId === '')) {
+                effectiveRunId = `wrun_${ulid()}`;
+            }
+            else if (!runId) {
+                throw new Error('runId is required for non-run_created events');
+            }
+            else {
+                effectiveRunId = runId;
+            }
+            // specVersion is always sent by the runtime, but we provide a fallback for safety
+            const effectiveSpecVersion = data.specVersion ?? SPEC_VERSION_CURRENT;
+            // Track entity created/updated for EventResult
+            let run;
+            let step;
+            let hook;
+            const now = new Date();
+            // Helper to check if run is in terminal state
+            const isRunTerminal = (status) => ['completed', 'failed', 'cancelled'].includes(status);
+            // Helper to check if step is in terminal state
+            const isStepTerminal = (status) => ['completed', 'failed'].includes(status);
+            // ============================================================
+            // VALIDATION: Terminal state and event ordering checks
+            // ============================================================
+            // Get current run state for validation (if not creating a new run)
+            // Skip run validation for step_completed and step_retrying - they only operate
+            // on running steps, and running steps are always allowed to modify regardless
+            // of run state. This optimization saves database queries per step event.
+            let currentRun = null;
+            const skipRunValidationEvents = ['step_completed', 'step_retrying'];
+            if (data.eventType !== 'run_created' &&
+                !skipRunValidationEvents.includes(data.eventType)) {
+                // Use prepared statement for better performance
+                const [runValue] = await getRunForValidation.execute({
+                    runId: effectiveRunId,
+                });
+                currentRun = runValue ?? null;
+            }
+            // ============================================================
+            // VERSION COMPATIBILITY: Check run spec version
+            // ============================================================
+            // For events that have fetched the run, check version compatibility.
+            // Skip for run_created (no existing run) and runtime events (step_completed, step_retrying).
+            if (currentRun) {
+                // Check if run requires a newer world version
+                if (requiresNewerWorld(currentRun.specVersion)) {
+                    throw new RunNotSupportedError(currentRun.specVersion, SPEC_VERSION_CURRENT);
+                }
+                // Route to legacy handler for pre-event-sourcing runs
+                if (isLegacySpecVersion(currentRun.specVersion)) {
+                    return handleLegacyEventPostgres(drizzle, effectiveRunId, eventId, data, currentRun, params);
+                }
+            }
+            // Run terminal state validation
+            if (currentRun && isRunTerminal(currentRun.status)) {
+                const runTerminalEvents = [
+                    'run_started',
+                    'run_completed',
+                    'run_failed',
+                ];
+                // Idempotent operation: run_cancelled on already cancelled run is allowed
+                if (data.eventType === 'run_cancelled' &&
+                    currentRun.status === 'cancelled') {
+                    // Get full run for return value
+                    const [fullRun] = await drizzle
+                        .select()
+                        .from(Schema.runs)
+                        .where(eq(Schema.runs.runId, effectiveRunId))
+                        .limit(1);
+                    // Create the event (still record it)
+                    const [value] = await drizzle
+                        .insert(Schema.events)
+                        .values({
+                        runId: effectiveRunId,
+                        eventId,
+                        correlationId: data.correlationId,
+                        eventType: data.eventType,
+                        eventData: 'eventData' in data ? data.eventData : undefined,
+                        specVersion: effectiveSpecVersion,
+                    })
+                        .returning({ createdAt: Schema.events.createdAt });
+                    const result = { ...data, ...value, runId: effectiveRunId, eventId };
+                    const parsed = EventSchema.parse(result);
+                    const resolveData = params?.resolveData ?? 'all';
+                    return {
+                        event: filterEventData(parsed, resolveData),
+                        run: fullRun ? deserializeRunError(compact(fullRun)) : undefined,
+                    };
+                }
+                // Run state transitions are not allowed on terminal runs
+                if (runTerminalEvents.includes(data.eventType) ||
+                    data.eventType === 'run_cancelled') {
+                    throw new WorkflowAPIError(`Cannot transition run from terminal state "${currentRun.status}"`, { status: 409 });
+                }
+                // Creating new entities on terminal runs is not allowed
+                if (data.eventType === 'step_created' ||
+                    data.eventType === 'hook_created') {
+                    throw new WorkflowAPIError(`Cannot create new entities on run in terminal state "${currentRun.status}"`, { status: 409 });
+                }
+            }
+            // Step-related event validation (ordering and terminal state)
+            // Fetch status + startedAt so we can reuse for step_started (avoid double read)
+            // Skip validation for step_completed/step_failed - use conditional UPDATE instead
+            let validatedStep = null;
+            const stepEventsNeedingValidation = ['step_started', 'step_retrying'];
+            if (stepEventsNeedingValidation.includes(data.eventType) &&
+                data.correlationId) {
+                // Use prepared statement for better performance
+                const [existingStep] = await getStepForValidation.execute({
+                    runId: effectiveRunId,
+                    stepId: data.correlationId,
+                });
+                validatedStep = existingStep ?? null;
+                // Event ordering: step must exist before these events
+                if (!validatedStep) {
+                    throw new WorkflowAPIError(`Step "${data.correlationId}" not found`, {
+                        status: 404,
+                    });
+                }
+                // Step terminal state validation
+                if (isStepTerminal(validatedStep.status)) {
+                    throw new WorkflowAPIError(`Cannot modify step in terminal state "${validatedStep.status}"`, { status: 409 });
+                }
+                // On terminal runs: only allow completing/failing in-progress steps
+                if (currentRun && isRunTerminal(currentRun.status)) {
+                    if (validatedStep.status !== 'running') {
+                        throw new WorkflowAPIError(`Cannot modify non-running step on run in terminal state "${currentRun.status}"`, { status: 410 });
+                    }
+                }
+            }
+            // Hook-related event validation (ordering)
+            const hookEventsRequiringExistence = ['hook_disposed', 'hook_received'];
+            if (hookEventsRequiringExistence.includes(data.eventType) &&
+                data.correlationId) {
+                const [existingHook] = await drizzle
+                    .select({ hookId: Schema.hooks.hookId })
+                    .from(Schema.hooks)
+                    .where(eq(Schema.hooks.hookId, data.correlationId))
+                    .limit(1);
+                if (!existingHook) {
+                    throw new WorkflowAPIError(`Hook "${data.correlationId}" not found`, {
+                        status: 404,
+                    });
+                }
+            }
+            // ============================================================
+            // Entity creation/updates based on event type
+            // ============================================================
+            // Handle run_created event: create the run entity atomically
+            if (data.eventType === 'run_created') {
+                const eventData = data.eventData;
+                const [runValue] = await drizzle
+                    .insert(Schema.runs)
+                    .values({
+                    runId: effectiveRunId,
+                    deploymentId: eventData.deploymentId,
+                    workflowName: eventData.workflowName,
+                    // Propagate specVersion from the event to the run entity
+                    specVersion: effectiveSpecVersion,
+                    input: eventData.input,
+                    executionContext: eventData.executionContext,
+                    status: 'pending',
+                })
+                    .onConflictDoNothing()
+                    .returning();
+                if (runValue) {
+                    run = deserializeRunError(compact(runValue));
+                }
+            }
+            // Handle run_started event: update run status
+            if (data.eventType === 'run_started') {
+                const [runValue] = await drizzle
+                    .update(Schema.runs)
+                    .set({
+                    status: 'running',
+                    startedAt: now,
+                    updatedAt: now,
+                })
+                    .where(eq(Schema.runs.runId, effectiveRunId))
+                    .returning();
+                if (runValue) {
+                    run = deserializeRunError(compact(runValue));
+                }
+            }
+            // Handle run_completed event: update run status and cleanup hooks
+            if (data.eventType === 'run_completed') {
+                const eventData = data.eventData;
+                const [runValue] = await drizzle
+                    .update(Schema.runs)
+                    .set({
+                    status: 'completed',
+                    output: eventData.output,
+                    completedAt: now,
+                    updatedAt: now,
+                })
+                    .where(eq(Schema.runs.runId, effectiveRunId))
+                    .returning();
+                if (runValue) {
+                    run = deserializeRunError(compact(runValue));
+                }
+                // Delete all hooks for this run to allow token reuse
+                await drizzle
+                    .delete(Schema.hooks)
+                    .where(eq(Schema.hooks.runId, effectiveRunId));
+            }
+            // Handle run_failed event: update run status and cleanup hooks
+            if (data.eventType === 'run_failed') {
+                const eventData = data.eventData;
+                const errorMessage = typeof eventData.error === 'string'
+                    ? eventData.error
+                    : (eventData.error?.message ?? 'Unknown error');
+                const [runValue] = await drizzle
+                    .update(Schema.runs)
+                    .set({
+                    status: 'failed',
+                    error: {
+                        message: errorMessage,
+                        stack: eventData.error?.stack,
+                        code: eventData.errorCode,
+                    },
+                    completedAt: now,
+                    updatedAt: now,
+                })
+                    .where(eq(Schema.runs.runId, effectiveRunId))
+                    .returning();
+                if (runValue) {
+                    run = deserializeRunError(compact(runValue));
+                }
+                // Delete all hooks for this run to allow token reuse
+                await drizzle
+                    .delete(Schema.hooks)
+                    .where(eq(Schema.hooks.runId, effectiveRunId));
+            }
+            // Handle run_cancelled event: update run status and cleanup hooks
+            if (data.eventType === 'run_cancelled') {
+                const [runValue] = await drizzle
+                    .update(Schema.runs)
+                    .set({
+                    status: 'cancelled',
+                    completedAt: now,
+                    updatedAt: now,
+                })
+                    .where(eq(Schema.runs.runId, effectiveRunId))
+                    .returning();
+                if (runValue) {
+                    run = deserializeRunError(compact(runValue));
+                }
+                // Delete all hooks for this run to allow token reuse
+                await drizzle
+                    .delete(Schema.hooks)
+                    .where(eq(Schema.hooks.runId, effectiveRunId));
+            }
+            // Handle step_created event: create step entity
+            if (data.eventType === 'step_created') {
+                const eventData = data.eventData;
+                const [stepValue] = await drizzle
+                    .insert(Schema.steps)
+                    .values({
+                    runId: effectiveRunId,
+                    stepId: data.correlationId,
+                    stepName: eventData.stepName,
+                    input: eventData.input,
+                    status: 'pending',
+                    attempt: 0,
+                    // Propagate specVersion from the event to the step entity
+                    specVersion: effectiveSpecVersion,
+                })
+                    .onConflictDoNothing()
+                    .returning();
+                if (stepValue) {
+                    step = deserializeStepError(compact(stepValue));
+                }
+            }
+            // Handle step_started event: increment attempt, set status to 'running'
+            // Sets startedAt (maps to startedAt) only on first start
+            // Reuse validatedStep from validation (already read above)
+            if (data.eventType === 'step_started') {
+                // Check if retryAfter timestamp hasn't been reached yet
+                if (validatedStep?.retryAfter &&
+                    validatedStep.retryAfter.getTime() > Date.now()) {
+                    const err = new WorkflowAPIError(`Cannot start step "${data.correlationId}": retryAfter timestamp has not been reached yet`, { status: 425 });
+                    // Add meta for step-handler to extract retryAfter timestamp
+                    err.meta = {
+                        stepId: data.correlationId,
+                        retryAfter: validatedStep.retryAfter.toISOString(),
+                    };
+                    throw err;
+                }
+                const isFirstStart = !validatedStep?.startedAt;
+                const hadRetryAfter = !!validatedStep?.retryAfter;
+                const [stepValue] = await drizzle
+                    .update(Schema.steps)
+                    .set({
+                    status: 'running',
+                    // Increment attempt counter using SQL
+                    attempt: sql `${Schema.steps.attempt} + 1`,
+                    // Only set startedAt on first start (not updated on retries)
+                    ...(isFirstStart ? { startedAt: now } : {}),
+                    // Clear retryAfter now that the step has started
+                    ...(hadRetryAfter ? { retryAfter: null } : {}),
+                })
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId)))
+                    .returning();
+                if (stepValue) {
+                    step = deserializeStepError(compact(stepValue));
+                }
+            }
+            // Handle step_completed event: update step status
+            // Uses conditional UPDATE to skip validation query (performance optimization)
+            if (data.eventType === 'step_completed') {
+                const eventData = data.eventData;
+                const [stepValue] = await drizzle
+                    .update(Schema.steps)
+                    .set({
+                    status: 'completed',
+                    output: eventData.result,
+                    completedAt: now,
+                })
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId), 
+                // Only update if not already in terminal state (validation in WHERE clause)
+                notInArray(Schema.steps.status, ['completed', 'failed'])))
+                    .returning();
+                if (stepValue) {
+                    step = deserializeStepError(compact(stepValue));
+                }
+                else {
+                    // Step not updated - check if it exists and why
+                    const [existing] = await getStepForValidation.execute({
+                        runId: effectiveRunId,
+                        stepId: data.correlationId,
+                    });
+                    if (!existing) {
+                        throw new WorkflowAPIError(`Step "${data.correlationId}" not found`, { status: 404 });
+                    }
+                    if (['completed', 'failed'].includes(existing.status)) {
+                        throw new WorkflowAPIError(`Cannot modify step in terminal state "${existing.status}"`, { status: 409 });
+                    }
+                }
+            }
+            // Handle step_failed event: terminal state with error
+            // Uses conditional UPDATE to skip validation query (performance optimization)
+            if (data.eventType === 'step_failed') {
+                const eventData = data.eventData;
+                const errorMessage = typeof eventData.error === 'string'
+                    ? eventData.error
+                    : (eventData.error?.message ?? 'Unknown error');
+                const [stepValue] = await drizzle
+                    .update(Schema.steps)
+                    .set({
+                    status: 'failed',
+                    error: {
+                        message: errorMessage,
+                        stack: eventData.stack,
+                    },
+                    completedAt: now,
+                })
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId), 
+                // Only update if not already in terminal state (validation in WHERE clause)
+                notInArray(Schema.steps.status, ['completed', 'failed'])))
+                    .returning();
+                if (stepValue) {
+                    step = deserializeStepError(compact(stepValue));
+                }
+                else {
+                    // Step not updated - check if it exists and why
+                    const [existing] = await getStepForValidation.execute({
+                        runId: effectiveRunId,
+                        stepId: data.correlationId,
+                    });
+                    if (!existing) {
+                        throw new WorkflowAPIError(`Step "${data.correlationId}" not found`, { status: 404 });
+                    }
+                    if (['completed', 'failed'].includes(existing.status)) {
+                        throw new WorkflowAPIError(`Cannot modify step in terminal state "${existing.status}"`, { status: 409 });
+                    }
+                }
+            }
+            // Handle step_retrying event: sets status back to 'pending', records error
+            if (data.eventType === 'step_retrying') {
+                const eventData = data.eventData;
+                const errorMessage = typeof eventData.error === 'string'
+                    ? eventData.error
+                    : (eventData.error?.message ?? 'Unknown error');
+                const [stepValue] = await drizzle
+                    .update(Schema.steps)
+                    .set({
+                    status: 'pending',
+                    error: {
+                        message: errorMessage,
+                        stack: eventData.stack,
+                    },
+                    retryAfter: eventData.retryAfter,
+                })
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId)))
+                    .returning();
+                if (stepValue) {
+                    step = deserializeStepError(compact(stepValue));
+                }
+            }
+            // Handle hook_created event: create hook entity
+            // Uses prepared statement for token uniqueness check (performance optimization)
+            if (data.eventType === 'hook_created') {
+                const eventData = data.eventData;
+                // Check for duplicate token using prepared statement
+                const [existingHook] = await getHookByToken.execute({
+                    token: eventData.token,
+                });
+                if (existingHook) {
+                    // Create hook_conflict event instead of throwing 409
+                    // This allows the workflow to continue and fail gracefully when the hook is awaited
+                    const conflictEventData = {
+                        token: eventData.token,
+                    };
+                    const [conflictValue] = await drizzle
+                        .insert(events)
+                        .values({
+                        runId: effectiveRunId,
+                        eventId,
+                        correlationId: data.correlationId,
+                        eventType: 'hook_conflict',
+                        eventData: conflictEventData,
+                        specVersion: effectiveSpecVersion,
+                    })
+                        .returning({ createdAt: events.createdAt });
+                    if (!conflictValue) {
+                        throw new WorkflowAPIError(`Event ${eventId} could not be created`, { status: 409 });
+                    }
+                    const conflictResult = {
+                        eventType: 'hook_conflict',
+                        correlationId: data.correlationId,
+                        eventData: conflictEventData,
+                        ...conflictValue,
+                        runId: effectiveRunId,
+                        eventId,
+                    };
+                    const parsedConflict = EventSchema.parse(conflictResult);
+                    const resolveData = params?.resolveData ?? 'all';
+                    return {
+                        event: filterEventData(parsedConflict, resolveData),
+                        run,
+                        step,
+                        hook: undefined,
+                    };
+                }
+                const [hookValue] = await drizzle
+                    .insert(Schema.hooks)
+                    .values({
+                    runId: effectiveRunId,
+                    hookId: data.correlationId,
+                    token: eventData.token,
+                    metadata: eventData.metadata,
+                    ownerId: '', // TODO: get from context
+                    projectId: '', // TODO: get from context
+                    environment: '', // TODO: get from context
+                    // Propagate specVersion from the event to the hook entity
+                    specVersion: effectiveSpecVersion,
+                })
+                    .onConflictDoNothing()
+                    .returning();
+                if (hookValue) {
+                    hookValue.metadata ||= hookValue.metadataJson;
+                    hook = HookSchema.parse(compact(hookValue));
+                }
+            }
+            // Handle hook_disposed event: delete hook entity
+            if (data.eventType === 'hook_disposed' && data.correlationId) {
+                await drizzle
+                    .delete(Schema.hooks)
+                    .where(eq(Schema.hooks.hookId, data.correlationId));
+            }
             const [value] = await drizzle
                 .insert(events)
                 .values({
-                runId,
+                runId: effectiveRunId,
                 eventId,
                 correlationId: data.correlationId,
                 eventType: data.eventType,
                 eventData: 'eventData' in data ? data.eventData : undefined,
+                specVersion: effectiveSpecVersion,
             })
                 .returning({ createdAt: events.createdAt });
             if (!value) {
@@ -263,10 +703,10 @@ export function createEventsStorage(drizzle) {
                     status: 409,
                 });
             }
-            const result = { ...data, ...value, runId, eventId };
+            const result = { ...data, ...value, runId: effectiveRunId, eventId };
             const parsed = EventSchema.parse(result);
             const resolveData = params?.resolveData ?? 'all';
-            return filterEventData(parsed, resolveData);
+            return { event: filterEventData(parsed, resolveData), run, step, hook };
         },
         async list(params) {
             const limit = params?.pagination?.limit ?? 100;
@@ -338,30 +778,6 @@ export function createHooksStorage(drizzle) {
             const resolveData = params?.resolveData ?? 'all';
             return filterHookData(parsed, resolveData);
         },
-        async create(runId, data, params) {
-            const [value] = await drizzle
-                .insert(hooks)
-                .values({
-                runId,
-                hookId: data.hookId,
-                token: data.token,
-                metadata: data.metadata,
-                ownerId: '', // TODO: get from context
-                projectId: '', // TODO: get from context
-                environment: '', // TODO: get from context
-            })
-                .onConflictDoNothing()
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Hook ${data.hookId} already exists`, {
-                    status: 409,
-                });
-            }
-            value.metadata ||= value.metadataJson;
-            const parsed = HookSchema.parse(compact(value));
-            const resolveData = params?.resolveData ?? 'all';
-            return filterHookData(parsed, resolveData);
-        },
         async getByToken(token, params) {
             const [value] = await getByToken.execute({ token });
             if (!value) {
@@ -396,46 +812,12 @@ export function createHooksStorage(drizzle) {
                 hasMore,
             };
         },
-        async dispose(hookId, params) {
-            const [value] = await drizzle
-                .delete(hooks)
-                .where(eq(hooks.hookId, hookId))
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Hook not found: ${hookId}`, {
-                    status: 404,
-                });
-            }
-            const parsed = HookSchema.parse(compact(value));
-            const resolveData = params?.resolveData ?? 'all';
-            return filterHookData(parsed, resolveData);
-        },
     };
 }
 export function createStepsStorage(drizzle) {
     const { steps } = Schema;
     return {
-        async create(runId, data) {
-            const [value] = await drizzle
-                .insert(steps)
-                .values({
-                runId,
-                stepId: data.stepId,
-                stepName: data.stepName,
-                input: data.input,
-                status: 'pending',
-                attempt: 0,
-            })
-                .onConflictDoNothing()
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Step ${data.stepId} already exists`, {
-                    status: 409,
-                });
-            }
-            return deserializeStepError(compact(value));
-        },
-        async get(runId, stepId, params) {
+        get: (async (runId, stepId, params) => {
             // If runId is not provided, query only by stepId
             const whereClause = runId
                 ? and(eq(steps.stepId, stepId), eq(steps.runId, runId))
@@ -451,50 +833,14 @@ export function createStepsStorage(drizzle) {
                 });
             }
             value.output ||= value.outputJson;
+            value.input ||= value.inputJson;
+            value.error ||= parseErrorJson(value.errorJson);
             const deserialized = deserializeStepError(compact(value));
             const parsed = StepSchema.parse(deserialized);
             const resolveData = params?.resolveData ?? 'all';
             return filterStepData(parsed, resolveData);
-        },
-        async update(runId, stepId, data) {
-            // Fetch current step to check if startedAt is already set
-            const [currentStep] = await drizzle
-                .select()
-                .from(steps)
-                .where(and(eq(steps.stepId, stepId), eq(steps.runId, runId)))
-                .limit(1);
-            if (!currentStep) {
-                throw new WorkflowAPIError(`Step not found: ${stepId}`, {
-                    status: 404,
-                });
-            }
-            // Serialize the error field if present
-            const serialized = serializeStepError(data);
-            const updates = {
-                ...serialized,
-                output: data.output,
-            };
-            const now = new Date();
-            // Only set startedAt the first time the step transitions to 'running'
-            if (data.status === 'running' && !currentStep.startedAt) {
-                updates.startedAt = now;
-            }
-            if (data.status === 'completed' || data.status === 'failed') {
-                updates.completedAt = now;
-            }
-            const [value] = await drizzle
-                .update(steps)
-                .set(updates)
-                .where(and(eq(steps.stepId, stepId), eq(steps.runId, runId)))
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Step not found: ${stepId}`, {
-                    status: 404,
-                });
-            }
-            return deserializeStepError(compact(value));
-        },
-        async list(params) {
+        }),
+        list: (async (params) => {
             const limit = params?.pagination?.limit ?? 20;
             const fromCursor = params?.pagination?.cursor;
             const all = await drizzle
@@ -508,6 +854,9 @@ export function createStepsStorage(drizzle) {
             const resolveData = params?.resolveData ?? 'all';
             return {
                 data: values.map((v) => {
+                    v.output ||= v.outputJson;
+                    v.input ||= v.inputJson;
+                    v.error ||= parseErrorJson(v.errorJson);
                     const deserialized = deserializeStepError(compact(v));
                     const parsed = StepSchema.parse(deserialized);
                     return filterStepData(parsed, resolveData);
@@ -515,20 +864,20 @@ export function createStepsStorage(drizzle) {
                 hasMore,
                 cursor: values.at(-1)?.stepId ?? null,
             };
-        },
+        }),
     };
 }
 function filterStepData(step, resolveData) {
     if (resolveData === 'none') {
         const { input: _, output: __, ...rest } = step;
-        return { input: [], output: undefined, ...rest };
+        return { input: undefined, output: undefined, ...rest };
     }
     return step;
 }
 function filterRunData(run, resolveData) {
     if (resolveData === 'none') {
         const { input: _, output: __, ...rest } = run;
-        return { input: [], output: undefined, ...rest };
+        return { input: undefined, output: undefined, ...rest };
     }
     return run;
 }