@workflow/world-postgres 4.1.0-beta.4 → 4.1.0-beta.41

package/dist/storage.js

@@ -1,10 +1,67 @@
-import { WorkflowAPIError } from '@workflow/errors';
-import { and, desc, eq, gt, lt, sql } from 'drizzle-orm';
+import { HookNotFoundError, RunNotSupportedError, WorkflowAPIError, } from '@workflow/errors';
+import { EventSchema, HookSchema, isLegacySpecVersion, requiresNewerWorld, SPEC_VERSION_CURRENT, StepSchema, validateUlidTimestamp, WorkflowRunSchema, } from '@workflow/world';
+import { and, asc, desc, eq, gt, lt, notInArray, sql } from 'drizzle-orm';
 import { monotonicFactory } from 'ulid';
 import { Schema } from './drizzle/index.js';
 import { compact } from './util.js';
+/**
+ * Parse legacy errorJson (text column with JSON-stringified StructuredError).
+ * Used for backwards compatibility when reading from deprecated error column.
+ */
+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 };
+    }
+}
+/**
+ * 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 { errorStack, errorCode, ...rest } = run;
+    // If no legacy fields, return as-is (error is already a StructuredError or undefined)
+    if (!errorStack && !errorCode) {
+        return rest;
+    }
+    // Very old legacy: separate errorStack/errorCode fields
+    const existingError = rest.error;
+    return {
+        ...rest,
+        error: {
+            message: existingError?.message || '',
+            stack: existingError?.stack || errorStack,
+            code: existingError?.code || errorCode,
+        },
+    };
+}
+/**
+ * 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 { startedAt, ...rest } = step;
+    return {
+        ...rest,
+        startedAt,
+    };
+}
 export function createRunsStorage(drizzle) {
-    const ulid = monotonicFactory();
     const { runs } = Schema;
     const get = drizzle
         .select()
@@ -13,51 +70,21 @@ export function createRunsStorage(drizzle) {
         .limit(1)
         .prepare('workflow_runs_get');
     return {
-        async get(id) {
+        get: (async (id, params) => {
             const [value] = await get.execute({ id });
             if (!value) {
                 throw new WorkflowAPIError(`Run not found: ${id}`, { status: 404 });
             }
-            return compact(value);
-        },
-        async cancel(id) {
-            // 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 });
-            }
-            return compact(value);
-        },
-        async pause(id) {
-            // TODO: we might want to guard this for only specific statuses
-            const [value] = await drizzle
-                .update(Schema.runs)
-                .set({ status: 'paused' })
-                .where(eq(runs.runId, id))
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Run not found: ${id}`, { status: 404 });
-            }
-            return compact(value);
-        },
-        async resume(id) {
-            const [value] = await drizzle
-                .update(Schema.runs)
-                .set({ status: 'running' })
-                .where(and(eq(runs.runId, id), eq(runs.status, 'paused')))
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Paused run not found: ${id}`, {
-                    status: 404,
-                });
-            }
-            return compact(value);
-        },
-        async list(params) {
+            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);
+        }),
+        list: (async (params) => {
             const limit = params?.pagination?.limit ?? 20;
             const fromCursor = params?.pagination?.cursor;
             const all = await drizzle
@@ -68,85 +95,711 @@ export function createRunsStorage(drizzle) {
                 .limit(limit + 1);
             const values = all.slice(0, limit);
             const hasMore = all.length > limit;
+            const resolveData = params?.resolveData ?? 'all';
             return {
-                data: values.map(compact),
+                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);
+                }),
                 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 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 });
-            }
-            const updates = {
-                ...data,
-                output: data.output,
-            };
-            // Only set startedAt the first time transitioning to 'running'
-            if (data.status === 'running' && !currentRun.startedAt) {
-                updates.startedAt = new Date();
-            }
-            if (data.status === 'completed' ||
-                data.status === 'failed' ||
-                data.status === 'cancelled') {
-                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 });
-            }
-            return 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 and waits for this run
+            await Promise.all([
+                drizzle.delete(Schema.hooks).where(eq(Schema.hooks.runId, runId)),
+                drizzle.delete(Schema.waits).where(eq(Schema.waits.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');
+    const getWaitForValidation = drizzle
+        .select({
+        status: Schema.waits.status,
+    })
+        .from(Schema.waits)
+        .where(eq(Schema.waits.waitId, sql.placeholder('waitId')))
+        .limit(1)
+        .prepare('events_get_wait_for_validation');
     return {
-        async create(runId, data) {
+        async create(runId, data, params) {
             const eventId = `wevt_${ulid()}`;
+            // For run_created events, use client-provided runId or generate one server-side
+            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;
+            }
+            // Validate client-provided runId timestamp is within acceptable threshold
+            if (data.eventType === 'run_created' && runId && runId !== '') {
+                const validationError = validateUlidTimestamp(effectiveRunId, 'wrun_');
+                if (validationError) {
+                    throw new WorkflowAPIError(validationError, { status: 400 });
+                }
+            }
+            // 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;
+            let wait;
+            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' ||
+                    data.eventType === 'wait_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 and waits for this run to allow token reuse
+                await Promise.all([
+                    drizzle
+                        .delete(Schema.hooks)
+                        .where(eq(Schema.hooks.runId, effectiveRunId)),
+                    drizzle
+                        .delete(Schema.waits)
+                        .where(eq(Schema.waits.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 and waits for this run to allow token reuse
+                await Promise.all([
+                    drizzle
+                        .delete(Schema.hooks)
+                        .where(eq(Schema.hooks.runId, effectiveRunId)),
+                    drizzle
+                        .delete(Schema.waits)
+                        .where(eq(Schema.waits.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 and waits for this run to allow token reuse
+                await Promise.all([
+                    drizzle
+                        .delete(Schema.hooks)
+                        .where(eq(Schema.hooks.runId, effectiveRunId)),
+                    drizzle
+                        .delete(Schema.waits)
+                        .where(eq(Schema.waits.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,
+                    isWebhook: eventData.isWebhook,
+                })
+                    .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));
+            }
+            // Handle wait_created event: create wait entity
+            if (data.eventType === 'wait_created') {
+                const eventData = data.eventData;
+                const waitId = `${effectiveRunId}-${data.correlationId}`;
+                const [waitValue] = await drizzle
+                    .insert(Schema.waits)
+                    .values({
+                    waitId,
+                    runId: effectiveRunId,
+                    status: 'waiting',
+                    resumeAt: eventData.resumeAt,
+                    specVersion: effectiveSpecVersion,
+                })
+                    .onConflictDoNothing()
+                    .returning();
+                if (waitValue) {
+                    wait = {
+                        waitId: waitValue.waitId,
+                        runId: waitValue.runId,
+                        status: waitValue.status,
+                        resumeAt: waitValue.resumeAt ?? undefined,
+                        completedAt: waitValue.completedAt ?? undefined,
+                        createdAt: waitValue.createdAt,
+                        updatedAt: waitValue.updatedAt,
+                        specVersion: waitValue.specVersion ?? undefined,
+                    };
+                }
+                else {
+                    throw new WorkflowAPIError(`Wait "${data.correlationId}" already exists`, { status: 409 });
+                }
+            }
+            // Handle wait_completed event: transition wait to 'completed'
+            // Uses conditional UPDATE to reject duplicate completions (same pattern as step_completed)
+            if (data.eventType === 'wait_completed') {
+                const waitId = `${effectiveRunId}-${data.correlationId}`;
+                const [waitValue] = await drizzle
+                    .update(Schema.waits)
+                    .set({
+                    status: 'completed',
+                    completedAt: now,
+                })
+                    .where(and(eq(Schema.waits.waitId, waitId), eq(Schema.waits.status, 'waiting')))
+                    .returning();
+                if (waitValue) {
+                    wait = {
+                        waitId: waitValue.waitId,
+                        runId: waitValue.runId,
+                        status: waitValue.status,
+                        resumeAt: waitValue.resumeAt ?? undefined,
+                        completedAt: waitValue.completedAt ?? undefined,
+                        createdAt: waitValue.createdAt,
+                        updatedAt: waitValue.updatedAt,
+                        specVersion: waitValue.specVersion ?? undefined,
+                    };
+                }
+                else {
+                    // Wait not updated - check if it exists and why
+                    const [existing] = await getWaitForValidation.execute({
+                        waitId,
+                    });
+                    if (!existing) {
+                        throw new WorkflowAPIError(`Wait "${data.correlationId}" not found`, { status: 404 });
+                    }
+                    if (existing.status === 'completed') {
+                        throw new WorkflowAPIError(`Wait "${data.correlationId}" already completed`, { status: 409 });
+                    }
+                }
+            }
             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) {
@@ -154,7 +807,16 @@ export function createEventsStorage(drizzle) {
                     status: 409,
                 });
             }
-            return { ...data, ...value, runId, eventId };
+            const result = { ...data, ...value, runId: effectiveRunId, eventId };
+            const parsed = EventSchema.parse(result);
+            const resolveData = params?.resolveData ?? 'all';
+            return {
+                event: filterEventData(parsed, resolveData),
+                run,
+                step,
+                hook,
+                wait,
+            };
         },
         async list(params) {
             const limit = params?.pagination?.limit ?? 100;
@@ -169,8 +831,13 @@ export function createEventsStorage(drizzle) {
                 .orderBy(order.by)
                 .limit(limit + 1);
             const values = all.slice(0, limit);
+            const resolveData = params?.resolveData ?? 'all';
             return {
-                data: values.map(compact),
+                data: values.map((v) => {
+                    v.eventData ||= v.eventDataJson;
+                    const parsed = EventSchema.parse(compact(v));
+                    return filterEventData(parsed, resolveData);
+                }),
                 cursor: values.at(-1)?.eventId ?? null,
                 hasMore: all.length > limit,
             };
@@ -188,8 +855,13 @@ export function createEventsStorage(drizzle) {
                 .orderBy(order.by)
                 .limit(limit + 1);
             const values = all.slice(0, limit);
+            const resolveData = params?.resolveData ?? 'all';
             return {
-                data: values.map(compact),
+                data: values.map((v) => {
+                    v.eventData ||= v.eventDataJson;
+                    const parsed = EventSchema.parse(compact(v));
+                    return filterEventData(parsed, resolveData);
+                }),
                 cursor: values.at(-1)?.eventId ?? null,
                 hasMore: all.length > limit,
             };
@@ -205,149 +877,83 @@ export function createHooksStorage(drizzle) {
         .limit(1)
         .prepare('workflow_hooks_get_by_token');
     return {
-        async get(hookId) {
+        async get(hookId, params) {
             const [value] = await drizzle
                 .select()
                 .from(hooks)
                 .where(eq(hooks.hookId, hookId))
                 .limit(1);
-            return compact(value);
-        },
-        async create(runId, data) {
-            const [value] = await drizzle
-                .insert(hooks)
-                .values({
-                runId,
-                hookId: data.hookId,
-                token: data.token,
-                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,
-                });
-            }
-            return compact(value);
+            value.metadata ||= value.metadataJson;
+            const parsed = HookSchema.parse(compact(value));
+            parsed.isWebhook ??= true;
+            const resolveData = params?.resolveData ?? 'all';
+            return filterHookData(parsed, resolveData);
         },
-        async getByToken(token) {
+        async getByToken(token, params) {
             const [value] = await getByToken.execute({ token });
             if (!value) {
-                throw new WorkflowAPIError(`Hook not found for token: ${token}`, {
-                    status: 404,
-                });
+                throw new HookNotFoundError(token);
             }
-            return compact(value);
+            value.metadata ||= value.metadataJson;
+            const parsed = HookSchema.parse(compact(value));
+            parsed.isWebhook ??= true;
+            const resolveData = params?.resolveData ?? 'all';
+            return filterHookData(parsed, resolveData);
         },
         async list(params) {
             const limit = params?.pagination?.limit ?? 100;
             const fromCursor = params?.pagination?.cursor;
+            const sortOrder = params?.pagination?.sortOrder ?? 'asc';
+            const orderFn = sortOrder === 'asc' ? asc : desc;
+            const cursorFn = sortOrder === 'asc' ? gt : lt;
             const all = await drizzle
                 .select()
                 .from(hooks)
-                .where(and(map(params.runId, (id) => eq(hooks.runId, id)), map(fromCursor, (c) => lt(hooks.hookId, c))))
-                .orderBy(desc(hooks.hookId))
+                .where(and(map(params.runId, (id) => eq(hooks.runId, id)), map(fromCursor, (c) => cursorFn(hooks.hookId, c))))
+                .orderBy(orderFn(hooks.hookId))
                 .limit(limit + 1);
             const values = all.slice(0, limit);
             const hasMore = all.length > limit;
+            const resolveData = params?.resolveData ?? 'all';
             return {
-                data: values.map(compact),
+                data: values.map((v) => {
+                    v.metadata ||= v.metadataJson;
+                    const parsed = HookSchema.parse(compact(v));
+                    return filterHookData(parsed, resolveData);
+                }),
                 cursor: values.at(-1)?.hookId ?? null,
                 hasMore,
             };
         },
-        async dispose(hookId) {
-            const [value] = await drizzle
-                .delete(hooks)
-                .where(eq(hooks.hookId, hookId))
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Hook not found: ${hookId}`, {
-                    status: 404,
-                });
-            }
-            return compact(value);
-        },
     };
 }
 export function createStepsStorage(drizzle) {
     const { steps } = Schema;
-    const get = drizzle
-        .select()
-        .from(steps)
-        .where(and(eq(steps.stepId, sql.placeholder('stepId')), eq(steps.runId, sql.placeholder('runId'))))
-        .limit(1)
-        .prepare('workflow_steps_get');
     return {
-        async create(runId, data) {
+        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))
+                : eq(steps.stepId, stepId);
             const [value] = await drizzle
-                .insert(steps)
-                .values({
-                runId,
-                stepId: data.stepId,
-                stepName: data.stepName,
-                input: data.input,
-                status: 'pending',
-                attempt: 1,
-            })
-                .onConflictDoNothing()
-                .returning();
-            if (!value) {
-                throw new WorkflowAPIError(`Step ${data.stepId} already exists`, {
-                    status: 409,
-                });
-            }
-            return compact(value);
-        },
-        async get(runId, stepId) {
-            const [value] = await get.execute({ stepId, runId });
-            if (!value) {
-                throw new WorkflowAPIError(`Step not found: ${stepId}`, {
-                    status: 404,
-                });
-            }
-            return compact(value);
-        },
-        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)))
+                .where(whereClause)
                 .limit(1);
-            if (!currentStep) {
-                throw new WorkflowAPIError(`Step not found: ${stepId}`, {
-                    status: 404,
-                });
-            }
-            const updates = {
-                ...data,
-                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 compact(value);
-        },
-        async list(params) {
+            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);
+        }),
+        list: (async (params) => {
             const limit = params?.pagination?.limit ?? 20;
             const fromCursor = params?.pagination?.cursor;
             const all = await drizzle
@@ -358,12 +964,48 @@ export function createStepsStorage(drizzle) {
                 .limit(limit + 1);
             const values = all.slice(0, limit);
             const hasMore = all.length > limit;
+            const resolveData = params?.resolveData ?? 'all';
             return {
-                data: values.map(compact),
+                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);
+                }),
                 hasMore,
                 cursor: values.at(-1)?.stepId ?? null,
             };
-        },
+        }),
     };
 }
+function filterStepData(step, resolveData) {
+    if (resolveData === 'none') {
+        const { input: _, output: __, ...rest } = step;
+        return { input: undefined, output: undefined, ...rest };
+    }
+    return step;
+}
+function filterRunData(run, resolveData) {
+    if (resolveData === 'none') {
+        const { input: _, output: __, ...rest } = run;
+        return { input: undefined, output: undefined, ...rest };
+    }
+    return run;
+}
+function filterHookData(hook, resolveData) {
+    if (resolveData === 'none' && 'metadata' in hook) {
+        const { metadata: _, ...rest } = hook;
+        return { metadata: undefined, ...rest };
+    }
+    return hook;
+}
+function filterEventData(event, resolveData) {
+    if (resolveData === 'none' && 'eventData' in event) {
+        const { eventData: _, ...rest } = event;
+        return rest;
+    }
+    return event;
+}
 //# sourceMappingURL=storage.js.map