@aikirun/workflow 0.7.0 → 0.8.0

package/README.md

@@ -16,10 +16,10 @@ npm install @aikirun/workflow
 import { workflow } from "@aikirun/workflow";
 import { markUserVerified, sendVerificationEmail } from "./tasks.ts";
 
-export const onboardingWorkflow = workflow({ id: "user-onboarding" });
+export const onboardingWorkflow = workflow({ name: "user-onboarding" });
 
-export const onboardingWorkflowV1 = onboardingWorkflow.v("1.0", {
-	async handler(input: { email: string }, run) {
+export const onboardingWorkflowV1 = onboardingWorkflow.v("1.0.0", {
+	async handler(run, input: { email: string }) {
 		run.logger.info("Starting onboarding", { email: input.email });
 
 		// Execute a task to send verification email
@@ -30,7 +30,7 @@ export const onboardingWorkflowV1 = onboardingWorkflow.v("1.0", {
 		await markUserVerified.start(run, { email: input.email });
 
 		// Sleep for 24 hours before sending tips
-		await run.sleep({ id: "onboarding-delay", days: 1 });
+		await run.sleep("onboarding-delay", { days: 1 });
 
 		// Send usage tips
 		await sendUsageTips.start(run, { email: input.email });
@@ -64,9 +64,9 @@ const result = await createUserProfile.start(run, {
 
 ```typescript
 // Sleep requires a unique id for memoization
-await run.sleep({ id: "daily-delay", days: 1 });
-await run.sleep({ id: "processing-delay", hours: 2, minutes: 30 });
-await run.sleep({ id: "short-pause", seconds: 30 });
+await run.sleep("daily-delay", { days: 1 });
+await run.sleep("processing-delay", { hours: 2, minutes: 30 });
+await run.sleep("short-pause", { seconds: 30 });
 ```
 
 ### Sleep Cancellation
@@ -81,7 +81,7 @@ await handle.wake(); // Wakes the workflow if sleeping
 The sleep returns a result indicating whether it was cancelled:
 
 ```typescript
-const { cancelled } = await run.sleep({ id: "wait-period", hours: 1 });
+const { cancelled } = await run.sleep("wait-period", { hours: 1 });
 if (cancelled) {
   // Handle early wake-up
 }
@@ -106,7 +106,7 @@ run.logger.debug("User created", { userId: result.userId });
 ### Delayed Trigger
 
 ```typescript
-export const morningWorkflowV1 = morningWorkflow.v("1.0", {
+export const morningWorkflowV1 = morningWorkflow.v("1.0.0", {
 	// ... workflow definition
 	opts: {
 		trigger: {
@@ -120,7 +120,7 @@ export const morningWorkflowV1 = morningWorkflow.v("1.0", {
 ### Retry Strategy
 
 ```typescript
-export const paymentWorkflowV1 = paymentWorkflow.v("1.0", {
+export const paymentWorkflowV1 = paymentWorkflow.v("1.0.0", {
 	// ... workflow definition
 	opts: {
 		retry: {
@@ -133,15 +133,18 @@ export const paymentWorkflowV1 = paymentWorkflow.v("1.0", {
 });
 ```
 
-### Idempotency Key
+### Reference ID
 
 ```typescript
-export const orderWorkflowV1 = orderWorkflow.v("1.0", {
-	// ... workflow definition
-	opts: {
-		idempotencyKey: "order-${orderId}",
-	},
-});
+// Assign a reference ID for tracking and lookup
+const handle = await orderWorkflowV1
+	.with().opt("reference.id", `order-${orderId}`)
+	.start(client, { orderId });
+
+// Configure conflict handling: "error" (default) or "return_existing"
+const handle = await orderWorkflowV1
+	.with().opt("reference", { id: `order-${orderId}`, onConflict: "return_existing" })
+	.start(client, { orderId });
 ```
 
 ## Running Workflows
@@ -153,7 +156,7 @@ import { client } from "@aikirun/client";
 import { onboardingWorkflowV1 } from "./workflows.ts";
 
 const aikiClient = await client({
-	url: "http://localhost:9090",
+	url: "http://localhost:9876",
 	redis: { host: "localhost", port: 6379 },
 });
 
@@ -180,7 +183,7 @@ With a worker:
 import { worker } from "@aikirun/worker";
 
 const aikiWorker = worker({
-	id: "my-worker",
+	name: "my-worker",
 	workflows: [onboardingWorkflowV1],
 	opts: {
 		maxConcurrentWorkflowRuns: 10,
@@ -199,7 +202,7 @@ interface WorkflowRunContext<Input, Output> {
 	id: WorkflowRunId; // Unique run ID
 	name: WorkflowName; // Workflow name
 	versionId: WorkflowVersionId; // Version ID
-	options: WorkflowOptions; // Execution options (trigger, retry, idempotencyKey)
+	options: WorkflowOptions; // Execution options (trigger, retry, reference)
 	handle: WorkflowRunHandle<Input, Output>; // Advanced state management
 	logger: Logger; // Logging (info, debug, warn, error, trace)
 	sleep(params: SleepParams): Promise<SleepResult>; // Durable sleep
@@ -210,7 +213,7 @@ Sleep parameters:
 - `id` (required): Unique identifier for memoization
 - Duration fields: `days`, `hours`, `minutes`, `seconds`, `milliseconds`
 
-Example: `run.sleep({ id: "my-sleep", days: 1, hours: 2 })`
+Example: `run.sleep("my-sleep", { days: 1, hours: 2 })`
 
 ## Error Handling
 
@@ -229,9 +232,11 @@ Failed workflows transition to `awaiting_retry` state and are automatically retr
 
 ### Expected Errors
 
-`WorkflowRunSuspendedError` is thrown when a workflow suspends (e.g., during sleep).
-This is expected behavior - the worker catches this error and the workflow resumes
-when the sleep completes. Do not catch this error in workflow code.
+These errors are thrown during normal workflow execution and should not be caught in workflow code:
+
+- `WorkflowRunSuspendedError` - Thrown when a workflow suspends (e.g., during sleep or awaiting events). The worker catches this error and the workflow resumes when the condition is met.
+
+- `WorkflowRunConflictError` - Thrown when another worker has already claimed the workflow execution. This prevents duplicate execution when workers race to process the same workflow.
 
 ## Best Practices
 

package/dist/index.d.ts

@@ -1,13 +1,15 @@
-import { WorkflowId, WorkflowVersionId } from '@aikirun/types/workflow';
+import { WorkflowName, WorkflowVersionId } from '@aikirun/types/workflow';
 import { Client, Logger, ApiClient } from '@aikirun/types/client';
 import { INTERNAL } from '@aikirun/types/symbols';
+import { Schema } from '@aikirun/types/validator';
 import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, WorkflowOptions } from '@aikirun/types/workflow-run';
-import { SleepParams, SleepResult } from '@aikirun/types/sleep';
+import { DurationObject, Duration } from '@aikirun/types/duration';
+import { SleepResult } from '@aikirun/types/sleep';
 import { EventSendOptions, EventWaitOptions, EventWaitState } from '@aikirun/types/event';
-import { DurationObject } from '@aikirun/types/duration';
-import { TaskPath } from '@aikirun/types/task';
-import { WorkflowRunStateRequest, TaskStateRequest } from '@aikirun/types/workflow-run-api';
-import { Serializable } from '@aikirun/types/error';
+import { Serializable } from '@aikirun/types/serializable';
+import { DistributiveOmit, RequireAtLeastOneProp } from '@aikirun/types/utils';
+import { TaskId } from '@aikirun/types/task';
+import { WorkflowRunStateRequest, WorkflowRunTransitionTaskStateRequestV1 } from '@aikirun/types/workflow-run-api';
 
 type NonEmptyArray<T> = [T, ...T[]];
 
@@ -90,7 +92,9 @@ interface WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition extends
     [INTERNAL]: {
         client: Client<AppContext>;
         transitionState: (state: WorkflowRunStateRequest) => Promise<void>;
-        transitionTaskState: (taskPath: TaskPath, taskState: TaskStateRequest) => Promise<void>;
+        transitionTaskState: (request: DistributiveOmit<WorkflowRunTransitionTaskStateRequestV1, "id" | "expectedRevision">) => Promise<{
+            taskId: TaskId;
+        }>;
         assertExecutionAllowed: () => void;
     };
 }
@@ -131,14 +135,11 @@ type WorkflowRunWaitResult<Status extends TerminalWorkflowRunStatus, Output, Tim
  * });
  * ```
  */
-declare function event(): EventDefinition<undefined>;
-declare function event<Data>(params?: EventParams<Data>): EventDefinition<Data>;
+declare function event(): EventDefinition<void>;
+declare function event<Data extends Serializable>(params?: EventParams<Data>): EventDefinition<Data>;
 interface EventParams<Data> {
     schema?: Schema<Data>;
 }
-interface Schema<Data> {
-    parse: (data: unknown) => Data;
-}
 interface EventDefinition<Data> {
     _type: Data;
     schema?: Schema<Data>;
@@ -156,24 +157,34 @@ type EventSenders<TEventsDefinition extends EventsDefinition> = {
     [K in keyof TEventsDefinition]: EventSender<EventData<TEventsDefinition[K]>>;
 };
 interface EventSender<Data> {
-    send: (...args: Data extends undefined ? [data?: Data, options?: EventSendOptions] : [data: Data, options?: EventSendOptions]) => Promise<void>;
+    with(): EventSenderBuilder<Data>;
+    send: (...args: Data extends void ? [] : [Data]) => Promise<void>;
+}
+interface EventSenderBuilder<Data> {
+    opt<Path extends PathFromObject<EventSendOptions>>(path: Path, value: TypeOfValueAtPath<EventSendOptions, Path>): EventSenderBuilder<Data>;
+    send: (...args: Data extends void ? [] : [Data]) => Promise<void>;
 }
 type EventMulticasters<TEventsDefinition extends EventsDefinition> = {
     [K in keyof TEventsDefinition]: EventMulticaster<EventData<TEventsDefinition[K]>>;
 };
 interface EventMulticaster<Data> {
-    send: <AppContext>(client: Client<AppContext>, runId: string | string[], data: Data, options?: EventSendOptions) => Promise<void>;
+    with(): EventMulticasterBuilder<Data>;
+    send: <AppContext>(client: Client<AppContext>, runId: 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>;
 }
 declare function createEventWaiters<TEventsDefinition extends EventsDefinition>(handle: WorkflowRunHandle<unknown, unknown, unknown, TEventsDefinition>, eventsDefinition: TEventsDefinition, logger: Logger): EventWaiters<TEventsDefinition>;
 declare function createEventSenders<TEventsDefinition extends EventsDefinition>(api: ApiClient, workflowRunId: string, eventsDefinition: TEventsDefinition, logger: Logger, onSend: (run: WorkflowRun<unknown, unknown>) => void): EventSenders<TEventsDefinition>;
 
 interface WorkflowRunContext<Input, AppContext, TEventDefinition extends EventsDefinition> {
     id: WorkflowRunId;
-    workflowId: WorkflowId;
-    workflowVersionId: WorkflowVersionId;
+    name: WorkflowName;
+    versionId: WorkflowVersionId;
     options: WorkflowOptions;
     logger: Logger;
-    sleep: (params: SleepParams) => Promise<SleepResult>;
+    sleep: (name: string, duration: Duration) => Promise<SleepResult>;
     events: EventWaiters<TEventDefinition>;
     [INTERNAL]: {
         handle: WorkflowRunHandle<Input, unknown, AppContext, TEventDefinition>;
@@ -229,45 +240,49 @@ interface ChildWorkflowRunWaitOptions<Timed extends boolean> {
 }
 
 interface WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> {
-    handler: (input: Input, run: Readonly<WorkflowRunContext<Input, AppContext, TEventsDefinition>>, context: AppContext) => Promise<Output>;
+    handler: (run: Readonly<WorkflowRunContext<Input, AppContext, TEventsDefinition>>, input: Input, context: AppContext) => Promise<Output>;
     events?: TEventsDefinition;
     opts?: WorkflowOptions;
-}
-interface WorkflowBuilder<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> {
-    opt<Path extends PathFromObject<WorkflowOptions>>(path: Path, value: TypeOfValueAtPath<WorkflowOptions, Path>): WorkflowBuilder<Input, Output, AppContext, TEventsDefinition>;
-    start: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>["start"];
-    startAsChild: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>["startAsChild"];
+    schema?: RequireAtLeastOneProp<{
+        input?: Schema<Input>;
+        output?: Schema<Output>;
+    }>;
 }
 interface WorkflowVersion<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> {
-    id: WorkflowId;
+    name: WorkflowName;
     versionId: WorkflowVersionId;
     events: EventMulticasters<TEventsDefinition>;
     with(): WorkflowBuilder<Input, Output, AppContext, TEventsDefinition>;
-    start: (client: Client<AppContext>, ...args: Input extends null ? [] : [Input]) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
-    startAsChild: <ParentInput, ParentEventsDefinition extends EventsDefinition>(parentRun: WorkflowRunContext<ParentInput, AppContext, ParentEventsDefinition>, ...args: Input extends null ? [] : [Input]) => Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    start: (client: Client<AppContext>, ...args: Input extends void ? [] : [Input]) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    startAsChild: <ParentInput, ParentEventsDefinition extends EventsDefinition>(parentRun: WorkflowRunContext<ParentInput, AppContext, ParentEventsDefinition>, ...args: Input extends void ? [] : [Input]) => Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
     getHandle: (client: Client<AppContext>, runId: WorkflowRunId) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
     [INTERNAL]: {
         eventsDefinition: TEventsDefinition;
-        handler: (input: Input, run: WorkflowRunContext<Input, AppContext, TEventsDefinition>, context: AppContext) => Promise<void>;
+        handler: (run: WorkflowRunContext<Input, AppContext, TEventsDefinition>, input: Input, context: AppContext) => Promise<void>;
     };
 }
+interface WorkflowBuilder<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> {
+    opt<Path extends PathFromObject<WorkflowOptions>>(path: Path, value: TypeOfValueAtPath<WorkflowOptions, Path>): WorkflowBuilder<Input, Output, AppContext, TEventsDefinition>;
+    start: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>["start"];
+    startAsChild: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>["startAsChild"];
+}
 declare class WorkflowVersionImpl<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> implements WorkflowVersion<Input, Output, AppContext, TEventsDefinition> {
-    readonly id: WorkflowId;
+    readonly name: WorkflowName;
     readonly versionId: WorkflowVersionId;
     private readonly params;
     readonly events: EventMulticasters<TEventsDefinition>;
     readonly [INTERNAL]: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>[typeof INTERNAL];
-    constructor(id: WorkflowId, versionId: WorkflowVersionId, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>);
+    constructor(name: WorkflowName, versionId: WorkflowVersionId, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>);
     with(): WorkflowBuilder<Input, Output, AppContext, TEventsDefinition>;
-    start(client: Client<AppContext>, ...args: Input extends null ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
-    startAsChild<ParentInput>(parentRun: WorkflowRunContext<ParentInput, AppContext, EventsDefinition>, ...args: Input extends null ? [] : [Input]): Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    start(client: Client<AppContext>, ...args: Input extends void ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    startAsChild(parentRun: WorkflowRunContext<unknown, AppContext, EventsDefinition>, ...args: Input extends void ? [] : [Input]): Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    private assertUniqueChildRunReferenceId;
     getHandle(client: Client<AppContext>, runId: WorkflowRunId): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
     private handler;
     private tryExecuteWorkflow;
     private assertRetryAllowed;
     private createFailedState;
     private createAwaitingRetryState;
-    private getPath;
 }
 
 declare function workflowRegistry(): WorkflowRegistry;
@@ -279,13 +294,10 @@ interface WorkflowRegistry {
     removeMany: (workflows: Workflow$1[]) => WorkflowRegistry;
     removeAll: () => WorkflowRegistry;
     getAll(): Workflow$1[];
-    get: (id: WorkflowId, versionId: WorkflowVersionId) => Workflow$1 | undefined;
+    get: (name: WorkflowName, versionId: WorkflowVersionId) => Workflow$1 | undefined;
 }
 
-interface SleeperOptions {
-    spinThresholdMs: number;
-}
-declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unknown>, logger: Logger, options: SleeperOptions): (params: SleepParams) => Promise<SleepResult>;
+declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unknown>, logger: Logger): (name: string, duration: Duration) => Promise<SleepResult>;
 
 /**
  * Defines a durable workflow with versioning and multiple task execution.
@@ -295,17 +307,17 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unkno
  * Multiple versions of a workflow can run simultaneously, allowing safe deployments.
  *
  * @param params - Workflow configuration
- * @param params.id - Unique workflow id used for identification and routing
+ * @param params.name - Unique workflow name used for identification and routing
  * @returns Workflow instance with version management methods
  *
  * @example
  * ```typescript
  * // Define a workflow
- * export const userOnboarding = workflow({ id: "user-onboarding" });
+ * export const userOnboarding = workflow({ name: "user-onboarding" });
  *
  * // Define version 1.0
- * export const userOnboardingV1 = userOnboarding.v("1.0", {
- *   async handler(input: { email: string }, run) {
+ * export const userOnboardingV1 = userOnboarding.v("1.0.0", {
+ *   async handler(run, input: { email: string }) {
  *     run.logger.info("Starting onboarding", { email: input.email });
  *
  *     // Execute tasks
@@ -313,7 +325,7 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unkno
  *     await createUserProfile.start(run, { email: input.email });
  *
  *     // Durable sleep
- *     await run.sleep({ id: "onboarding-delay", days: 1 });
+ *     await run.sleep("onboarding-delay", { days: 1 });
  *
  *     // More tasks
  *     await sendUsageTips.start(run, { email: input.email });
@@ -323,8 +335,8 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unkno
  * });
  *
  * // Deploy version 2.0 alongside 1.0 (no downtime)
- * export const userOnboardingV2 = userOnboarding.v("2.0", {
- *   async handler(input: { email: string; trial: boolean }, run) {
+ * export const userOnboardingV2 = userOnboarding.v("2.0.0", {
+ *   async handler(run, input: { email: string; trial: boolean }) {
  *     // Enhanced version with different logic
  *     // Existing v1.0 workflows continue with their version
  *     // New workflows use v2.0
@@ -336,10 +348,10 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unkno
  */
 declare function workflow(params: WorkflowParams): Workflow;
 interface WorkflowParams {
-    id: string;
+    name: string;
 }
 interface Workflow {
-    id: WorkflowId;
+    name: WorkflowName;
     v: <Input extends Serializable, Output extends Serializable, AppContext = null, TEventsDefinition extends EventsDefinition = Record<string, never>>(versionId: string, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>) => WorkflowVersion<Input, Output, AppContext, TEventsDefinition>;
     [INTERNAL]: {
         getAllVersions: () => WorkflowVersion<unknown, unknown, unknown>[];

package/dist/index.js

@@ -3,15 +3,15 @@ function workflowRegistry() {
   return new WorkflowRegistryImpl();
 }
 var WorkflowRegistryImpl = class {
-  workflowsById = /* @__PURE__ */ new Map();
+  workflowsByName = /* @__PURE__ */ new Map();
   add(workflow2) {
-    const workflows = this.workflowsById.get(workflow2.id);
+    const workflows = this.workflowsByName.get(workflow2.name);
     if (!workflows) {
-      this.workflowsById.set(workflow2.id, /* @__PURE__ */ new Map([[workflow2.versionId, workflow2]]));
+      this.workflowsByName.set(workflow2.name, /* @__PURE__ */ new Map([[workflow2.versionId, workflow2]]));
       return this;
     }
     if (workflows.has(workflow2.versionId)) {
-      throw new Error(`Workflow "${workflow2.id}/${workflow2.versionId}" is already registered`);
+      throw new Error(`Workflow "${workflow2.name}/${workflow2.versionId}" is already registered`);
     }
     workflows.set(workflow2.versionId, workflow2);
     return this;
@@ -23,7 +23,7 @@ var WorkflowRegistryImpl = class {
     return this;
   }
   remove(workflow2) {
-    const workflowVersinos = this.workflowsById.get(workflow2.id);
+    const workflowVersinos = this.workflowsByName.get(workflow2.name);
     if (workflowVersinos) {
       workflowVersinos.delete(workflow2.versionId);
     }
@@ -36,20 +36,20 @@ var WorkflowRegistryImpl = class {
     return this;
   }
   removeAll() {
-    this.workflowsById.clear();
+    this.workflowsByName.clear();
     return this;
   }
   getAll() {
     const workflows = [];
-    for (const workflowVersions of this.workflowsById.values()) {
+    for (const workflowVersions of this.workflowsByName.values()) {
       for (const workflow2 of workflowVersions.values()) {
         workflows.push(workflow2);
       }
     }
     return workflows;
   }
-  get(id, versionId) {
-    return this.workflowsById.get(id)?.get(versionId);
+  get(name, versionId) {
+    return this.workflowsByName.get(name)?.get(versionId);
   }
 };
 
@@ -77,6 +77,31 @@ function delay(ms, options) {
   });
 }
 
+// ../../lib/json/stable-stringify.ts
+function stableStringify(value) {
+  return stringifyValue(value);
+}
+function stringifyValue(value) {
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stringifyValue).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const pairs = [];
+  for (const key of keys) {
+    const keyValue = value[key];
+    if (keyValue !== void 0) {
+      pairs.push(`${JSON.stringify(key)}:${stringifyValue(keyValue)}`);
+    }
+  }
+  return `{${pairs.join(",")}}`;
+}
+
 // ../../lib/crypto/hash.ts
 async function sha256(input) {
   const data = new TextEncoder().encode(input);
@@ -84,6 +109,9 @@ async function sha256(input) {
   const hashArray = Array.from(new Uint8Array(hashBuffer));
   return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+async function hashInput(input) {
+  return sha256(stableStringify({ input }));
+}
 
 // ../../lib/duration/convert.ts
 var MS_PER_SECOND = 1e3;
@@ -144,25 +172,6 @@ function createSerializableError(error) {
   };
 }
 
-// ../../lib/json/stable-stringify.ts
-function stableStringify(value) {
-  if (value === null || value === void 0) {
-    return JSON.stringify(value);
-  }
-  if (typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
-  }
-  const keys = Object.keys(value).sort();
-  const pairs = keys.map((key) => {
-    const val = value[key];
-    return `${JSON.stringify(key)}:${stableStringify(val)}`;
-  });
-  return `{${pairs.join(",")}}`;
-}
-
 // ../../lib/object/overrider.ts
 function set(obj, path, value) {
   const keys = path.split(".");
@@ -281,6 +290,7 @@ function getRetryParams(attempts, strategy) {
 // run/event.ts
 import { INTERNAL } from "@aikirun/types/symbols";
 import {
+  WorkflowRunConflictError,
   WorkflowRunFailedError,
   WorkflowRunSuspendedError
 } from "@aikirun/types/workflow-run";
@@ -292,22 +302,22 @@ function event(params) {
 }
 function createEventWaiters(handle, eventsDefinition, logger) {
   const waiters = {};
-  for (const [eventId, eventDefinition] of Object.entries(eventsDefinition)) {
+  for (const [eventName, eventDefinition] of Object.entries(eventsDefinition)) {
     const waiter = createEventWaiter(
       handle,
-      eventId,
+      eventName,
       eventDefinition.schema,
-      logger.child({ "aiki.eventId": eventId })
+      logger.child({ "aiki.eventName": eventName })
     );
-    waiters[eventId] = waiter;
+    waiters[eventName] = waiter;
   }
   return waiters;
 }
-function createEventWaiter(handle, eventId, schema, logger) {
+function createEventWaiter(handle, eventName, schema, logger) {
   let nextEventIndex = 0;
   async function wait(options) {
     await handle.refresh();
-    const events = handle.run.eventsQueue[eventId]?.events ?? [];
+    const events = handle.run.eventsQueue[eventName]?.events ?? [];
     const event2 = events[nextEventIndex];
     if (event2) {
       nextEventIndex++;
@@ -320,11 +330,10 @@ function createEventWaiter(handle, eventId, schema, logger) {
         data = schema ? schema.parse(event2.data) : event2.data;
       } catch (error) {
         logger.error("Invalid event data", { data: event2.data, error });
-        const serializableError = createSerializableError(error);
         await handle[INTERNAL].transitionState({
           status: "failed",
           cause: "self",
-          error: serializableError
+          error: createSerializableError(error)
         });
         throw new WorkflowRunFailedError(handle.run.id, handle.run.attempts);
       }
@@ -332,75 +341,121 @@ function createEventWaiter(handle, eventId, schema, logger) {
       return { timeout: false, data };
     }
     const timeoutInMs = options?.timeout && toMilliseconds(options.timeout);
-    logger.info("Waiting for event", {
-      ...timeoutInMs !== void 0 ? { "aiki.timeoutInMs": timeoutInMs } : {}
-    });
-    await handle[INTERNAL].transitionState({
-      status: "awaiting_event",
-      eventId,
-      timeoutInMs
-    });
+    try {
+      await handle[INTERNAL].transitionState({
+        status: "awaiting_event",
+        eventName,
+        timeoutInMs
+      });
+      logger.info("Waiting for event", {
+        ...timeoutInMs !== void 0 ? { "aiki.timeoutInMs": timeoutInMs } : {}
+      });
+    } catch (error) {
+      if (error instanceof WorkflowRunConflictError) {
+        throw new WorkflowRunSuspendedError(handle.run.id);
+      }
+      throw error;
+    }
     throw new WorkflowRunSuspendedError(handle.run.id);
   }
   return { wait };
 }
 function createEventSenders(api, workflowRunId, eventsDefinition, logger, onSend) {
   const senders = {};
-  for (const [eventId, eventDefinition] of Object.entries(eventsDefinition)) {
+  for (const [eventName, eventDefinition] of Object.entries(eventsDefinition)) {
     const sender = createEventSender(
       api,
       workflowRunId,
-      eventId,
+      eventName,
       eventDefinition.schema,
-      logger.child({ "aiki.eventId": eventId }),
+      logger.child({ "aiki.eventName": eventName }),
       onSend
     );
-    senders[eventId] = sender;
+    senders[eventName] = sender;
   }
   return senders;
 }
-function createEventSender(api, workflowRunId, eventId, schema, logger, onSend) {
-  return {
-    async send(...args) {
-      const [data, options] = args;
-      if (schema) {
-        schema.parse(data);
-      }
-      logger.debug("Sending event", {
-        ...options?.idempotencyKey ? { "aiki.idempotencyKey": options.idempotencyKey } : {}
-      });
-      const { run } = await api.workflowRun.sendEventV1({
-        id: workflowRunId,
-        eventId,
-        data,
-        options
-      });
-      onSend(run);
+function createEventSender(api, workflowRunId, eventName, schema, logger, onSend, 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)
+  });
+  async function send(...args) {
+    const data = isNonEmptyArray(args) ? args[0] : void 0;
+    if (schema) {
+      schema.parse(data);
     }
+    const { run } = await api.workflowRun.sendEventV1({
+      id: workflowRunId,
+      eventName,
+      data,
+      options
+    });
+    onSend(run);
+    logger.info("Sent event to workflow", {
+      ...options?.reference ? { "aiki.referenceId": options.reference.id } : {}
+    });
+  }
+  return {
+    with: () => createBuilder(optsOverrider()),
+    send
   };
 }
-function createEventMulticasters(eventsDefinition) {
+function createEventMulticasters(workflowName, workflowVersionId, eventsDefinition) {
   const senders = {};
-  for (const [eventId, eventDefinition] of Object.entries(eventsDefinition)) {
-    const sender = createEventMulticaster(eventId, eventDefinition.schema);
-    senders[eventId] = sender;
+  for (const [eventName, eventDefinition] of Object.entries(eventsDefinition)) {
+    const sender = createEventMulticaster(
+      workflowName,
+      workflowVersionId,
+      eventName,
+      eventDefinition.schema
+    );
+    senders[eventName] = sender;
   }
   return senders;
 }
-function createEventMulticaster(eventId, schema) {
-  return {
-    async send(client, runId, data, options) {
-      if (schema) {
-        schema.parse(data);
-      }
-      const runIds = Array.isArray(runId) ? runId : [runId];
-      await client.api.workflowRun.multicastEventV1({
-        ids: runIds,
-        eventId,
-        data,
-        options
-      });
+function createEventMulticaster(workflowName, workflowVersionId, eventName, schema, options) {
+  const optsOverrider = objectOverrider(options ?? {});
+  const createBuilder = (optsBuilder) => ({
+    opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
+    send: (client, runId, ...args) => createEventMulticaster(workflowName, workflowVersionId, eventName, schema, optsBuilder.build()).send(
+      client,
+      runId,
+      ...args
+    )
+  });
+  async function send(client, runId, ...args) {
+    const data = isNonEmptyArray(args) ? args[0] : void 0;
+    if (schema) {
+      schema.parse(data);
     }
+    const runIds = Array.isArray(runId) ? runId : [runId];
+    if (!isNonEmptyArray(runIds)) {
+      return;
+    }
+    const logger = client.logger.child({
+      "aiki.workflowName": workflowName,
+      "aiki.workflowVersionId": workflowVersionId,
+      "aiki.eventName": eventName
+    });
+    await client.api.workflowRun.multicastEventV1({
+      ids: runIds,
+      eventName,
+      data,
+      options
+    });
+    logger.info("Multicasted event to workflows", {
+      "aiki.workflowName": workflowName,
+      "aiki.workflowVersionId": workflowVersionId,
+      "aiki.workflowRunIds": runIds,
+      "aiki.eventName": eventName,
+      ...options?.reference ? { "aiki.referenceId": options.reference.id } : {}
+    });
+  }
+  return {
+    with: () => createBuilder(optsOverrider()),
+    send
   };
 }
 
@@ -408,6 +463,7 @@ function createEventMulticaster(eventId, schema) {
 import { INTERNAL as INTERNAL2 } from "@aikirun/types/symbols";
 import {
   isTerminalWorkflowRunStatus,
+  WorkflowRunConflictError as WorkflowRunConflictError2,
   WorkflowRunNotExecutableError
 } from "@aikirun/types/workflow-run";
 async function workflowRunHandle(client, runOrId, eventsDefinition, logger) {
@@ -417,8 +473,8 @@ async function workflowRunHandle(client, runOrId, eventsDefinition, logger) {
     run,
     eventsDefinition ?? {},
     logger ?? client.logger.child({
-      "aiki.workflowId": run.workflowId,
-      "aiki.workflowVersionId": run.workflowVersionId,
+      "aiki.workflowName": run.name,
+      "aiki.workflowVersionId": run.versionId,
       "aiki.workflowRunId": run.id
     })
   );
@@ -506,43 +562,61 @@ var WorkflowRunHandleImpl = class {
     return { success: false, cause: maybeResult.state };
   }
   async cancel(reason) {
-    return this.transitionState({ status: "cancelled", reason });
+    await this.transitionState({ status: "cancelled", reason });
+    this.logger.info("Workflow cancelled");
   }
   async pause() {
-    return this.transitionState({ status: "paused" });
+    await this.transitionState({ status: "paused" });
+    this.logger.info("Workflow paused");
   }
   async resume() {
-    return this.transitionState({ status: "scheduled", scheduledInMs: 0, reason: "resume" });
+    await this.transitionState({ status: "scheduled", scheduledInMs: 0, reason: "resume" });
+    this.logger.info("Workflow resumed");
   }
   async awake() {
-    return this.transitionState({ status: "scheduled", scheduledInMs: 0, reason: "awake" });
+    await this.transitionState({ status: "scheduled", scheduledInMs: 0, reason: "awake_early" });
+    this.logger.info("Workflow awoken");
   }
   async transitionState(targetState) {
-    if (targetState.status === "scheduled" && (targetState.reason === "new" || targetState.reason === "resume" || targetState.reason === "awake") || targetState.status === "paused" || targetState.status === "cancelled") {
-      const { run: run2 } = await this.api.workflowRun.transitionStateV1({
-        type: "pessimistic",
+    try {
+      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({
+          type: "pessimistic",
+          id: this.run.id,
+          state: targetState
+        });
+        this._run = run2;
+        return;
+      }
+      const { run } = await this.api.workflowRun.transitionStateV1({
+        type: "optimistic",
         id: this.run.id,
-        state: targetState
+        state: targetState,
+        expectedRevision: this.run.revision
       });
-      this._run = run2;
-      return;
+      this._run = run;
+    } catch (error) {
+      if (isConflictError(error)) {
+        throw new WorkflowRunConflictError2(this.run.id);
+      }
+      throw error;
+    }
+  }
+  async transitionTaskState(request) {
+    try {
+      const { run, taskId } = await this.api.workflowRun.transitionTaskStateV1({
+        ...request,
+        id: this.run.id,
+        expectedRevision: this.run.revision
+      });
+      this._run = run;
+      return { taskId };
+    } catch (error) {
+      if (isConflictError(error)) {
+        throw new WorkflowRunConflictError2(this.run.id);
+      }
+      throw error;
     }
-    const { run } = await this.api.workflowRun.transitionStateV1({
-      type: "optimistic",
-      id: this.run.id,
-      state: targetState,
-      expectedRevision: this.run.revision
-    });
-    this._run = run;
-  }
-  async transitionTaskState(taskPath, taskState) {
-    const { run } = await this.api.workflowRun.transitionTaskStateV1({
-      id: this.run.id,
-      taskPath,
-      taskState,
-      expectedRevision: this.run.revision
-    });
-    this._run = run;
   }
   assertExecutionAllowed() {
     const status = this.run.state.status;
@@ -551,56 +625,92 @@ var WorkflowRunHandleImpl = class {
     }
   }
 };
+function isConflictError(error) {
+  return error != null && typeof error === "object" && "code" in error && error.code === "CONFLICT";
+}
 
 // run/sleeper.ts
 import { INTERNAL as INTERNAL3 } from "@aikirun/types/symbols";
-import { WorkflowRunSuspendedError as WorkflowRunSuspendedError2 } from "@aikirun/types/workflow-run";
+import { WorkflowRunConflictError as WorkflowRunConflictError3, WorkflowRunSuspendedError as WorkflowRunSuspendedError2 } from "@aikirun/types/workflow-run";
 var MAX_SLEEP_YEARS = 10;
 var MAX_SLEEP_MS = MAX_SLEEP_YEARS * 365 * 24 * 60 * 60 * 1e3;
-function createSleeper(handle, logger, options) {
-  return async (params) => {
-    const { id: sleepId, ...durationFields } = params;
-    const durationMs = toMilliseconds(durationFields);
+function createSleeper(handle, logger) {
+  const nextSleepIndexByName = {};
+  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 sleepPath = `${sleepId}/${durationMs}`;
-    const sleepState = handle.run.sleepsState[sleepPath] ?? { status: "none" };
-    if (sleepState.status === "completed") {
-      logger.debug("Sleep completed", {
-        "aiki.sleepId": sleepId,
-        "aiki.durationMs": durationMs
+    const nextSleepIndex = nextSleepIndexByName[sleepName] ?? 0;
+    const sleepQueue = handle.run.sleepsQueue[sleepName] ?? { sleeps: [] };
+    const sleepState = sleepQueue.sleeps[nextSleepIndex];
+    if (!sleepState) {
+      try {
+        await handle[INTERNAL3].transitionState({ status: "sleeping", sleepName, durationMs });
+        logger.info("Sleeping", {
+          "aiki.sleepName": sleepName,
+          "aiki.durationMs": durationMs
+        });
+      } catch (error) {
+        if (error instanceof WorkflowRunConflictError3) {
+          throw new WorkflowRunSuspendedError2(handle.run.id);
+        }
+        throw error;
+      }
+      throw new WorkflowRunSuspendedError2(handle.run.id);
+    }
+    if (sleepState.status === "sleeping") {
+      logger.debug("Already sleeping", {
+        "aiki.sleepName": sleepName,
+        "aiki.awakeAt": sleepState.awakeAt
       });
-      return { cancelled: false };
+      throw new WorkflowRunSuspendedError2(handle.run.id);
     }
+    sleepState.status;
+    nextSleepIndexByName[sleepName] = nextSleepIndex + 1;
     if (sleepState.status === "cancelled") {
       logger.debug("Sleep cancelled", {
-        "aiki.sleepId": sleepId,
-        "aiki.durationMs": durationMs
+        "aiki.sleepName": sleepName,
+        "aiki.cancelledAt": sleepState.cancelledAt
       });
       return { cancelled: true };
     }
-    if (sleepState.status === "sleeping") {
-      logger.debug("Already sleeping", {
-        "aiki.sleepId": sleepId,
-        "aiki.durationMs": durationMs
+    if (durationMs === sleepState.durationMs) {
+      logger.debug("Sleep completed", {
+        "aiki.sleepName": sleepName,
+        "aiki.durationMs": durationMs,
+        "aiki.completedAt": sleepState.completedAt
       });
-      throw new WorkflowRunSuspendedError2(handle.run.id);
+      return { cancelled: false };
     }
-    sleepState;
-    if (durationMs <= options.spinThresholdMs) {
-      logger.debug("Spinning for short sleep", {
-        "aiki.sleepId": sleepId,
-        "aiki.durationMs": durationMs
+    if (durationMs > sleepState.durationMs) {
+      logger.warn("Higher sleep duration encountered during replay. Sleeping for remaining duration", {
+        "aiki.sleepName": sleepName,
+        "aiki.historicDurationMs": sleepState.durationMs,
+        "aiki.latestDurationMs": durationMs
+      });
+      durationMs -= sleepState.durationMs;
+    } else {
+      logger.warn("Lower sleep duration encountered during replay. Already slept enough", {
+        "aiki.sleepName": sleepName,
+        "aiki.historicDurationMs": sleepState.durationMs,
+        "aiki.latestDurationMs": durationMs
       });
-      await delay(durationMs);
       return { cancelled: false };
     }
-    await handle[INTERNAL3].transitionState({ status: "sleeping", sleepPath, durationMs });
-    logger.info("Workflow going to sleep", {
-      "aiki.sleepId": sleepId,
-      "aiki.durationMs": durationMs
-    });
+    try {
+      await handle[INTERNAL3].transitionState({ status: "sleeping", sleepName, durationMs });
+      logger.info("Sleeping", {
+        "aiki.sleepName": sleepName,
+        "aiki.durationMs": durationMs
+      });
+    } catch (error) {
+      if (error instanceof WorkflowRunConflictError3) {
+        throw new WorkflowRunSuspendedError2(handle.run.id);
+      }
+      throw error;
+    }
     throw new WorkflowRunSuspendedError2(handle.run.id);
   };
 }
@@ -608,10 +718,16 @@ function createSleeper(handle, logger, options) {
 // workflow.ts
 import { INTERNAL as INTERNAL6 } from "@aikirun/types/symbols";
 
+// ../../lib/path/index.ts
+function getWorkflowRunPath(name, versionId, referenceId) {
+  return `${name}/${versionId}/${referenceId}`;
+}
+
 // workflow-version.ts
 import { INTERNAL as INTERNAL5 } from "@aikirun/types/symbols";
 import { TaskFailedError } from "@aikirun/types/task";
 import {
+  WorkflowRunConflictError as WorkflowRunConflictError5,
   WorkflowRunFailedError as WorkflowRunFailedError2,
   WorkflowRunSuspendedError as WorkflowRunSuspendedError4
 } from "@aikirun/types/workflow-run";
@@ -620,15 +736,16 @@ import {
 import { INTERNAL as INTERNAL4 } from "@aikirun/types/symbols";
 import {
   isTerminalWorkflowRunStatus as isTerminalWorkflowRunStatus2,
+  WorkflowRunConflictError as WorkflowRunConflictError4,
   WorkflowRunSuspendedError as WorkflowRunSuspendedError3
 } from "@aikirun/types/workflow-run";
-async function childWorkflowRunHandle(client, path, run, parentRun, logger, eventsDefinition) {
+async function childWorkflowRunHandle(client, run, parentRun, logger, eventsDefinition) {
   const handle = await workflowRunHandle(client, run, eventsDefinition, logger);
   return {
     run: handle.run,
     events: handle.events,
     refresh: handle.refresh.bind(handle),
-    waitForStatus: createStatusWaiter(path, handle, parentRun, logger),
+    waitForStatus: createStatusWaiter(handle, parentRun, logger),
     cancel: handle.cancel.bind(handle),
     pause: handle.pause.bind(handle),
     resume: handle.resume.bind(handle),
@@ -636,16 +753,18 @@ async function childWorkflowRunHandle(client, path, run, parentRun, logger, even
     [INTERNAL4]: handle[INTERNAL4]
   };
 }
-function createStatusWaiter(path, handle, parentRun, logger) {
+function createStatusWaiter(handle, parentRun, logger) {
   let nextWaitIndex = 0;
   async function waitForStatus(expectedStatus, options) {
     const parentRunHandle = parentRun[INTERNAL4].handle;
-    const waitResults = parentRunHandle.run.childWorkflowRuns[path]?.statusWaitResults ?? [];
+    const waitResults = parentRunHandle.run.childWorkflowRuns[handle.run.path]?.statusWaitResults ?? [];
     const waitResult = waitResults[nextWaitIndex];
     if (waitResult) {
       nextWaitIndex++;
       if (waitResult.status === "timeout") {
-        logger.debug("Timed out waiting for child workflow status", { "aiki.expectedStatus": expectedStatus });
+        logger.debug("Timed out waiting for child workflow status", {
+          "aiki.childWorkflowExpectedStatus": expectedStatus
+        });
         return {
           success: false,
           cause: "timeout"
@@ -658,7 +777,9 @@ function createStatusWaiter(path, handle, parentRun, logger) {
         };
       }
       if (isTerminalWorkflowRunStatus2(waitResult.childWorkflowRunState.status)) {
-        logger.debug("Child workflow run reached termnial state");
+        logger.debug("Child workflow run reached termnial state", {
+          "aiki.childWorkflowTerminalStatus": waitResult.childWorkflowRunState.status
+        });
         return {
           success: false,
           cause: "run_terminated"
@@ -673,19 +794,32 @@ function createStatusWaiter(path, handle, parentRun, logger) {
       };
     }
     if (isTerminalWorkflowRunStatus2(state.status)) {
-      logger.debug("Child workflow run reached termnial state");
+      logger.debug("Child workflow run reached termnial state", {
+        "aiki.childWorkflowTerminalStatus": state.status
+      });
       return {
         success: false,
         cause: "run_terminated"
       };
     }
     const timeoutInMs = options?.timeout && toMilliseconds(options.timeout);
-    await parentRunHandle[INTERNAL4].transitionState({
-      status: "awaiting_child_workflow",
-      childWorkflowRunPath: path,
-      childWorkflowRunStatus: expectedStatus,
-      timeoutInMs
-    });
+    try {
+      await parentRunHandle[INTERNAL4].transitionState({
+        status: "awaiting_child_workflow",
+        childWorkflowRunId: handle.run.id,
+        childWorkflowRunStatus: expectedStatus,
+        timeoutInMs
+      });
+      logger.info("Waiting for child Workflow", {
+        "aiki.childWorkflowExpectedStatus": expectedStatus,
+        ...timeoutInMs !== void 0 ? { "aiki.timeoutInMs": timeoutInMs } : {}
+      });
+    } catch (error) {
+      if (error instanceof WorkflowRunConflictError4) {
+        throw new WorkflowRunSuspendedError3(parentRun.id);
+      }
+      throw error;
+    }
     throw new WorkflowRunSuspendedError3(parentRun.id);
   }
   return waitForStatus;
@@ -693,12 +827,12 @@ function createStatusWaiter(path, handle, parentRun, logger) {
 
 // workflow-version.ts
 var WorkflowVersionImpl = class _WorkflowVersionImpl {
-  constructor(id, versionId, params) {
-    this.id = id;
+  constructor(name, versionId, params) {
+    this.name = name;
     this.versionId = versionId;
     this.params = params;
     const eventsDefinition = this.params.events ?? {};
-    this.events = createEventMulticasters(eventsDefinition);
+    this.events = createEventMulticasters(this.name, this.versionId, eventsDefinition);
     this[INTERNAL5] = {
       eventsDefinition,
       handler: this.handler.bind(this)
@@ -711,11 +845,11 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
     const createBuilder = (optsBuilder) => {
       return {
         opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
-        start: (client, ...args) => new _WorkflowVersionImpl(this.id, this.versionId, {
+        start: (client, ...args) => new _WorkflowVersionImpl(this.name, this.versionId, {
           ...this.params,
           opts: optsBuilder.build()
         }).start(client, ...args),
-        startAsChild: (parentRun, ...args) => new _WorkflowVersionImpl(this.id, this.versionId, {
+        startAsChild: (parentRun, ...args) => new _WorkflowVersionImpl(this.name, this.versionId, {
           ...this.params,
           opts: optsBuilder.build()
         }).startAsChild(parentRun, ...args)
@@ -724,67 +858,118 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
     return createBuilder(optsOverrider());
   }
   async start(client, ...args) {
+    const inputRaw = isNonEmptyArray(args) ? args[0] : void 0;
+    const input = this.params.schema?.input ? this.params.schema.input.parse(inputRaw) : inputRaw;
     const { run } = await client.api.workflowRun.createV1({
-      workflowId: this.id,
-      workflowVersionId: this.versionId,
-      input: isNonEmptyArray(args) ? args[0] : null,
+      name: this.name,
+      versionId: this.versionId,
+      input,
       options: this.params.opts
     });
+    client.logger.info("Created workflow", {
+      "aiki.workflowName": this.name,
+      "aiki.workflowVersionId": this.versionId,
+      "aiki.workflowRunId": run.id
+    });
     return workflowRunHandle(client, run, this[INTERNAL5].eventsDefinition);
   }
   async startAsChild(parentRun, ...args) {
     const parentRunHandle = parentRun[INTERNAL5].handle;
     parentRunHandle[INTERNAL5].assertExecutionAllowed();
     const { client } = parentRunHandle[INTERNAL5];
-    const input = isNonEmptyArray(args) ? args[0] : null;
-    const childRunPath = await this.getPath(input);
-    const existingChildRunId = parentRunHandle.run.childWorkflowRuns[childRunPath]?.id;
-    if (existingChildRunId) {
-      const { run: existingChildRun } = await client.api.workflowRun.getByIdV1({ id: existingChildRunId });
+    const inputRaw = isNonEmptyArray(args) ? args[0] : void 0;
+    let input = inputRaw;
+    if (this.params.schema?.input) {
+      try {
+        input = this.params.schema.input.parse(inputRaw);
+      } catch (error) {
+        await parentRunHandle[INTERNAL5].transitionState({
+          status: "failed",
+          cause: "self",
+          error: createSerializableError(error)
+        });
+        throw new WorkflowRunFailedError2(parentRun.id, parentRunHandle.run.attempts);
+      }
+    }
+    const inputHash = await hashInput(input);
+    const reference = this.params.opts?.reference;
+    const path = getWorkflowRunPath(this.name, this.versionId, reference?.id ?? inputHash);
+    const existingRunInfo = parentRunHandle.run.childWorkflowRuns[path];
+    if (existingRunInfo) {
+      await this.assertUniqueChildRunReferenceId(
+        parentRunHandle,
+        existingRunInfo,
+        inputHash,
+        reference,
+        parentRun.logger
+      );
+      const { run: existingRun } = await client.api.workflowRun.getByIdV1({ id: existingRunInfo.id });
       const logger2 = parentRun.logger.child({
-        "aiki.childWorkflowId": existingChildRun.workflowId,
-        "aiki.childWorkflowVersionId": existingChildRun.workflowVersionId,
-        "aiki.childWorkflowRunId": existingChildRun.id
+        "aiki.childWorkflowName": existingRun.name,
+        "aiki.childWorkflowVersionId": existingRun.versionId,
+        "aiki.childWorkflowRunId": existingRun.id
       });
       return childWorkflowRunHandle(
         client,
-        childRunPath,
-        existingChildRun,
+        existingRun,
         parentRun,
         logger2,
         this[INTERNAL5].eventsDefinition
       );
     }
-    const { run: newChildRun } = await client.api.workflowRun.createV1({
-      workflowId: this.id,
-      workflowVersionId: this.versionId,
+    const { run: newRun } = await client.api.workflowRun.createV1({
+      name: this.name,
+      versionId: this.versionId,
       input,
-      path: childRunPath,
       parentWorkflowRunId: parentRun.id,
-      options: {
-        ...this.params.opts,
-        idempotencyKey: childRunPath
-      }
+      options: this.params.opts
     });
-    parentRunHandle.run.childWorkflowRuns[childRunPath] = { id: newChildRun.id, statusWaitResults: [] };
+    parentRunHandle.run.childWorkflowRuns[path] = {
+      id: newRun.id,
+      inputHash,
+      statusWaitResults: []
+    };
     const logger = parentRun.logger.child({
-      "aiki.childWorkflowId": newChildRun.workflowId,
-      "aiki.childWorkflowVersionId": newChildRun.workflowVersionId,
-      "aiki.childWorkflowRunId": newChildRun.id
+      "aiki.childWorkflowName": newRun.name,
+      "aiki.childWorkflowVersionId": newRun.versionId,
+      "aiki.childWorkflowRunId": newRun.id
     });
+    logger.info("Created child workflow");
     return childWorkflowRunHandle(
       client,
-      childRunPath,
-      newChildRun,
+      newRun,
       parentRun,
       logger,
       this[INTERNAL5].eventsDefinition
     );
   }
+  async assertUniqueChildRunReferenceId(parentRunHandle, existingRunInfo, inputHash, reference, logger) {
+    if (existingRunInfo.inputHash !== inputHash && reference) {
+      const onConflict = reference.onConflict ?? "error";
+      if (onConflict !== "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 getHandle(client, runId) {
     return workflowRunHandle(client, runId, this[INTERNAL5].eventsDefinition);
   }
-  async handler(input, run, context) {
+  async handler(run, input, context) {
     const { logger } = run;
     const { handle } = run[INTERNAL5];
     handle[INTERNAL5].assertExecutionAllowed();
@@ -802,9 +987,24 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
   async tryExecuteWorkflow(input, run, context, retryStrategy) {
     while (true) {
       try {
-        return await this.params.handler(input, run, context);
+        const outputRaw = await this.params.handler(run, input, context);
+        let output = outputRaw;
+        if (this.params.schema?.output) {
+          try {
+            output = this.params.schema.output.parse(outputRaw);
+          } catch (error) {
+            const { handle } = run[INTERNAL5];
+            await handle[INTERNAL5].transitionState({
+              status: "failed",
+              cause: "self",
+              error: createSerializableError(error)
+            });
+            throw new WorkflowRunFailedError2(run.id, handle.run.attempts);
+          }
+        }
+        return output;
       } catch (error) {
-        if (error instanceof WorkflowRunSuspendedError4 || error instanceof WorkflowRunFailedError2) {
+        if (error instanceof WorkflowRunSuspendedError4 || error instanceof WorkflowRunFailedError2 || error instanceof WorkflowRunConflictError5) {
           throw error;
         }
         const { handle } = run[INTERNAL5];
@@ -844,11 +1044,10 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
     if (!retryParams.retriesLeft) {
       logger.error("Workflow retry not allowed", { "aiki.attempts": attempts });
       const error = new WorkflowRunFailedError2(id, attempts);
-      const serializableError = createSerializableError(error);
       await handle[INTERNAL5].transitionState({
         status: "failed",
         cause: "self",
-        error: serializableError
+        error: createSerializableError(error)
       });
       throw error;
     }
@@ -858,14 +1057,13 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       return {
         status: "failed",
         cause: "task",
-        taskPath: error.taskPath
+        taskId: error.taskId
       };
     }
-    const serializableError = createSerializableError(error);
     return {
       status: "failed",
       cause: "self",
-      error: serializableError
+      error: createSerializableError(error)
     };
   }
   createAwaitingRetryState(error, nextAttemptInMs) {
@@ -874,22 +1072,16 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
         status: "awaiting_retry",
         cause: "task",
         nextAttemptInMs,
-        taskPath: error.taskPath
+        taskId: error.taskId
       };
     }
-    const serializableError = createSerializableError(error);
     return {
       status: "awaiting_retry",
       cause: "self",
       nextAttemptInMs,
-      error: serializableError
+      error: createSerializableError(error)
     };
   }
-  async getPath(input) {
-    const inputHash = await sha256(stableStringify(input));
-    const path = this.params.opts?.idempotencyKey ? `${this.id}/${this.versionId}/${inputHash}/${this.params.opts.idempotencyKey}` : `${this.id}/${this.versionId}/${inputHash}`;
-    return path;
-  }
 };
 
 // workflow.ts
@@ -897,11 +1089,11 @@ function workflow(params) {
   return new WorkflowImpl(params);
 }
 var WorkflowImpl = class {
-  id;
+  name;
   [INTERNAL6];
   workflowVersions = /* @__PURE__ */ new Map();
   constructor(params) {
-    this.id = params.id;
+    this.name = params.name;
     this[INTERNAL6] = {
       getAllVersions: this.getAllVersions.bind(this),
       getVersion: this.getVersion.bind(this)
@@ -909,9 +1101,9 @@ var WorkflowImpl = class {
   }
   v(versionId, params) {
     if (this.workflowVersions.has(versionId)) {
-      throw new Error(`Workflow "${this.id}/${versionId}" already exists`);
+      throw new Error(`Workflow "${this.name}/${versionId}" already exists`);
     }
-    const workflowVersion = new WorkflowVersionImpl(this.id, versionId, params);
+    const workflowVersion = new WorkflowVersionImpl(this.name, versionId, params);
     this.workflowVersions.set(
       versionId,
       workflowVersion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/workflow",
-	"version": "0.7.0",
+	"version": "0.8.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.7.0"
+		"@aikirun/types": "0.8.0"
 	},
 	"publishConfig": {
 		"access": "public"