@aikirun/workflow 0.6.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 { WorkflowRun, WorkflowRunStatus, WorkflowRunStateCompleted, WorkflowRunStateInComplete, WorkflowRunState, WorkflowRunId, WorkflowOptions } from '@aikirun/types/workflow-run';
-import { SleepParams, SleepResult } from '@aikirun/types/sleep';
-import { DurationObject } from '@aikirun/types/duration';
+import { Schema } from '@aikirun/types/validator';
+import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, WorkflowOptions } from '@aikirun/types/workflow-run';
+import { DurationObject, Duration } from '@aikirun/types/duration';
+import { SleepResult } from '@aikirun/types/sleep';
 import { EventSendOptions, EventWaitOptions, EventWaitState } from '@aikirun/types/event';
-import { TaskPath } from '@aikirun/types/task';
-import { WorkflowRunStateRequest, TaskStateRequest } from '@aikirun/types/workflow-run-api';
-import { SerializableInput } 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[]];
 
@@ -28,46 +30,89 @@ type PathFromObjectInternal<T, IncludeArrayKeys extends boolean> = And<[
 type ExtractObjectType<T> = T extends object ? T : never;
 type TypeOfValueAtPath<T extends object, Path extends PathFromObject<T>> = Path extends keyof T ? T[Path] : Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? undefined extends T[First] ? Rest extends PathFromObject<ExtractObjectType<T[First]>> ? TypeOfValueAtPath<ExtractObjectType<T[First]>, Rest> | undefined : never : Rest extends PathFromObject<ExtractObjectType<T[First]>> ? TypeOfValueAtPath<ExtractObjectType<T[First]>, Rest> : never : never : never;
 
-declare function workflowRunHandle<Input, Output, TEventsDefinition extends EventsDefinition>(client: Client, id: WorkflowRunId, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
-declare function workflowRunHandle<Input, Output, TEventsDefinition extends EventsDefinition>(client: Client, run: WorkflowRun<Input, Output>, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
-interface WorkflowRunHandle<Input, Output, TEventsDefinition extends EventsDefinition = EventsDefinition> {
+declare function workflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition>(client: Client<AppContext>, id: WorkflowRunId, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+declare function workflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition>(client: Client<AppContext>, run: WorkflowRun<Input, Output>, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+interface WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> {
     run: Readonly<WorkflowRun<Input, Output>>;
     events: EventSenders<TEventsDefinition>;
     refresh: () => Promise<void>;
-    wait<S extends WorkflowRunStatus>(condition: {
-        type: "status";
-        status: S;
-    }, options: WorkflowRunWaitOptions): Promise<{
-        success: false;
-        cause: "timeout" | "aborted";
-    } | {
-        success: true;
-        state: S extends "completed" ? WorkflowRunStateCompleted<Output> : WorkflowRunStateInComplete;
-    }>;
-    wait(condition: {
-        type: "event";
-        event: string;
-    }, options: WorkflowRunWaitOptions): Promise<{
-        success: false;
-        cause: "timeout" | "aborted";
-    } | {
-        success: true;
-        state: WorkflowRunState<Output>;
-    }>;
+    /**
+     *  Waits for the child workflow run to reach a terminal status by polling.
+     *
+     * Returns a result object:
+     * - `{ success: true, state }` - workflow reached the expected status
+     * - `{ success: false, cause }` - workflow did not reach status
+     *
+     * Possible failure causes:
+     * - `"run_terminated"` - workflow reached a terminal state other than expected
+     * - `"timeout"` - timeout elapsed (only when timeout option provided)
+     * - `"aborted"` - abort signal triggered (only when abortSignal option provided)
+     *
+     * @param status - The target status to wait for
+     * @param options - Optional configuration for polling interval, timeout, and abort signal
+     *
+     * @example
+     * // Wait indefinitely until completed or the workflow reaches another terminal state
+     * const result = await handle.waitForStatus("completed");
+     * if (result.success) {
+     *   console.log(result.state.output);
+     * } else {
+     *   console.log(`Workflow terminated: ${result.cause}`);
+     * }
+     *
+     * @example
+     * // Wait with a timeout
+     * const result = await handle.waitForStatus("completed", {
+     *   timeout: { seconds: 30 }
+     * });
+     * if (result.success) {
+     *   console.log(result.state.output);
+     * } else if (result.cause === "timeout") {
+     *   console.log("Timed out waiting for completion");
+     * }
+     *
+     * @example
+     * // Wait with an abort signal
+     * const controller = new AbortController();
+     * const result = await handle.waitForStatus("completed", {
+     *   abortSignal: controller.signal
+     * });
+     * if (!result.success) {
+     *   console.log(`Wait ended: ${result.cause}`);
+     * }
+     */
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options?: WorkflowRunWaitOptions<false, false>): Promise<WorkflowRunWaitResult<Status, Output, false, false>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: WorkflowRunWaitOptions<true, false>): Promise<WorkflowRunWaitResult<Status, Output, true, false>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: WorkflowRunWaitOptions<false, true>): Promise<WorkflowRunWaitResult<Status, Output, false, true>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: WorkflowRunWaitOptions<true, true>): Promise<WorkflowRunWaitResult<Status, Output, true, true>>;
     cancel: (reason?: string) => Promise<void>;
     pause: () => Promise<void>;
     resume: () => Promise<void>;
+    awake: () => Promise<void>;
     [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;
     };
 }
-interface WorkflowRunWaitOptions {
-    maxDurationMs: number;
-    pollIntervalMs?: number;
-    abortSignal?: AbortSignal;
+interface WorkflowRunWaitOptions<Timed extends boolean, Abortable extends boolean> {
+    interval?: DurationObject;
+    timeout?: Timed extends true ? DurationObject : never;
+    abortSignal?: Abortable extends true ? AbortSignal : never;
 }
+type WorkflowRunWaitResultSuccess<Status extends TerminalWorkflowRunStatus, Output> = Extract<WorkflowRunState<Output>, {
+    status: Status;
+}>;
+type WorkflowRunWaitResult<Status extends TerminalWorkflowRunStatus, Output, Timed extends boolean, Abortable extends boolean> = {
+    success: false;
+    cause: "run_terminated" | (Timed extends true ? "timeout" : never) | (Abortable extends true ? "aborted" : never);
+} | {
+    success: true;
+    state: WorkflowRunWaitResultSuccess<Status, Output>;
+};
 
 /**
  * Defines an event type that can be sent to and waited for by workflows.
@@ -90,13 +135,11 @@ interface WorkflowRunWaitOptions {
  * });
  * ```
  */
-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>;
@@ -107,63 +150,134 @@ type EventWaiters<TEventsDefinition extends EventsDefinition> = {
     [K in keyof TEventsDefinition]: EventWaiter<EventData<TEventsDefinition[K]>>;
 };
 interface EventWaiter<Data> {
-    wait(options?: EventWaitOptions<undefined>): Promise<EventWaitState<Data, false>>;
-    wait(options: EventWaitOptions<DurationObject>): Promise<EventWaitState<Data, true>>;
+    wait(options?: EventWaitOptions<false>): Promise<EventWaitState<Data, false>>;
+    wait(options: EventWaitOptions<true>): Promise<EventWaitState<Data, true>>;
 }
 type EventSenders<TEventsDefinition extends EventsDefinition> = {
     [K in keyof TEventsDefinition]: EventSender<EventData<TEventsDefinition[K]>>;
 };
 interface EventSender<Data> {
-    send: (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>;
 }
-declare function createEventWaiters<TEventsDefinition extends EventsDefinition>(handle: WorkflowRunHandle<unknown, unknown, TEventsDefinition>, eventsDefinition: TEventsDefinition, logger: Logger): EventWaiters<TEventsDefinition>;
+type EventMulticasters<TEventsDefinition extends EventsDefinition> = {
+    [K in keyof TEventsDefinition]: EventMulticaster<EventData<TEventsDefinition[K]>>;
+};
+interface EventMulticaster<Data> {
+    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, Output, TEventDefinition extends EventsDefinition> {
+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, Output, TEventDefinition>;
+        handle: WorkflowRunHandle<Input, unknown, AppContext, TEventDefinition>;
         options: {
             spinThresholdMs: number;
         };
     };
 }
 
+type ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> = Omit<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>, "waitForStatus"> & {
+    /**
+     * Waits for the child workflow run to reach a terminal status.
+     *
+     * This method suspends the parent workflow until the child reaches the expected terminal status
+     * or the optional timeout elapses.
+     *
+     * When the parent resumes, the result is deterministically replayed from stored wait results.
+     *
+     * Returns a result object:
+     * - `{ success: true, state }` - child reached the expected status
+     * - `{ success: false, cause }` - child did not reach status
+     *
+     * Possible failure causes:
+     * - `"run_terminated"` - child reached a different terminal state than expected
+     * - `"timeout"` - timeout elapsed (only when timeout option provided)
+     *
+     * @param status - The target terminal status to wait for
+     * @param options - Optional configuration with timeout
+     *
+     * @example
+     * // Wait indefinitely for child to complete
+     * const result = await childHandle.waitForStatus("completed");
+     * if (result.success) {
+     *   console.log(result.state.output);
+     * } else {
+     *   console.log(`Child terminated: ${result.cause}`);
+     * }
+     *
+     * @example
+     * // Wait with a timeout
+     * const result = await childHandle.waitForStatus("completed", {
+     *   timeout: { minutes: 5 }
+     * });
+     * if (!result.success && result.cause === "timeout") {
+     *   console.log("Child workflow took too long");
+     * }
+     */
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options?: ChildWorkflowRunWaitOptions<false>): Promise<WorkflowRunWaitResult<Status, Output, false, false>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: ChildWorkflowRunWaitOptions<true>): Promise<WorkflowRunWaitResult<Status, Output, true, false>>;
+};
+interface ChildWorkflowRunWaitOptions<Timed extends boolean> {
+    timeout?: Timed extends true ? DurationObject : never;
+}
+
 interface WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> {
+    handler: (run: Readonly<WorkflowRunContext<Input, AppContext, TEventsDefinition>>, input: Input, context: AppContext) => Promise<Output>;
     events?: TEventsDefinition;
     opts?: WorkflowOptions;
-    handler: (input: Input, run: Readonly<WorkflowRunContext<Input, Output, TEventsDefinition>>, context: AppContext) => Promise<Output>;
-}
-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"];
+    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, TEventsDefinition>>;
-    getHandle: (client: Client<AppContext>, runId: WorkflowRunId) => Promise<WorkflowRunHandle<Input, Output, 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, Output, 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, TEventsDefinition>>;
-    getHandle(client: Client<AppContext>, runId: WorkflowRunId): Promise<WorkflowRunHandle<Input, Output, 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;
@@ -180,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>, 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.
@@ -196,17 +307,17 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown>, logg
  * 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
@@ -214,7 +325,7 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown>, logg
  *     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 });
@@ -224,8 +335,8 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown>, logg
  * });
  *
  * // 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
@@ -237,15 +348,15 @@ declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown>, logg
  */
 declare function workflow(params: WorkflowParams): Workflow;
 interface WorkflowParams {
-    id: string;
+    name: string;
 }
 interface Workflow {
-    id: WorkflowId;
-    v: <Input extends SerializableInput = null, Output = void, AppContext = null, TEventsDefinition extends EventsDefinition = Record<string, never>>(versionId: string, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>) => WorkflowVersion<Input, Output, AppContext, TEventsDefinition>;
+    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>[];
         getVersion: (versionId: WorkflowVersionId) => WorkflowVersion<unknown, unknown, unknown> | undefined;
     };
 }
 
-export { type EventDefinition, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createEventSenders, createEventWaiters, createSleeper, event, workflow, workflowRegistry, workflowRunHandle };
+export { type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createEventSenders, createEventWaiters, createSleeper, event, workflow, workflowRegistry, workflowRunHandle };