@aikirun/workflow 0.16.0 → 0.18.0

package/README.md

@@ -32,6 +32,7 @@ Run with a client:
 ```typescript
 import { client } from "@aikirun/client";
 
+// Set AIKI_API_KEY env variable or pass apiKey option
 const aikiClient = client({
 	url: "http://localhost:9850",
 	redis: { host: "localhost", port: 6379 },

package/dist/index.d.ts

@@ -1,16 +1,16 @@
 import { WorkflowName, WorkflowVersionId } from '@aikirun/types/workflow';
 import { Client, Logger, ApiClient } from '@aikirun/types/client';
 import { INTERNAL } from '@aikirun/types/symbols';
-import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, WorkflowStartOptions, WorkflowDefinitionOptions } from '@aikirun/types/workflow-run';
+import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, WorkflowRunAddress, ChildWorkflowRunInfo, WorkflowStartOptions, WorkflowDefinitionOptions } from '@aikirun/types/workflow-run';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DurationObject, Duration } from '@aikirun/types/duration';
 import { SleepResult } from '@aikirun/types/sleep';
-import { EventSendOptions, EventWaitOptions, EventWaitState } from '@aikirun/types/event';
+import { EventSendOptions, EventWaitOptions, EventWaitResult } from '@aikirun/types/event';
 import { Serializable } from '@aikirun/types/serializable';
 import { DistributiveOmit, RequireAtLeastOneProp } from '@aikirun/types/utils';
-import { TaskId } from '@aikirun/types/task';
+import { TaskInfo, TaskAddress } from '@aikirun/types/task';
 import { WorkflowRunStateRequest, WorkflowRunTransitionTaskStateRequestV1 } from '@aikirun/types/workflow-run-api';
-import { OverlapPolicy, ScheduleActivateOptions, ScheduleId } from '@aikirun/types/schedule';
+import { ScheduleOverlapPolicy, ScheduleActivateOptions, ScheduleId } from '@aikirun/types/schedule';
 
 type NonEmptyArray<T> = [T, ...T[]];
 
@@ -19,10 +19,7 @@ type IsSubtype<SubT, SuperT> = SubT extends SuperT ? true : false;
 type And<T extends NonEmptyArray<boolean>> = T extends [infer First, ...infer Rest] ? false extends First ? false : Rest extends NonEmptyArray<boolean> ? And<Rest> : true : never;
 type Or<T extends NonEmptyArray<boolean>> = T extends [infer First, ...infer Rest] ? true extends First ? true : Rest extends NonEmptyArray<boolean> ? Or<Rest> : false : never;
 type PathFromObject<T, IncludeArrayKeys extends boolean = false> = T extends T ? PathFromObjectInternal<T, IncludeArrayKeys> : never;
-type PathFromObjectInternal<T, IncludeArrayKeys extends boolean> = And<[
-    IsSubtype<T, object>,
-    Or<[IncludeArrayKeys, NonArrayObject<T> extends never ? false : true]>
-]> extends true ? {
+type PathFromObjectInternal<T, IncludeArrayKeys extends boolean> = And<[IsSubtype<T, object>, Or<[IncludeArrayKeys, NonArrayObject<T> extends never ? false : true]>]> extends true ? {
     [K in Exclude<keyof T, symbol>]-?: And<[
         IsSubtype<NonNullable<T[K]>, object>,
         Or<[IncludeArrayKeys, NonArrayObject<NonNullable<T[K]>> extends never ? false : true]>
@@ -93,9 +90,7 @@ interface WorkflowRunHandle<Input, Output, AppContext, TEvents extends EventsDef
     [INTERNAL]: {
         client: Client<AppContext>;
         transitionState: (state: WorkflowRunStateRequest) => Promise<void>;
-        transitionTaskState: (request: DistributiveOmit<WorkflowRunTransitionTaskStateRequestV1, "id" | "expectedRevision">) => Promise<{
-            taskId: TaskId;
-        }>;
+        transitionTaskState: (request: DistributiveOmit<WorkflowRunTransitionTaskStateRequestV1, "id" | "expectedWorkflowRunRevision">) => Promise<TaskInfo>;
         assertExecutionAllowed: () => void;
     };
 }
@@ -151,8 +146,8 @@ type EventWaiters<TEvents extends EventsDefinition> = {
     [K in keyof TEvents]: EventWaiter<EventData<TEvents[K]>>;
 };
 interface EventWaiter<Data> {
-    wait(options?: EventWaitOptions<false>): Promise<EventWaitState<Data, false>>;
-    wait(options: EventWaitOptions<true>): Promise<EventWaitState<Data, true>>;
+    wait(options?: EventWaitOptions<false>): Promise<EventWaitResult<Data, false>>;
+    wait(options: EventWaitOptions<true>): Promise<EventWaitResult<Data, true>>;
 }
 type EventSenders<TEvents extends EventsDefinition> = {
     [K in keyof TEvents]: EventSender<EventData<TEvents[K]>>;
@@ -171,13 +166,29 @@ type EventMulticasters<TEvents extends EventsDefinition> = {
 interface EventMulticaster<Data> {
     with(): EventMulticasterBuilder<Data>;
     send: <AppContext>(client: Client<AppContext>, runId: string | string[], ...args: Data extends void ? [] : [Data]) => Promise<void>;
+    sendByReferenceId: <AppContext>(client: Client<AppContext>, referenceId: string | string[], ...args: Data extends void ? [] : [Data]) => Promise<void>;
 }
 interface EventMulticasterBuilder<Data> {
     opt<Path extends PathFromObject<EventSendOptions>>(path: Path, value: TypeOfValueAtPath<EventSendOptions, Path>): EventMulticasterBuilder<Data>;
     send: <AppContext>(client: Client<AppContext>, runId: string | string[], ...args: Data extends void ? [] : [Data]) => Promise<void>;
+    sendByReferenceId: <AppContext>(client: Client<AppContext>, referenceId: string | string[], ...args: Data extends void ? [] : [Data]) => Promise<void>;
 }
 declare function createEventWaiters<TEvents extends EventsDefinition>(handle: WorkflowRunHandle<unknown, unknown, unknown, TEvents>, eventsDefinition: TEvents, logger: Logger): EventWaiters<TEvents>;
-declare function createEventSenders<TEvents extends EventsDefinition>(api: ApiClient, workflowRunId: string, eventsDefinition: TEvents, logger: Logger, onSend: (run: WorkflowRun<unknown, unknown>) => void): EventSenders<TEvents>;
+declare function createEventSenders<TEvents extends EventsDefinition>(api: ApiClient, workflowRunId: string, eventsDefinition: TEvents, logger: Logger): EventSenders<TEvents>;
+
+/** biome-ignore-all lint/style/noNonNullAssertion: Manifest boundaries are tracked, hence, we never exceed array boundaries */
+
+interface ReplayManifest {
+    consumeNextTask(address: TaskAddress): TaskInfo | undefined;
+    consumeNextChildWorkflowRun(address: WorkflowRunAddress): ChildWorkflowRunInfo | undefined;
+    hasUnconsumedEntries(): boolean;
+    getUnconsumedEntries(): UnconsumedManifestEntries;
+}
+interface UnconsumedManifestEntries {
+    taskIds: string[];
+    childWorkflowRunIds: string[];
+}
+declare function createReplayManifest(run: WorkflowRun): ReplayManifest;
 
 interface WorkflowRunContext<Input, AppContext, TEvents extends EventsDefinition> {
     id: WorkflowRunId;
@@ -189,6 +200,7 @@ interface WorkflowRunContext<Input, AppContext, TEvents extends EventsDefinition
     events: EventWaiters<TEvents>;
     [INTERNAL]: {
         handle: WorkflowRunHandle<Input, unknown, AppContext, TEvents>;
+        replayManifest: ReplayManifest;
         options: {
             spinThresholdMs: number;
         };
@@ -275,7 +287,7 @@ declare class WorkflowVersionImpl<Input, Output, AppContext, TEvents extends Eve
     startWithOpts(client: Client<AppContext>, startOpts: WorkflowStartOptions, ...args: Input extends void ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
     startAsChild(parentRun: WorkflowRunContext<unknown, AppContext, EventsDefinition>, ...args: Input extends void ? [] : [Input]): Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEvents>>;
     startAsChildWithOpts(parentRun: WorkflowRunContext<unknown, AppContext, EventsDefinition>, startOpts: WorkflowStartOptions, ...args: Input extends void ? [] : [Input]): Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEvents>>;
-    private assertUniqueChildRunReferenceId;
+    private throwNonDeterminismError;
     getHandleById(client: Client<AppContext>, runId: string): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
     getHandleByReferenceId(client: Client<AppContext>, referenceId: string): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
     private handler;
@@ -309,12 +321,12 @@ interface CronScheduleParams {
     type: "cron";
     expression: string;
     timezone?: string;
-    overlapPolicy?: OverlapPolicy;
+    overlapPolicy?: ScheduleOverlapPolicy;
 }
 interface IntervalScheduleParams {
     type: "interval";
     every: DurationObject;
-    overlapPolicy?: OverlapPolicy;
+    overlapPolicy?: ScheduleOverlapPolicy;
 }
 type ScheduleParams = CronScheduleParams | IntervalScheduleParams;
 interface ScheduleHandle {
@@ -393,4 +405,4 @@ interface Workflow {
     };
 }
 
-export { type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type ScheduleDefinition, type ScheduleHandle, type ScheduleParams, type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createEventSenders, createEventWaiters, createSleeper, event, schedule, workflow, workflowRegistry, workflowRunHandle };
+export { type EventDefinition, type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type ReplayManifest, type ScheduleDefinition, type ScheduleHandle, type ScheduleParams, type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createEventSenders, createEventWaiters, createReplayManifest, createSleeper, event, schedule, workflow, workflowRegistry, workflowRunHandle };

package/dist/index.js

@@ -11,7 +11,7 @@ var WorkflowRegistryImpl = class {
       return this;
     }
     if (workflows.has(workflow2.versionId)) {
-      throw new Error(`Workflow "${workflow2.name}/${workflow2.versionId}" is already registered`);
+      throw new Error(`Workflow "${workflow2.name}:${workflow2.versionId}" is already registered`);
     }
     workflows.set(workflow2.versionId, workflow2);
     return this;
@@ -55,7 +55,7 @@ var WorkflowRegistryImpl = class {
 
 // ../../lib/array/utils.ts
 function isNonEmptyArray(value) {
-  return value.length > 0;
+  return value !== void 0 && value.length > 0;
 }
 
 // ../../lib/async/delay.ts
@@ -77,6 +77,9 @@ function delay(ms, options) {
   });
 }
 
+// ../../lib/crypto/hash.ts
+import { createHash } from "crypto";
+
 // ../../lib/json/stable-stringify.ts
 function stableStringify(value) {
   return stringifyValue(value);
@@ -317,20 +320,20 @@ function createEventWaiters(handle, eventsDefinition, logger) {
   return waiters;
 }
 function createEventWaiter(handle, eventName, schema, logger) {
-  let nextEventIndex = 0;
+  let nextIndex = 0;
   async function wait(options) {
     await handle.refresh();
-    const events = handle.run.eventsQueue[eventName]?.events ?? [];
-    const event2 = events[nextEventIndex];
-    if (event2) {
-      nextEventIndex++;
-      if (event2.status === "timeout") {
+    const eventWaits = handle.run.eventWaitQueues[eventName]?.eventWaits ?? [];
+    const existingEventWait = eventWaits[nextIndex];
+    if (existingEventWait) {
+      nextIndex++;
+      if (existingEventWait.status === "timeout") {
         logger.debug("Timed out waiting for event");
         return { timeout: true };
       }
-      let data = event2.data;
+      let data = existingEventWait.data;
       if (schema) {
-        const schemaValidation = schema["~standard"].validate(event2.data);
+        const schemaValidation = schema["~standard"].validate(existingEventWait.data);
         const schemaValidationResult = schemaValidation instanceof Promise ? await schemaValidation : schemaValidation;
         if (!schemaValidationResult.issues) {
           data = schemaValidationResult.value;
@@ -370,7 +373,7 @@ function createEventWaiter(handle, eventName, schema, logger) {
   }
   return { wait };
 }
-function createEventSenders(api, workflowRunId, eventsDefinition, logger, onSend) {
+function createEventSenders(api, workflowRunId, eventsDefinition, logger) {
   const senders = {};
   for (const [eventName, eventDefinition] of Object.entries(eventsDefinition)) {
     const sender = createEventSender(
@@ -378,18 +381,17 @@ function createEventSenders(api, workflowRunId, eventsDefinition, logger, onSend
       workflowRunId,
       eventName,
       eventDefinition.schema,
-      logger.child({ "aiki.eventName": eventName }),
-      onSend
+      logger.child({ "aiki.eventName": eventName })
     );
     senders[eventName] = sender;
   }
   return senders;
 }
-function createEventSender(api, workflowRunId, eventName, schema, logger, onSend, options) {
+function createEventSender(api, workflowRunId, eventName, schema, logger, options) {
   const optsOverrider = objectOverrider(options ?? {});
   const createBuilder = (optsBuilder) => ({
     opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
-    send: (...args) => createEventSender(api, workflowRunId, eventName, schema, logger, onSend, optsBuilder.build()).send(...args)
+    send: (...args) => createEventSender(api, workflowRunId, eventName, schema, logger, optsBuilder.build()).send(...args)
   });
   async function send(...args) {
     let data = args[0];
@@ -402,13 +404,12 @@ function createEventSender(api, workflowRunId, eventName, schema, logger, onSend
       }
       data = schemaValidationResult.value;
     }
-    const { run } = await api.workflowRun.sendEventV1({
+    await api.workflowRun.sendEventV1({
       id: workflowRunId,
       eventName,
       data,
       options
     });
-    onSend(run);
     logger.info("Sent event to workflow", {
       ...options?.reference ? { "aiki.referenceId": options.reference.id } : {}
     });
@@ -439,6 +440,11 @@ function createEventMulticaster(workflowName, workflowVersionId, eventName, sche
       client,
       runId,
       ...args
+    ),
+    sendByReferenceId: (client, referenceId, ...args) => createEventMulticaster(workflowName, workflowVersionId, eventName, schema, optsBuilder.build()).sendByReferenceId(
+      client,
+      referenceId,
+      ...args
     )
   });
   async function send(client, runId, ...args) {
@@ -472,12 +478,51 @@ function createEventMulticaster(workflowName, workflowVersionId, eventName, sche
       "aiki.workflowVersionId": workflowVersionId,
       "aiki.workflowRunIds": runIds,
       "aiki.eventName": eventName,
-      ...options?.reference ? { "aiki.referenceId": options.reference.id } : {}
+      ...options?.reference ? { "aiki.eventReferenceId": options.reference.id } : {}
+    });
+  }
+  async function sendByReferenceId(client, referenceId, ...args) {
+    let data = args[0];
+    if (schema) {
+      const schemaValidation = schema["~standard"].validate(data);
+      const schemaValidationResult = schemaValidation instanceof Promise ? await schemaValidation : schemaValidation;
+      if (schemaValidationResult.issues) {
+        client.logger.error("Invalid event data", {
+          "aiki.workflowName": workflowName,
+          "aiki.workflowVersionId": workflowVersionId,
+          "aiki.eventName": eventName,
+          "aiki.issues": schemaValidationResult.issues
+        });
+        throw new SchemaValidationError("Invalid event data", schemaValidationResult.issues);
+      }
+      data = schemaValidationResult.value;
+    }
+    const referenceIds = Array.isArray(referenceId) ? referenceId : [referenceId];
+    if (!isNonEmptyArray(referenceIds)) {
+      return;
+    }
+    await client.api.workflowRun.multicastEventByReferenceV1({
+      references: referenceIds.map((referenceId2) => ({
+        name: workflowName,
+        versionId: workflowVersionId,
+        referenceId: referenceId2
+      })),
+      eventName,
+      data,
+      options
+    });
+    client.logger.info("Multicasted event by reference", {
+      "aiki.workflowName": workflowName,
+      "aiki.workflowVersionId": workflowVersionId,
+      "aiki.referenceIds": referenceIds,
+      "aiki.eventName": eventName,
+      ...options?.reference ? { "aiki.eventReferenceId": options.reference.id } : {}
     });
   }
   return {
     with: () => createBuilder(optsOverrider()),
-    send
+    send,
+    sendByReferenceId
   };
 }
 
@@ -506,9 +551,7 @@ var WorkflowRunHandleImpl = class {
     this._run = _run;
     this.logger = logger;
     this.api = client.api;
-    this.events = createEventSenders(client.api, this._run.id, eventsDefinition, this.logger, (run) => {
-      this._run = run;
-    });
+    this.events = createEventSenders(client.api, this._run.id, eventsDefinition, this.logger);
     this[INTERNAL2] = {
       client,
       transitionState: this.transitionState.bind(this),
@@ -604,24 +647,26 @@ var WorkflowRunHandleImpl = class {
   }
   async transitionState(targetState) {
     try {
+      let response;
       if (targetState.status === "scheduled" && (targetState.reason === "new" || targetState.reason === "resume" || targetState.reason === "awake_early") || targetState.status === "paused" || targetState.status === "cancelled") {
-        const { run: run2 } = await this.api.workflowRun.transitionStateV1({
+        response = await this.api.workflowRun.transitionStateV1({
           type: "pessimistic",
           id: this.run.id,
           state: targetState
         });
-        this._run = run2;
-        return;
+      } else {
+        response = await this.api.workflowRun.transitionStateV1({
+          type: "optimistic",
+          id: this.run.id,
+          state: targetState,
+          expectedRevision: this.run.revision
+        });
       }
-      const { run } = await this.api.workflowRun.transitionStateV1({
-        type: "optimistic",
-        id: this.run.id,
-        state: targetState,
-        expectedRevision: this.run.revision
-      });
-      this._run = run;
+      this._run.revision = response.revision;
+      this._run.state = response.state;
+      this._run.attempts = response.attempts;
     } catch (error) {
-      if (isConflictError(error)) {
+      if (isWorkflowRunRevisionConflictError(error)) {
         throw new WorkflowRunRevisionConflictError2(this.run.id);
       }
       throw error;
@@ -629,15 +674,14 @@ var WorkflowRunHandleImpl = class {
   }
   async transitionTaskState(request) {
     try {
-      const { run, taskId } = await this.api.workflowRun.transitionTaskStateV1({
+      const { taskInfo } = await this.api.workflowRun.transitionTaskStateV1({
         ...request,
         id: this.run.id,
-        expectedRevision: this.run.revision
+        expectedWorkflowRunRevision: this.run.revision
       });
-      this._run = run;
-      return { taskId };
+      return taskInfo;
     } catch (error) {
-      if (isConflictError(error)) {
+      if (isWorkflowRunRevisionConflictError(error)) {
         throw new WorkflowRunRevisionConflictError2(this.run.id);
       }
       throw error;
@@ -650,8 +694,73 @@ var WorkflowRunHandleImpl = class {
     }
   }
 };
-function isConflictError(error) {
-  return error != null && typeof error === "object" && "code" in error && error.code === "CONFLICT";
+function isWorkflowRunRevisionConflictError(error) {
+  return error != null && typeof error === "object" && "code" in error && error.code === "WORKFLOW_RUN_REVISION_CONFLICT";
+}
+
+// run/replay-manifest.ts
+function createReplayManifest(run) {
+  const { taskQueues, childWorkflowRunQueues } = run;
+  let totalEntries = 0;
+  const taskCountByAddress = {};
+  const childWorkflowRunCountByAddress = {};
+  for (const [address, queue] of Object.entries(taskQueues)) {
+    taskCountByAddress[address] = queue.tasks.length;
+    totalEntries += queue.tasks.length;
+  }
+  for (const [address, queue] of Object.entries(childWorkflowRunQueues)) {
+    childWorkflowRunCountByAddress[address] = queue.childWorkflowRuns.length;
+    totalEntries += queue.childWorkflowRuns.length;
+  }
+  const nextTaskIndexByAddress = {};
+  const nextChildWorkflowRunIndexByAddress = {};
+  let consumedEntries = 0;
+  return {
+    consumeNextTask(address) {
+      const taskCount = taskCountByAddress[address] ?? 0;
+      const nextIndex = nextTaskIndexByAddress[address] ?? 0;
+      if (nextIndex >= taskCount) {
+        return void 0;
+      }
+      const task = taskQueues[address].tasks[nextIndex];
+      nextTaskIndexByAddress[address] = nextIndex + 1;
+      consumedEntries++;
+      return task;
+    },
+    consumeNextChildWorkflowRun(address) {
+      const childWorkflowRunCount = childWorkflowRunCountByAddress[address] ?? 0;
+      const nextIndex = nextChildWorkflowRunIndexByAddress[address] ?? 0;
+      if (nextIndex >= childWorkflowRunCount) {
+        return void 0;
+      }
+      const childWorkflowRun = childWorkflowRunQueues[address].childWorkflowRuns[nextIndex];
+      nextChildWorkflowRunIndexByAddress[address] = nextIndex + 1;
+      consumedEntries++;
+      return childWorkflowRun;
+    },
+    hasUnconsumedEntries() {
+      return consumedEntries < totalEntries;
+    },
+    getUnconsumedEntries() {
+      const taskIds = [];
+      const childWorkflowRunIds = [];
+      for (const [address, taskCount] of Object.entries(taskCountByAddress)) {
+        const tasks = taskQueues[address].tasks;
+        const nextIndex = nextTaskIndexByAddress[address] ?? 0;
+        for (let i = nextIndex; i < taskCount; i++) {
+          taskIds.push(tasks[i].id);
+        }
+      }
+      for (const [address, childWorkflowRunCount] of Object.entries(childWorkflowRunCountByAddress)) {
+        const childWorkflowRuns = childWorkflowRunQueues[address].childWorkflowRuns;
+        const nextIndex = nextChildWorkflowRunIndexByAddress[address] ?? 0;
+        for (let i = nextIndex; i < childWorkflowRunCount; i++) {
+          childWorkflowRunIds.push(childWorkflowRuns[i].id);
+        }
+      }
+      return { taskIds, childWorkflowRunIds };
+    }
+  };
 }
 
 // run/sleeper.ts
@@ -663,17 +772,17 @@ import {
 var MAX_SLEEP_YEARS = 10;
 var MAX_SLEEP_MS = MAX_SLEEP_YEARS * 365 * 24 * 60 * 60 * 1e3;
 function createSleeper(handle, logger) {
-  const nextSleepIndexByName = {};
+  const nextIndexBySleepName = {};
   return async (name, duration) => {
     const sleepName = name;
     let durationMs = toMilliseconds(duration);
     if (durationMs > MAX_SLEEP_MS) {
       throw new Error(`Sleep duration ${durationMs}ms exceeds maximum of ${MAX_SLEEP_YEARS} years`);
     }
-    const nextSleepIndex = nextSleepIndexByName[sleepName] ?? 0;
-    const sleepQueue = handle.run.sleepsQueue[sleepName] ?? { sleeps: [] };
-    const sleepState = sleepQueue.sleeps[nextSleepIndex];
-    if (!sleepState) {
+    const nextIndex = nextIndexBySleepName[sleepName] ?? 0;
+    const sleepQueue = handle.run.sleepQueues[sleepName] ?? { sleeps: [] };
+    const existingSleep = sleepQueue.sleeps[nextIndex];
+    if (!existingSleep) {
       try {
         await handle[INTERNAL3].transitionState({ status: "sleeping", sleepName, durationMs });
         logger.info("Going to sleep", {
@@ -688,37 +797,37 @@ function createSleeper(handle, logger) {
       }
       throw new WorkflowRunSuspendedError2(handle.run.id);
     }
-    if (sleepState.status === "sleeping") {
+    if (existingSleep.status === "sleeping") {
       logger.debug("Already sleeping", {
         "aiki.sleepName": sleepName,
-        "aiki.awakeAt": sleepState.awakeAt
+        "aiki.awakeAt": existingSleep.awakeAt
       });
       throw new WorkflowRunSuspendedError2(handle.run.id);
     }
-    sleepState.status;
-    nextSleepIndexByName[sleepName] = nextSleepIndex + 1;
-    if (sleepState.status === "cancelled") {
+    existingSleep.status;
+    nextIndexBySleepName[sleepName] = nextIndex + 1;
+    if (existingSleep.status === "cancelled") {
       logger.debug("Sleep cancelled", {
         "aiki.sleepName": sleepName,
-        "aiki.cancelledAt": sleepState.cancelledAt
+        "aiki.cancelledAt": existingSleep.cancelledAt
       });
       return { cancelled: true };
     }
-    if (durationMs === sleepState.durationMs) {
+    if (durationMs === existingSleep.durationMs) {
       logger.debug("Sleep completed", {
         "aiki.sleepName": sleepName,
         "aiki.durationMs": durationMs,
-        "aiki.completedAt": sleepState.completedAt
+        "aiki.completedAt": existingSleep.completedAt
       });
       return { cancelled: false };
     }
-    if (durationMs > sleepState.durationMs) {
+    if (durationMs > existingSleep.durationMs) {
       logger.warn("Higher sleep duration encountered during replay. Sleeping for remaining duration", {
         "aiki.sleepName": sleepName,
-        "aiki.historicDurationMs": sleepState.durationMs,
+        "aiki.historicDurationMs": existingSleep.durationMs,
         "aiki.latestDurationMs": durationMs
       });
-      durationMs -= sleepState.durationMs;
+      durationMs -= existingSleep.durationMs;
     } else {
       return { cancelled: false };
     }
@@ -804,7 +913,7 @@ import { INTERNAL as INTERNAL6 } from "@aikirun/types/symbols";
 
 // ../../lib/address/index.ts
 function getWorkflowRunAddress(name, versionId, referenceId) {
-  return `${name}/${versionId}/${referenceId}`;
+  return `${name}:${versionId}:${referenceId}`;
 }
 
 // workflow-version.ts
@@ -812,6 +921,7 @@ import { INTERNAL as INTERNAL5 } from "@aikirun/types/symbols";
 import { TaskFailedError } from "@aikirun/types/task";
 import { SchemaValidationError as SchemaValidationError2 } from "@aikirun/types/validator";
 import {
+  NonDeterminismError,
   WorkflowRunFailedError as WorkflowRunFailedError2,
   WorkflowRunRevisionConflictError as WorkflowRunRevisionConflictError5,
   WorkflowRunSuspendedError as WorkflowRunSuspendedError4
@@ -824,13 +934,13 @@ import {
   WorkflowRunRevisionConflictError as WorkflowRunRevisionConflictError4,
   WorkflowRunSuspendedError as WorkflowRunSuspendedError3
 } from "@aikirun/types/workflow-run";
-async function childWorkflowRunHandle(client, run, parentRun, logger, eventsDefinition) {
+async function childWorkflowRunHandle(client, run, parentRun, childWorkflowRunWaitQueues, logger, eventsDefinition) {
   const handle = await workflowRunHandle(client, run, eventsDefinition, logger);
   return {
     run: handle.run,
     events: handle.events,
     refresh: handle.refresh.bind(handle),
-    waitForStatus: createStatusWaiter(handle, parentRun, logger),
+    waitForStatus: createStatusWaiter(handle, parentRun, childWorkflowRunWaitQueues, logger),
     cancel: handle.cancel.bind(handle),
     pause: handle.pause.bind(handle),
     resume: handle.resume.bind(handle),
@@ -838,15 +948,21 @@ async function childWorkflowRunHandle(client, run, parentRun, logger, eventsDefi
     [INTERNAL4]: handle[INTERNAL4]
   };
 }
-function createStatusWaiter(handle, parentRun, logger) {
-  let nextWaitIndex = 0;
+function createStatusWaiter(handle, parentRun, childWorkflowRunWaitQueues, logger) {
+  const nextIndexByStatus = {
+    cancelled: 0,
+    completed: 0,
+    failed: 0
+  };
   async function waitForStatus(expectedStatus, options) {
     const parentRunHandle = parentRun[INTERNAL4].handle;
-    const waitResults = parentRunHandle.run.childWorkflowRuns[handle.run.address]?.statusWaitResults ?? [];
-    const waitResult = waitResults[nextWaitIndex];
-    if (waitResult) {
-      nextWaitIndex++;
-      if (waitResult.status === "timeout") {
+    const nextIndex = nextIndexByStatus[expectedStatus];
+    const { run } = handle;
+    const childWorkflowRunWaits = childWorkflowRunWaitQueues[expectedStatus].childWorkflowRunWaits;
+    const existingChildWorkflowRunWait = childWorkflowRunWaits[nextIndex];
+    if (existingChildWorkflowRunWait) {
+      nextIndexByStatus[expectedStatus] = nextIndex + 1;
+      if (existingChildWorkflowRunWait.status === "timeout") {
         logger.debug("Timed out waiting for child workflow status", {
           "aiki.childWorkflowExpectedStatus": expectedStatus
         });
@@ -855,43 +971,29 @@ function createStatusWaiter(handle, parentRun, logger) {
           cause: "timeout"
         };
       }
-      if (waitResult.childWorkflowRunState.status === expectedStatus) {
+      const childWorkflowRunStatus = existingChildWorkflowRunWait.childWorkflowRunState.status;
+      if (childWorkflowRunStatus === expectedStatus) {
         return {
           success: true,
-          state: waitResult.childWorkflowRunState
+          state: existingChildWorkflowRunWait.childWorkflowRunState
         };
       }
-      if (isTerminalWorkflowRunStatus2(waitResult.childWorkflowRunState.status)) {
+      if (isTerminalWorkflowRunStatus2(childWorkflowRunStatus)) {
         logger.debug("Child workflow run reached termnial state", {
-          "aiki.childWorkflowTerminalStatus": waitResult.childWorkflowRunState.status
+          "aiki.childWorkflowTerminalStatus": childWorkflowRunStatus
         });
         return {
           success: false,
           cause: "run_terminated"
         };
       }
-    }
-    const { state } = handle.run;
-    if (state.status === expectedStatus) {
-      return {
-        success: true,
-        state
-      };
-    }
-    if (isTerminalWorkflowRunStatus2(state.status)) {
-      logger.debug("Child workflow run reached termnial state", {
-        "aiki.childWorkflowTerminalStatus": state.status
-      });
-      return {
-        success: false,
-        cause: "run_terminated"
-      };
+      childWorkflowRunStatus;
     }
     const timeoutInMs = options?.timeout && toMilliseconds(options.timeout);
     try {
       await parentRunHandle[INTERNAL4].transitionState({
         status: "awaiting_child_workflow",
-        childWorkflowRunId: handle.run.id,
+        childWorkflowRunId: run.id,
         childWorkflowRunStatus: expectedStatus,
         timeoutInMs
       });
@@ -945,7 +1047,7 @@ var WorkflowVersionImpl = class {
       }
       input = schemaValidationResult.value;
     }
-    const { run } = await client.api.workflowRun.createV1({
+    const { id } = await client.api.workflowRun.createV1({
       name: this.name,
       versionId: this.versionId,
       input,
@@ -954,9 +1056,9 @@ var WorkflowVersionImpl = class {
     client.logger.info("Created workflow", {
       "aiki.workflowName": this.name,
       "aiki.workflowVersionId": this.versionId,
-      "aiki.workflowRunId": run.id
+      "aiki.workflowRunId": id
     });
-    return workflowRunHandle(client, run, this[INTERNAL5].eventsDefinition);
+    return workflowRunHandle(client, id, this[INTERNAL5].eventsDefinition);
   }
   async startAsChild(parentRun, ...args) {
     return this.startAsChildWithOpts(parentRun, this.params.opts ?? {}, ...args);
@@ -968,48 +1070,41 @@ var WorkflowVersionImpl = class {
     const inputRaw = args[0];
     const input = await this.parse(parentRunHandle, this.params.schema?.input, inputRaw, parentRun.logger);
     const inputHash = await hashInput(input);
-    const reference = startOpts.reference;
-    const address = getWorkflowRunAddress(this.name, this.versionId, reference?.id ?? inputHash);
-    const existingRunInfo = parentRunHandle.run.childWorkflowRuns[address];
-    if (existingRunInfo) {
-      await this.assertUniqueChildRunReferenceId(
-        parentRunHandle,
-        existingRunInfo,
-        inputHash,
-        reference,
-        parentRun.logger
-      );
-      const { run: existingRun } = await client.api.workflowRun.getByIdV1({ id: existingRunInfo.id });
-      if (existingRun.state.status === "completed") {
-        await this.parse(parentRunHandle, this.params.schema?.output, existingRun.state.output, parentRun.logger);
+    const referenceId = startOpts.reference?.id;
+    const address = getWorkflowRunAddress(this.name, this.versionId, referenceId ?? inputHash);
+    const replayManifest = parentRun[INTERNAL5].replayManifest;
+    if (replayManifest.hasUnconsumedEntries()) {
+      const existingRunInfo = replayManifest.consumeNextChildWorkflowRun(address);
+      if (existingRunInfo) {
+        const { run: existingRun } = await client.api.workflowRun.getByIdV1({ id: existingRunInfo.id });
+        if (existingRun.state.status === "completed") {
+          await this.parse(parentRunHandle, this.params.schema?.output, existingRun.state.output, parentRun.logger);
+        }
+        const logger2 = parentRun.logger.child({
+          "aiki.childWorkflowName": existingRun.name,
+          "aiki.childWorkflowVersionId": existingRun.versionId,
+          "aiki.childWorkflowRunId": existingRun.id
+        });
+        return childWorkflowRunHandle(
+          client,
+          existingRun,
+          parentRun,
+          existingRunInfo.childWorkflowRunWaitQueues,
+          logger2,
+          this[INTERNAL5].eventsDefinition
+        );
       }
-      const logger2 = parentRun.logger.child({
-        "aiki.childWorkflowName": existingRun.name,
-        "aiki.childWorkflowVersionId": existingRun.versionId,
-        "aiki.childWorkflowRunId": existingRun.id
-      });
-      return childWorkflowRunHandle(
-        client,
-        existingRun,
-        parentRun,
-        logger2,
-        this[INTERNAL5].eventsDefinition
-      );
+      await this.throwNonDeterminismError(parentRun, parentRunHandle, inputHash, referenceId, replayManifest);
     }
-    const { run: newRun } = await client.api.workflowRun.createV1({
+    const shard = parentRun.options.shard;
+    const { id: newRunId } = await client.api.workflowRun.createV1({
       name: this.name,
       versionId: this.versionId,
       input,
       parentWorkflowRunId: parentRun.id,
-      options: startOpts
+      options: shard === void 0 ? startOpts : { ...startOpts, shard }
     });
-    parentRunHandle.run.childWorkflowRuns[address] = {
-      id: newRun.id,
-      name: newRun.name,
-      versionId: newRun.versionId,
-      inputHash,
-      statusWaitResults: []
-    };
+    const { run: newRun } = await client.api.workflowRun.getByIdV1({ id: newRunId });
     const logger = parentRun.logger.child({
       "aiki.childWorkflowName": newRun.name,
       "aiki.childWorkflowVersionId": newRun.versionId,
@@ -1020,32 +1115,33 @@ var WorkflowVersionImpl = class {
       client,
       newRun,
       parentRun,
+      {
+        cancelled: { childWorkflowRunWaits: [] },
+        completed: { childWorkflowRunWaits: [] },
+        failed: { childWorkflowRunWaits: [] }
+      },
       logger,
       this[INTERNAL5].eventsDefinition
     );
   }
-  async assertUniqueChildRunReferenceId(parentRunHandle, existingRunInfo, inputHash, reference, logger) {
-    if (existingRunInfo.inputHash !== inputHash && reference) {
-      const conflictPolicy = reference.conflictPolicy ?? "error";
-      if (conflictPolicy !== "error") {
-        return;
-      }
-      logger.error("Reference ID already used by another child workflow", {
-        "aiki.referenceId": reference.id,
-        "aiki.existingChildWorkflowRunId": existingRunInfo.id
-      });
-      const error = new WorkflowRunFailedError2(
-        parentRunHandle.run.id,
-        parentRunHandle.run.attempts,
-        `Reference ID "${reference.id}" already used by another child workflow run ${existingRunInfo.id}`
-      );
-      await parentRunHandle[INTERNAL5].transitionState({
-        status: "failed",
-        cause: "self",
-        error: createSerializableError(error)
-      });
-      throw error;
+  async throwNonDeterminismError(parentRun, parentRunHandle, inputHash, referenceId, manifest) {
+    const unconsumedManifestEntries = manifest.getUnconsumedEntries();
+    const logMeta = {
+      "aiki.workflowName": this.name,
+      "aiki.inputHash": inputHash,
+      "aiki.unconsumedManifestEntries": unconsumedManifestEntries
+    };
+    if (referenceId !== void 0) {
+      logMeta["aiki.referenceId"] = referenceId;
     }
+    parentRun.logger.error("Replay divergence", logMeta);
+    const error = new NonDeterminismError(parentRun.id, parentRunHandle.run.attempts, unconsumedManifestEntries);
+    await parentRunHandle[INTERNAL5].transitionState({
+      status: "failed",
+      cause: "self",
+      error: createSerializableError(error)
+    });
+    throw error;
   }
   async getHandleById(client, runId) {
     return workflowRunHandle(client, runId, this[INTERNAL5].eventsDefinition);
@@ -1081,7 +1177,7 @@ var WorkflowVersionImpl = class {
         const output = await this.parse(handle, this.params.schema?.output, outputRaw, run.logger);
         return output;
       } catch (error) {
-        if (error instanceof WorkflowRunSuspendedError4 || error instanceof WorkflowRunFailedError2 || error instanceof WorkflowRunRevisionConflictError5) {
+        if (error instanceof WorkflowRunSuspendedError4 || error instanceof WorkflowRunFailedError2 || error instanceof WorkflowRunRevisionConflictError5 || error instanceof NonDeterminismError) {
           throw error;
         }
         const attempts = handle.run.attempts;
@@ -1211,7 +1307,7 @@ var WorkflowImpl = class {
   }
   v(versionId, params) {
     if (this.workflowVersions.has(versionId)) {
-      throw new Error(`Workflow "${this.name}/${versionId}" already exists`);
+      throw new Error(`Workflow "${this.name}:${versionId}" already exists`);
     }
     const workflowVersion = new WorkflowVersionImpl(this.name, versionId, params);
     this.workflowVersions.set(
@@ -1231,6 +1327,7 @@ export {
   WorkflowVersionImpl,
   createEventSenders,
   createEventWaiters,
+  createReplayManifest,
   createSleeper,
   event,
   schedule,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/workflow",
-	"version": "0.16.0",
+	"version": "0.18.0",
 	"description": "Workflow SDK for Aiki - define durable workflows with tasks, sleeps, waits, and event handling",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -18,7 +18,7 @@
 		"build": "tsup"
 	},
 	"dependencies": {
-		"@aikirun/types": "0.16.0",
+		"@aikirun/types": "0.18.0",
 		"@standard-schema/spec": "^1.1.0"
 	},
 	"publishConfig": {