@workflow/world-postgres 4.1.0-beta.45 → 4.1.0-beta.47

package/dist/storage.js

@@ -1,5 +1,5 @@
-import { HookNotFoundError, RunNotSupportedError, WorkflowAPIError, } from '@workflow/errors';
-import { EventSchema, HookSchema, isLegacySpecVersion, requiresNewerWorld, SPEC_VERSION_CURRENT, StepSchema, validateUlidTimestamp, WorkflowRunSchema, } from '@workflow/world';
+import { EntityConflictError, HookNotFoundError, RunExpiredError, RunNotSupportedError, TooEarlyError, WorkflowWorldError, WorkflowRunNotFoundError, } from '@workflow/errors';
+import { EventSchema, HookSchema, isLegacySpecVersion, requiresNewerWorld, SPEC_VERSION_CURRENT, StepSchema, stripEventDataRefs, 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';
@@ -73,7 +73,7 @@ export function createRunsStorage(drizzle) {
         get: (async (id, params) => {
             const [value] = await get.execute({ id });
             if (!value) {
-                throw new WorkflowAPIError(`Run not found: ${id}`, { status: 404 });
+                throw new WorkflowRunNotFoundError(id);
             }
             value.output ||= value.outputJson;
             value.input ||= value.inputJson;
@@ -179,7 +179,7 @@ async function handleLegacyEventPostgres(drizzle, runId, eventId, data, currentR
                 runId,
                 eventId,
             });
-            return { event: filterEventData(event, resolveData) };
+            return { event: stripEventDataRefs(event, resolveData) };
         }
         default:
             throw new Error(`Event type '${data.eventType}' not supported for legacy runs ` +
@@ -242,7 +242,7 @@ export function createEventsStorage(drizzle) {
             if (data.eventType === 'run_created' && runId && runId !== '') {
                 const validationError = validateUlidTimestamp(effectiveRunId, 'wrun_');
                 if (validationError) {
-                    throw new WorkflowAPIError(validationError, { status: 400 });
+                    throw new WorkflowWorldError(validationError);
                 }
             }
             // specVersion is always sent by the runtime, but we provide a fallback for safety
@@ -256,7 +256,11 @@ export function createEventsStorage(drizzle) {
             // 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);
+            const isStepTerminal = (status) => ['completed', 'failed', 'cancelled'].includes(status);
+            // Terminal step statuses for use in SQL WHERE clauses (atomic guard).
+            // Must match the Vercel world's conditional expressions:
+            //   ne(status, 'completed') AND ne(status, 'failed') AND ne(status, 'cancelled')
+            const terminalStepStatuses = ['completed', 'failed', 'cancelled'];
             // ============================================================
             // VALIDATION: Terminal state and event ordering checks
             // ============================================================
@@ -321,20 +325,20 @@ export function createEventsStorage(drizzle) {
                     const parsed = EventSchema.parse(result);
                     const resolveData = params?.resolveData ?? 'all';
                     return {
-                        event: filterEventData(parsed, resolveData),
+                        event: stripEventDataRefs(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 });
+                    throw new EntityConflictError(`Cannot transition run from terminal state "${currentRun.status}"`);
                 }
                 // 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 });
+                    throw new EntityConflictError(`Cannot create new entities on run in terminal state "${currentRun.status}"`);
                 }
             }
             // Step-related event validation (ordering and terminal state)
@@ -352,18 +356,16 @@ export function createEventsStorage(drizzle) {
                 validatedStep = existingStep ?? null;
                 // Event ordering: step must exist before these events
                 if (!validatedStep) {
-                    throw new WorkflowAPIError(`Step "${data.correlationId}" not found`, {
-                        status: 404,
-                    });
+                    throw new WorkflowWorldError(`Step "${data.correlationId}" not found`);
                 }
                 // Step terminal state validation
                 if (isStepTerminal(validatedStep.status)) {
-                    throw new WorkflowAPIError(`Cannot modify step in terminal state "${validatedStep.status}"`, { status: 409 });
+                    throw new EntityConflictError(`Cannot modify step in terminal state "${validatedStep.status}"`);
                 }
                 // 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 });
+                        throw new RunExpiredError(`Cannot modify non-running step on run in terminal state "${currentRun.status}"`);
                     }
                 }
             }
@@ -377,9 +379,7 @@ export function createEventsStorage(drizzle) {
                     .where(eq(Schema.hooks.hookId, data.correlationId))
                     .limit(1);
                 if (!existingHook) {
-                    throw new WorkflowAPIError(`Hook "${data.correlationId}" not found`, {
-                        status: 404,
-                    });
+                    throw new HookNotFoundError(data.correlationId);
                 }
             }
             // ============================================================
@@ -421,7 +421,12 @@ export function createEventsStorage(drizzle) {
                     run = deserializeRunError(compact(runValue));
                 }
             }
+            // Terminal run statuses for use in SQL WHERE clauses (atomic guard).
+            // Must match the Vercel world's conditional expressions:
+            //   ne(status, 'completed') AND ne(status, 'failed') AND ne(status, 'cancelled')
+            const terminalRunStatuses = ['completed', 'failed', 'cancelled'];
             // Handle run_completed event: update run status and cleanup hooks
+            // Uses conditional UPDATE to prevent completing an already-terminal run.
             if (data.eventType === 'run_completed') {
                 const eventData = data.eventData;
                 const [runValue] = await drizzle
@@ -432,11 +437,22 @@ export function createEventsStorage(drizzle) {
                     completedAt: now,
                     updatedAt: now,
                 })
-                    .where(eq(Schema.runs.runId, effectiveRunId))
+                    .where(and(eq(Schema.runs.runId, effectiveRunId), notInArray(Schema.runs.status, terminalRunStatuses)))
                     .returning();
                 if (runValue) {
                     run = deserializeRunError(compact(runValue));
                 }
+                else {
+                    const [existing] = await getRunForValidation.execute({
+                        runId: effectiveRunId,
+                    });
+                    if (!existing) {
+                        throw new WorkflowRunNotFoundError(effectiveRunId);
+                    }
+                    if (isRunTerminal(existing.status)) {
+                        throw new EntityConflictError(`Cannot transition run from terminal state "${existing.status}"`);
+                    }
+                }
                 // Delete all hooks and waits for this run to allow token reuse
                 await Promise.all([
                     drizzle
@@ -448,6 +464,7 @@ export function createEventsStorage(drizzle) {
                 ]);
             }
             // Handle run_failed event: update run status and cleanup hooks
+            // Uses conditional UPDATE to prevent failing an already-terminal run.
             if (data.eventType === 'run_failed') {
                 const eventData = data.eventData;
                 const errorMessage = typeof eventData.error === 'string'
@@ -465,11 +482,22 @@ export function createEventsStorage(drizzle) {
                     completedAt: now,
                     updatedAt: now,
                 })
-                    .where(eq(Schema.runs.runId, effectiveRunId))
+                    .where(and(eq(Schema.runs.runId, effectiveRunId), notInArray(Schema.runs.status, terminalRunStatuses)))
                     .returning();
                 if (runValue) {
                     run = deserializeRunError(compact(runValue));
                 }
+                else {
+                    const [existing] = await getRunForValidation.execute({
+                        runId: effectiveRunId,
+                    });
+                    if (!existing) {
+                        throw new WorkflowRunNotFoundError(effectiveRunId);
+                    }
+                    if (isRunTerminal(existing.status)) {
+                        throw new EntityConflictError(`Cannot transition run from terminal state "${existing.status}"`);
+                    }
+                }
                 // Delete all hooks and waits for this run to allow token reuse
                 await Promise.all([
                     drizzle
@@ -481,6 +509,9 @@ export function createEventsStorage(drizzle) {
                 ]);
             }
             // Handle run_cancelled event: update run status and cleanup hooks
+            // Uses conditional UPDATE to prevent cancelling an already-terminal run.
+            // Note: idempotent run_cancelled on already-cancelled runs is handled
+            // earlier in the pre-validation block (creates event and returns early).
             if (data.eventType === 'run_cancelled') {
                 const [runValue] = await drizzle
                     .update(Schema.runs)
@@ -489,11 +520,22 @@ export function createEventsStorage(drizzle) {
                     completedAt: now,
                     updatedAt: now,
                 })
-                    .where(eq(Schema.runs.runId, effectiveRunId))
+                    .where(and(eq(Schema.runs.runId, effectiveRunId), notInArray(Schema.runs.status, terminalRunStatuses)))
                     .returning();
                 if (runValue) {
                     run = deserializeRunError(compact(runValue));
                 }
+                else {
+                    const [existing] = await getRunForValidation.execute({
+                        runId: effectiveRunId,
+                    });
+                    if (!existing) {
+                        throw new WorkflowRunNotFoundError(effectiveRunId);
+                    }
+                    if (isRunTerminal(existing.status)) {
+                        throw new EntityConflictError(`Cannot transition run from terminal state "${existing.status}"`);
+                    }
+                }
                 // Delete all hooks and waits for this run to allow token reuse
                 await Promise.all([
                     drizzle
@@ -527,40 +569,53 @@ export function createEventsStorage(drizzle) {
             }
             // 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)
+            // Uses conditional UPDATE to prevent re-starting a step that has already
+            // reached a terminal state (completed/failed). Without this guard a
+            // concurrent step_started could revert a completed step back to 'running',
+            // allowing a duplicate execution that corrupts the event log.
             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;
+                    throw new TooEarlyError(`Cannot start step "${data.correlationId}": retryAfter timestamp has not been reached yet`, {
+                        retryAfter: Math.ceil((validatedStep.retryAfter.getTime() - Date.now()) / 1000),
+                    });
                 }
-                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 } : {}),
+                    // Only set startedAt on first start — use COALESCE so concurrent
+                    // step_started calls can't clobber the original timestamp.
+                    startedAt: sql `COALESCE(${Schema.steps.startedAt}, ${now.toISOString()})`,
+                    // Always clear retryAfter now that the step has started
+                    retryAfter: null,
                 })
-                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId)))
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId), 
+                // Only update if not already in terminal state (prevents TOCTOU race)
+                notInArray(Schema.steps.status, terminalStepStatuses)))
                     .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 WorkflowWorldError(`Step "${data.correlationId}" not found`);
+                    }
+                    if (isStepTerminal(existing.status)) {
+                        throw new EntityConflictError(`Cannot modify step in terminal state "${existing.status}"`);
+                    }
+                }
             }
             // Handle step_completed event: update step status
-            // Uses conditional UPDATE to skip validation query (performance optimization)
+            // Uses conditional UPDATE to prevent completing an already-terminal step.
             if (data.eventType === 'step_completed') {
                 const eventData = data.eventData;
                 const [stepValue] = await drizzle
@@ -570,9 +625,7 @@ export function createEventsStorage(drizzle) {
                     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'])))
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId), notInArray(Schema.steps.status, terminalStepStatuses)))
                     .returning();
                 if (stepValue) {
                     step = deserializeStepError(compact(stepValue));
@@ -584,15 +637,15 @@ export function createEventsStorage(drizzle) {
                         stepId: data.correlationId,
                     });
                     if (!existing) {
-                        throw new WorkflowAPIError(`Step "${data.correlationId}" not found`, { status: 404 });
+                        throw new WorkflowWorldError(`Step "${data.correlationId}" not found`);
                     }
-                    if (['completed', 'failed'].includes(existing.status)) {
-                        throw new WorkflowAPIError(`Cannot modify step in terminal state "${existing.status}"`, { status: 409 });
+                    if (isStepTerminal(existing.status)) {
+                        throw new EntityConflictError(`Cannot modify step in terminal state "${existing.status}"`);
                     }
                 }
             }
             // Handle step_failed event: terminal state with error
-            // Uses conditional UPDATE to skip validation query (performance optimization)
+            // Uses conditional UPDATE to prevent failing an already-terminal step.
             if (data.eventType === 'step_failed') {
                 const eventData = data.eventData;
                 const errorMessage = typeof eventData.error === 'string'
@@ -608,9 +661,7 @@ export function createEventsStorage(drizzle) {
                     },
                     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'])))
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId), notInArray(Schema.steps.status, terminalStepStatuses)))
                     .returning();
                 if (stepValue) {
                     step = deserializeStepError(compact(stepValue));
@@ -622,14 +673,15 @@ export function createEventsStorage(drizzle) {
                         stepId: data.correlationId,
                     });
                     if (!existing) {
-                        throw new WorkflowAPIError(`Step "${data.correlationId}" not found`, { status: 404 });
+                        throw new WorkflowWorldError(`Step "${data.correlationId}" not found`);
                     }
-                    if (['completed', 'failed'].includes(existing.status)) {
-                        throw new WorkflowAPIError(`Cannot modify step in terminal state "${existing.status}"`, { status: 409 });
+                    if (isStepTerminal(existing.status)) {
+                        throw new EntityConflictError(`Cannot modify step in terminal state "${existing.status}"`);
                     }
                 }
             }
             // Handle step_retrying event: sets status back to 'pending', records error
+            // Uses conditional UPDATE to prevent retrying an already-terminal step.
             if (data.eventType === 'step_retrying') {
                 const eventData = data.eventData;
                 const errorMessage = typeof eventData.error === 'string'
@@ -645,11 +697,24 @@ export function createEventsStorage(drizzle) {
                     },
                     retryAfter: eventData.retryAfter,
                 })
-                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId)))
+                    .where(and(eq(Schema.steps.runId, effectiveRunId), eq(Schema.steps.stepId, data.correlationId), notInArray(Schema.steps.status, terminalStepStatuses)))
                     .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 WorkflowWorldError(`Step "${data.correlationId}" not found`);
+                    }
+                    if (isStepTerminal(existing.status)) {
+                        throw new EntityConflictError(`Cannot modify step in terminal state "${existing.status}"`);
+                    }
+                }
             }
             // Handle hook_created event: create hook entity
             // Uses prepared statement for token uniqueness check (performance optimization)
@@ -677,7 +742,7 @@ export function createEventsStorage(drizzle) {
                     })
                         .returning({ createdAt: events.createdAt });
                     if (!conflictValue) {
-                        throw new WorkflowAPIError(`Event ${eventId} could not be created`, { status: 409 });
+                        throw new EntityConflictError(`Event ${eventId} could not be created`);
                     }
                     const conflictResult = {
                         eventType: 'hook_conflict',
@@ -690,7 +755,7 @@ export function createEventsStorage(drizzle) {
                     const parsedConflict = EventSchema.parse(conflictResult);
                     const resolveData = params?.resolveData ?? 'all';
                     return {
-                        event: filterEventData(parsedConflict, resolveData),
+                        event: stripEventDataRefs(parsedConflict, resolveData),
                         run,
                         step,
                         hook: undefined,
@@ -751,7 +816,7 @@ export function createEventsStorage(drizzle) {
                     };
                 }
                 else {
-                    throw new WorkflowAPIError(`Wait "${data.correlationId}" already exists`, { status: 409 });
+                    throw new EntityConflictError(`Wait "${data.correlationId}" already exists`);
                 }
             }
             // Handle wait_completed event: transition wait to 'completed'
@@ -784,10 +849,10 @@ export function createEventsStorage(drizzle) {
                         waitId,
                     });
                     if (!existing) {
-                        throw new WorkflowAPIError(`Wait "${data.correlationId}" not found`, { status: 404 });
+                        throw new WorkflowWorldError(`Wait "${data.correlationId}" not found`);
                     }
                     if (existing.status === 'completed') {
-                        throw new WorkflowAPIError(`Wait "${data.correlationId}" already completed`, { status: 409 });
+                        throw new EntityConflictError(`Wait "${data.correlationId}" already completed`);
                     }
                 }
             }
@@ -803,15 +868,13 @@ export function createEventsStorage(drizzle) {
             })
                 .returning({ createdAt: events.createdAt });
             if (!value) {
-                throw new WorkflowAPIError(`Event ${eventId} could not be created`, {
-                    status: 409,
-                });
+                throw new EntityConflictError(`Event ${eventId} could not be created`);
             }
             const result = { ...data, ...value, runId: effectiveRunId, eventId };
             const parsed = EventSchema.parse(result);
             const resolveData = params?.resolveData ?? 'all';
             return {
-                event: filterEventData(parsed, resolveData),
+                event: stripEventDataRefs(parsed, resolveData),
                 run,
                 step,
                 hook,
@@ -825,14 +888,12 @@ export function createEventsStorage(drizzle) {
                 .where(and(eq(events.runId, runId), eq(events.eventId, eventId)))
                 .limit(1);
             if (!value) {
-                throw new WorkflowAPIError(`Event not found: ${eventId}`, {
-                    status: 404,
-                });
+                throw new WorkflowWorldError(`Event not found: ${eventId}`);
             }
             value.eventData ||= value.eventDataJson;
             const parsed = EventSchema.parse(compact(value));
             const resolveData = params?.resolveData ?? 'all';
-            return filterEventData(parsed, resolveData);
+            return stripEventDataRefs(parsed, resolveData);
         },
         async list(params) {
             const limit = params?.pagination?.limit ?? 100;
@@ -852,7 +913,7 @@ export function createEventsStorage(drizzle) {
                 data: values.map((v) => {
                     v.eventData ||= v.eventDataJson;
                     const parsed = EventSchema.parse(compact(v));
-                    return filterEventData(parsed, resolveData);
+                    return stripEventDataRefs(parsed, resolveData);
                 }),
                 cursor: values.at(-1)?.eventId ?? null,
                 hasMore: all.length > limit,
@@ -876,7 +937,7 @@ export function createEventsStorage(drizzle) {
                 data: values.map((v) => {
                     v.eventData ||= v.eventDataJson;
                     const parsed = EventSchema.parse(compact(v));
-                    return filterEventData(parsed, resolveData);
+                    return stripEventDataRefs(parsed, resolveData);
                 }),
                 cursor: values.at(-1)?.eventId ?? null,
                 hasMore: all.length > limit,
@@ -957,9 +1018,7 @@ export function createStepsStorage(drizzle) {
                 .where(whereClause)
                 .limit(1);
             if (!value) {
-                throw new WorkflowAPIError(`Step not found: ${stepId}`, {
-                    status: 404,
-                });
+                throw new WorkflowWorldError(`Step not found: ${stepId}`);
             }
             value.output ||= value.outputJson;
             value.input ||= value.inputJson;
@@ -1017,11 +1076,4 @@ function filterHookData(hook, resolveData) {
     }
     return hook;
 }
-function filterEventData(event, resolveData) {
-    if (resolveData === 'none' && 'eventData' in event) {
-        const { eventData: _, ...rest } = event;
-        return rest;
-    }
-    return event;
-}
 //# sourceMappingURL=storage.js.map