@aikirun/workflow 0.14.0 → 0.16.0

package/README.md

@@ -44,6 +44,21 @@ const handle = await onboardingWorkflowV1.start(aikiClient, {
 const result = await handle.waitForStatus("completed");
 ```
 
+## Scheduling
+
+Run workflows on a schedule using cron expressions or intervals:
+
+```typescript
+import { schedule } from "@aikirun/workflow";
+
+const dailyReport = schedule({
+	type: "cron",
+	expression: "0 9 * * *", // Every day at 9 AM
+});
+
+await dailyReport.activate(aikiClient, onboardingWorkflowV1, { email: "daily@example.com" });
+```
+
 ## Features
 
 - **Durable Execution** - Workflows survive crashes and restarts
@@ -53,6 +68,7 @@ const result = await handle.waitForStatus("completed");
 - **Child Workflows** - Compose workflows together
 - **Automatic Retries** - Configurable retry strategies
 - **Versioning** - Run multiple versions simultaneously
+- **Scheduling** - Trigger workflows on cron or interval schedules
 
 ## Documentation
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, WorkflowOptions } from '@aikirun/types/workflow-run';
+import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, 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';
@@ -10,6 +10,7 @@ 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';
+import { OverlapPolicy, ScheduleActivateOptions, ScheduleId } from '@aikirun/types/schedule';
 
 type NonEmptyArray<T> = [T, ...T[]];
 
@@ -30,11 +31,11 @@ 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, 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> {
+declare function workflowRunHandle<Input, Output, AppContext, TEvents extends EventsDefinition>(client: Client<AppContext>, id: WorkflowRunId, eventsDefinition?: TEvents, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
+declare function workflowRunHandle<Input, Output, AppContext, TEvents extends EventsDefinition>(client: Client<AppContext>, run: WorkflowRun<Input, Output>, eventsDefinition?: TEvents, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
+interface WorkflowRunHandle<Input, Output, AppContext, TEvents extends EventsDefinition = EventsDefinition> {
     run: Readonly<WorkflowRun<Input, Output>>;
-    events: EventSenders<TEventsDefinition>;
+    events: EventSenders<TEvents>;
     refresh: () => Promise<void>;
     /**
      *  Waits for the child workflow run to reach a terminal status by polling.
@@ -145,16 +146,16 @@ interface EventDefinition<Data> {
     schema?: StandardSchemaV1<Data>;
 }
 type EventsDefinition = Record<string, EventDefinition<unknown>>;
-type EventData<TEventDefinition> = TEventDefinition extends EventDefinition<infer Data> ? Data : never;
-type EventWaiters<TEventsDefinition extends EventsDefinition> = {
-    [K in keyof TEventsDefinition]: EventWaiter<EventData<TEventsDefinition[K]>>;
+type EventData<TEvent> = TEvent extends EventDefinition<infer Data> ? Data : never;
+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>>;
 }
-type EventSenders<TEventsDefinition extends EventsDefinition> = {
-    [K in keyof TEventsDefinition]: EventSender<EventData<TEventsDefinition[K]>>;
+type EventSenders<TEvents extends EventsDefinition> = {
+    [K in keyof TEvents]: EventSender<EventData<TEvents[K]>>;
 };
 interface EventSender<Data> {
     with(): EventSenderBuilder<Data>;
@@ -164,8 +165,8 @@ 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]>>;
+type EventMulticasters<TEvents extends EventsDefinition> = {
+    [K in keyof TEvents]: EventMulticaster<EventData<TEvents[K]>>;
 };
 interface EventMulticaster<Data> {
     with(): EventMulticasterBuilder<Data>;
@@ -175,26 +176,26 @@ 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>;
+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>;
 
-interface WorkflowRunContext<Input, AppContext, TEventDefinition extends EventsDefinition> {
+interface WorkflowRunContext<Input, AppContext, TEvents extends EventsDefinition> {
     id: WorkflowRunId;
     name: WorkflowName;
     versionId: WorkflowVersionId;
-    options: WorkflowOptions;
+    options: WorkflowStartOptions;
     logger: Logger;
     sleep: (name: string, duration: Duration) => Promise<SleepResult>;
-    events: EventWaiters<TEventDefinition>;
+    events: EventWaiters<TEvents>;
     [INTERNAL]: {
-        handle: WorkflowRunHandle<Input, unknown, AppContext, TEventDefinition>;
+        handle: WorkflowRunHandle<Input, unknown, AppContext, TEvents>;
         options: {
             spinThresholdMs: number;
         };
     };
 }
 
-type ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> = Omit<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>, "waitForStatus"> & {
+type ChildWorkflowRunHandle<Input, Output, AppContext, TEvents extends EventsDefinition = EventsDefinition> = Omit<WorkflowRunHandle<Input, Output, AppContext, TEvents>, "waitForStatus"> & {
     /**
      * Waits for the child workflow run to reach a terminal status.
      *
@@ -239,47 +240,44 @@ 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;
+interface WorkflowVersionParams<Input, Output, AppContext, TEvents extends EventsDefinition> {
+    handler: (run: Readonly<WorkflowRunContext<Input, AppContext, TEvents>>, input: Input, context: AppContext) => Promise<Output>;
+    events?: TEvents;
+    opts?: WorkflowDefinitionOptions;
     schema?: RequireAtLeastOneProp<{
         input?: StandardSchemaV1<Input>;
         output?: StandardSchemaV1<Output>;
     }>;
 }
-interface WorkflowVersion<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> {
+interface WorkflowVersion<Input, Output, AppContext, TEvents extends EventsDefinition = EventsDefinition> {
     name: WorkflowName;
     versionId: WorkflowVersionId;
-    events: EventMulticasters<TEventsDefinition>;
-    with(): WorkflowBuilder<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>>;
-    getHandleById: (client: Client<AppContext>, runId: string) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
-    getHandleByReferenceId: (client: Client<AppContext>, referenceId: string) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    events: EventMulticasters<TEvents>;
+    with(): WorkflowBuilder<Input, Output, AppContext, TEvents>;
+    start: (client: Client<AppContext>, ...args: Input extends void ? [] : [Input]) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
+    startAsChild: <ParentInput, ParentEvents extends EventsDefinition>(parentRun: WorkflowRunContext<ParentInput, AppContext, ParentEvents>, ...args: Input extends void ? [] : [Input]) => Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEvents>>;
+    getHandleById: (client: Client<AppContext>, runId: string) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
+    getHandleByReferenceId: (client: Client<AppContext>, referenceId: string) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
     [INTERNAL]: {
-        eventsDefinition: TEventsDefinition;
-        handler: (run: WorkflowRunContext<Input, AppContext, TEventsDefinition>, input: Input, context: AppContext) => Promise<void>;
+        eventsDefinition: TEvents;
+        handler: (run: WorkflowRunContext<Input, AppContext, TEvents>, 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> {
+declare class WorkflowVersionImpl<Input, Output, AppContext, TEvents extends EventsDefinition> implements WorkflowVersion<Input, Output, AppContext, TEvents> {
     readonly name: WorkflowName;
     readonly versionId: WorkflowVersionId;
     private readonly params;
-    readonly events: EventMulticasters<TEventsDefinition>;
-    readonly [INTERNAL]: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>[typeof INTERNAL];
-    constructor(name: WorkflowName, versionId: WorkflowVersionId, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>);
-    with(): WorkflowBuilder<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>>;
+    readonly events: EventMulticasters<TEvents>;
+    readonly [INTERNAL]: WorkflowVersion<Input, Output, AppContext, TEvents>[typeof INTERNAL];
+    constructor(name: WorkflowName, versionId: WorkflowVersionId, params: WorkflowVersionParams<Input, Output, AppContext, TEvents>);
+    with(): WorkflowBuilder<Input, Output, AppContext, TEvents>;
+    start(client: Client<AppContext>, ...args: Input extends void ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, AppContext, TEvents>>;
+    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;
-    getHandleById(client: Client<AppContext>, runId: string): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
-    getHandleByReferenceId(client: Client<AppContext>, referenceId: string): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    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;
     private tryExecuteWorkflow;
     private assertRetryAllowed;
@@ -287,6 +285,11 @@ declare class WorkflowVersionImpl<Input, Output, AppContext, TEventsDefinition e
     private createFailedState;
     private createAwaitingRetryState;
 }
+interface WorkflowBuilder<Input, Output, AppContext, TEvents extends EventsDefinition> {
+    opt<Path extends PathFromObject<WorkflowStartOptions>>(path: Path, value: TypeOfValueAtPath<WorkflowStartOptions, Path>): WorkflowBuilder<Input, Output, AppContext, TEvents>;
+    start: WorkflowVersion<Input, Output, AppContext, TEvents>["start"];
+    startAsChild: WorkflowVersion<Input, Output, AppContext, TEvents>["startAsChild"];
+}
 
 declare function workflowRegistry(): WorkflowRegistry;
 type Workflow$1 = WorkflowVersion<unknown, unknown, unknown>;
@@ -302,6 +305,34 @@ interface WorkflowRegistry {
 
 declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unknown>, logger: Logger): (name: string, duration: Duration) => Promise<SleepResult>;
 
+interface CronScheduleParams {
+    type: "cron";
+    expression: string;
+    timezone?: string;
+    overlapPolicy?: OverlapPolicy;
+}
+interface IntervalScheduleParams {
+    type: "interval";
+    every: DurationObject;
+    overlapPolicy?: OverlapPolicy;
+}
+type ScheduleParams = CronScheduleParams | IntervalScheduleParams;
+interface ScheduleHandle {
+    id: ScheduleId;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    delete(): Promise<void>;
+}
+interface ScheduleBuilder {
+    opt<Path extends PathFromObject<ScheduleActivateOptions>>(path: Path, value: TypeOfValueAtPath<ScheduleActivateOptions, Path>): ScheduleBuilder;
+    activate<Input, Output, AppContext, TEvents extends EventsDefinition>(client: Client<AppContext>, workflow: WorkflowVersion<Input, Output, AppContext, TEvents>, ...args: Input extends void ? [] : [Input]): Promise<ScheduleHandle>;
+}
+type ScheduleDefinition = ScheduleParams & {
+    with(): ScheduleBuilder;
+    activate<Input, Output, AppContext, TEvents extends EventsDefinition>(client: Client<AppContext>, workflow: WorkflowVersion<Input, Output, AppContext, TEvents>, ...args: Input extends void ? [] : [Input]): Promise<ScheduleHandle>;
+};
+declare function schedule(params: ScheduleParams): ScheduleDefinition;
+
 /**
  * Defines a durable workflow with versioning and multiple task execution.
  *
@@ -355,11 +386,11 @@ interface WorkflowParams {
 }
 interface Workflow {
     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>;
+    v: <Input extends Serializable, Output extends Serializable, AppContext = null, TEvents extends EventsDefinition = Record<string, never>>(versionId: string, params: WorkflowVersionParams<Input, Output, AppContext, TEvents>) => WorkflowVersion<Input, Output, AppContext, TEvents>;
     [INTERNAL]: {
         getAllVersions: () => WorkflowVersion<unknown, unknown, unknown>[];
         getVersion: (versionId: WorkflowVersionId) => WorkflowVersion<unknown, unknown, unknown> | undefined;
     };
 }
 
-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 };
+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 };

package/dist/index.js

@@ -292,8 +292,8 @@ function getRetryParams(attempts, strategy) {
 import { INTERNAL } from "@aikirun/types/symbols";
 import { SchemaValidationError } from "@aikirun/types/validator";
 import {
-  WorkflowRunConflictError,
   WorkflowRunFailedError,
+  WorkflowRunRevisionConflictError,
   WorkflowRunSuspendedError
 } from "@aikirun/types/workflow-run";
 function event(params) {
@@ -361,7 +361,7 @@ function createEventWaiter(handle, eventName, schema, logger) {
         ...timeoutInMs !== void 0 ? { "aiki.timeoutInMs": timeoutInMs } : {}
       });
     } catch (error) {
-      if (error instanceof WorkflowRunConflictError) {
+      if (error instanceof WorkflowRunRevisionConflictError) {
         throw new WorkflowRunSuspendedError(handle.run.id);
       }
       throw error;
@@ -392,10 +392,9 @@ function createEventSender(api, workflowRunId, eventName, schema, logger, onSend
     send: (...args) => createEventSender(api, workflowRunId, eventName, schema, logger, onSend, optsBuilder.build()).send(...args)
   });
   async function send(...args) {
-    const dataRaw = isNonEmptyArray(args) ? args[0] : void 0;
-    let data = dataRaw;
+    let data = args[0];
     if (schema) {
-      const schemaValidation = schema["~standard"].validate(dataRaw);
+      const schemaValidation = schema["~standard"].validate(data);
       const schemaValidationResult = schemaValidation instanceof Promise ? await schemaValidation : schemaValidation;
       if (schemaValidationResult.issues) {
         logger.error("Invalid event data", { "aiki.issues": schemaValidationResult.issues });
@@ -443,10 +442,9 @@ function createEventMulticaster(workflowName, workflowVersionId, eventName, sche
     )
   });
   async function send(client, runId, ...args) {
-    const dataRaw = isNonEmptyArray(args) ? args[0] : void 0;
-    let data = dataRaw;
+    let data = args[0];
     if (schema) {
-      const schemaValidation = schema["~standard"].validate(dataRaw);
+      const schemaValidation = schema["~standard"].validate(data);
       const schemaValidationResult = schemaValidation instanceof Promise ? await schemaValidation : schemaValidation;
       if (schemaValidationResult.issues) {
         client.logger.error("Invalid event data", {
@@ -487,8 +485,8 @@ function createEventMulticaster(workflowName, workflowVersionId, eventName, sche
 import { INTERNAL as INTERNAL2 } from "@aikirun/types/symbols";
 import {
   isTerminalWorkflowRunStatus,
-  WorkflowRunConflictError as WorkflowRunConflictError2,
-  WorkflowRunNotExecutableError
+  WorkflowRunNotExecutableError,
+  WorkflowRunRevisionConflictError as WorkflowRunRevisionConflictError2
 } from "@aikirun/types/workflow-run";
 async function workflowRunHandle(client, runOrId, eventsDefinition, logger) {
   const run = typeof runOrId !== "string" ? runOrId : (await client.api.workflowRun.getByIdV1({ id: runOrId })).run;
@@ -624,7 +622,7 @@ var WorkflowRunHandleImpl = class {
       this._run = run;
     } catch (error) {
       if (isConflictError(error)) {
-        throw new WorkflowRunConflictError2(this.run.id);
+        throw new WorkflowRunRevisionConflictError2(this.run.id);
       }
       throw error;
     }
@@ -640,7 +638,7 @@ var WorkflowRunHandleImpl = class {
       return { taskId };
     } catch (error) {
       if (isConflictError(error)) {
-        throw new WorkflowRunConflictError2(this.run.id);
+        throw new WorkflowRunRevisionConflictError2(this.run.id);
       }
       throw error;
     }
@@ -658,7 +656,10 @@ function isConflictError(error) {
 
 // run/sleeper.ts
 import { INTERNAL as INTERNAL3 } from "@aikirun/types/symbols";
-import { WorkflowRunConflictError as WorkflowRunConflictError3, WorkflowRunSuspendedError as WorkflowRunSuspendedError2 } from "@aikirun/types/workflow-run";
+import {
+  WorkflowRunRevisionConflictError as WorkflowRunRevisionConflictError3,
+  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) {
@@ -680,7 +681,7 @@ function createSleeper(handle, logger) {
           "aiki.durationMs": durationMs
         });
       } catch (error) {
-        if (error instanceof WorkflowRunConflictError3) {
+        if (error instanceof WorkflowRunRevisionConflictError3) {
           throw new WorkflowRunSuspendedError2(handle.run.id);
         }
         throw error;
@@ -728,7 +729,7 @@ function createSleeper(handle, logger) {
         "aiki.durationMs": durationMs
       });
     } catch (error) {
-      if (error instanceof WorkflowRunConflictError3) {
+      if (error instanceof WorkflowRunRevisionConflictError3) {
         throw new WorkflowRunSuspendedError2(handle.run.id);
       }
       throw error;
@@ -737,11 +738,72 @@ function createSleeper(handle, logger) {
   };
 }
 
+// schedule.ts
+function schedule(params) {
+  async function activateWithOpts(client, workflow2, options, ...args) {
+    const input = args[0];
+    let scheduleSpec;
+    if (params.type === "interval") {
+      const { every, ...rest } = params;
+      scheduleSpec = {
+        ...rest,
+        everyMs: toMilliseconds(every)
+      };
+    } else {
+      scheduleSpec = params;
+    }
+    const { schedule: schedule2 } = await client.api.schedule.activateV1({
+      workflowName: workflow2.name,
+      workflowVersionId: workflow2.versionId,
+      spec: scheduleSpec,
+      input,
+      options
+    });
+    client.logger.info("Schedule activated", {
+      scheduleSpec,
+      workflowName: workflow2.name,
+      workflowVersionId: workflow2.versionId,
+      referenceId: options?.reference?.id
+    });
+    const scheduleId = schedule2.id;
+    return {
+      id: scheduleId,
+      pause: async () => {
+        await client.api.schedule.pauseV1({ id: scheduleId });
+      },
+      resume: async () => {
+        await client.api.schedule.resumeV1({ id: scheduleId });
+      },
+      delete: async () => {
+        await client.api.schedule.deleteV1({ id: scheduleId });
+      }
+    };
+  }
+  function createBuilder(optsBuilder) {
+    return {
+      opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
+      async activate(client, workflow2, ...args) {
+        return activateWithOpts(client, workflow2, optsBuilder.build(), ...args);
+      }
+    };
+  }
+  return {
+    ...params,
+    with() {
+      const optsOverrider = objectOverrider({});
+      return createBuilder(optsOverrider());
+    },
+    async activate(client, workflow2, ...args) {
+      return activateWithOpts(client, workflow2, {}, ...args);
+    }
+  };
+}
+
 // workflow.ts
 import { INTERNAL as INTERNAL6 } from "@aikirun/types/symbols";
 
-// ../../lib/path/index.ts
-function getWorkflowRunPath(name, versionId, referenceId) {
+// ../../lib/address/index.ts
+function getWorkflowRunAddress(name, versionId, referenceId) {
   return `${name}/${versionId}/${referenceId}`;
 }
 
@@ -750,8 +812,8 @@ import { INTERNAL as INTERNAL5 } from "@aikirun/types/symbols";
 import { TaskFailedError } from "@aikirun/types/task";
 import { SchemaValidationError as SchemaValidationError2 } from "@aikirun/types/validator";
 import {
-  WorkflowRunConflictError as WorkflowRunConflictError5,
   WorkflowRunFailedError as WorkflowRunFailedError2,
+  WorkflowRunRevisionConflictError as WorkflowRunRevisionConflictError5,
   WorkflowRunSuspendedError as WorkflowRunSuspendedError4
 } from "@aikirun/types/workflow-run";
 
@@ -759,7 +821,7 @@ import {
 import { INTERNAL as INTERNAL4 } from "@aikirun/types/symbols";
 import {
   isTerminalWorkflowRunStatus as isTerminalWorkflowRunStatus2,
-  WorkflowRunConflictError as WorkflowRunConflictError4,
+  WorkflowRunRevisionConflictError as WorkflowRunRevisionConflictError4,
   WorkflowRunSuspendedError as WorkflowRunSuspendedError3
 } from "@aikirun/types/workflow-run";
 async function childWorkflowRunHandle(client, run, parentRun, logger, eventsDefinition) {
@@ -780,7 +842,7 @@ function createStatusWaiter(handle, parentRun, logger) {
   let nextWaitIndex = 0;
   async function waitForStatus(expectedStatus, options) {
     const parentRunHandle = parentRun[INTERNAL4].handle;
-    const waitResults = parentRunHandle.run.childWorkflowRuns[handle.run.path]?.statusWaitResults ?? [];
+    const waitResults = parentRunHandle.run.childWorkflowRuns[handle.run.address]?.statusWaitResults ?? [];
     const waitResult = waitResults[nextWaitIndex];
     if (waitResult) {
       nextWaitIndex++;
@@ -838,7 +900,7 @@ function createStatusWaiter(handle, parentRun, logger) {
         ...timeoutInMs !== void 0 ? { "aiki.timeoutInMs": timeoutInMs } : {}
       });
     } catch (error) {
-      if (error instanceof WorkflowRunConflictError4) {
+      if (error instanceof WorkflowRunRevisionConflictError4) {
         throw new WorkflowRunSuspendedError3(parentRun.id);
       }
       throw error;
@@ -849,7 +911,7 @@ function createStatusWaiter(handle, parentRun, logger) {
 }
 
 // workflow-version.ts
-var WorkflowVersionImpl = class _WorkflowVersionImpl {
+var WorkflowVersionImpl = class {
   constructor(name, versionId, params) {
     this.name = name;
     this.versionId = versionId;
@@ -864,28 +926,18 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
   events;
   [INTERNAL5];
   with() {
-    const optsOverrider = objectOverrider(this.params.opts ?? {});
-    const createBuilder = (optsBuilder) => {
-      return {
-        opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
-        start: (client, ...args) => new _WorkflowVersionImpl(this.name, this.versionId, {
-          ...this.params,
-          opts: optsBuilder.build()
-        }).start(client, ...args),
-        startAsChild: (parentRun, ...args) => new _WorkflowVersionImpl(this.name, this.versionId, {
-          ...this.params,
-          opts: optsBuilder.build()
-        }).startAsChild(parentRun, ...args)
-      };
-    };
-    return createBuilder(optsOverrider());
+    const startOpts = this.params.opts ?? {};
+    const startOptsOverrider = objectOverrider(startOpts);
+    return new WorkflowBuilderImpl(this, startOptsOverrider());
   }
   async start(client, ...args) {
-    const inputRaw = isNonEmptyArray(args) ? args[0] : void 0;
-    let input = inputRaw;
+    return this.startWithOpts(client, this.params.opts ?? {}, ...args);
+  }
+  async startWithOpts(client, startOpts, ...args) {
+    let input = args[0];
     const schema = this.params.schema?.input;
     if (schema) {
-      const schemaValidation = schema["~standard"].validate(inputRaw);
+      const schemaValidation = schema["~standard"].validate(input);
       const schemaValidationResult = schemaValidation instanceof Promise ? await schemaValidation : schemaValidation;
       if (schemaValidationResult.issues) {
         client.logger.error("Invalid workflow data", { "aiki.issues": schemaValidationResult.issues });
@@ -897,7 +949,7 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       name: this.name,
       versionId: this.versionId,
       input,
-      options: this.params.opts
+      options: startOpts
     });
     client.logger.info("Created workflow", {
       "aiki.workflowName": this.name,
@@ -907,15 +959,18 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
     return workflowRunHandle(client, run, this[INTERNAL5].eventsDefinition);
   }
   async startAsChild(parentRun, ...args) {
+    return this.startAsChildWithOpts(parentRun, this.params.opts ?? {}, ...args);
+  }
+  async startAsChildWithOpts(parentRun, startOpts, ...args) {
     const parentRunHandle = parentRun[INTERNAL5].handle;
     parentRunHandle[INTERNAL5].assertExecutionAllowed();
     const { client } = parentRunHandle[INTERNAL5];
-    const inputRaw = isNonEmptyArray(args) ? args[0] : void 0;
+    const inputRaw = args[0];
     const input = await this.parse(parentRunHandle, this.params.schema?.input, inputRaw, parentRun.logger);
     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];
+    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,
@@ -946,9 +1001,9 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       versionId: this.versionId,
       input,
       parentWorkflowRunId: parentRun.id,
-      options: this.params.opts
+      options: startOpts
     });
-    parentRunHandle.run.childWorkflowRuns[path] = {
+    parentRunHandle.run.childWorkflowRuns[address] = {
       id: newRun.id,
       name: newRun.name,
       versionId: newRun.versionId,
@@ -971,8 +1026,8 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
   }
   async assertUniqueChildRunReferenceId(parentRunHandle, existingRunInfo, inputHash, reference, logger) {
     if (existingRunInfo.inputHash !== inputHash && reference) {
-      const onConflict = reference.onConflict ?? "error";
-      if (onConflict !== "error") {
+      const conflictPolicy = reference.conflictPolicy ?? "error";
+      if (conflictPolicy !== "error") {
         return;
       }
       logger.error("Reference ID already used by another child workflow", {
@@ -1026,7 +1081,7 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
         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 WorkflowRunConflictError5) {
+        if (error instanceof WorkflowRunSuspendedError4 || error instanceof WorkflowRunFailedError2 || error instanceof WorkflowRunRevisionConflictError5) {
           throw error;
         }
         const attempts = handle.run.attempts;
@@ -1123,6 +1178,21 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
     };
   }
 };
+var WorkflowBuilderImpl = class _WorkflowBuilderImpl {
+  constructor(workflow2, startOptsBuilder) {
+    this.workflow = workflow2;
+    this.startOptsBuilder = startOptsBuilder;
+  }
+  opt(path, value) {
+    return new _WorkflowBuilderImpl(this.workflow, this.startOptsBuilder.with(path, value));
+  }
+  start(client, ...args) {
+    return this.workflow.startWithOpts(client, this.startOptsBuilder.build(), ...args);
+  }
+  startAsChild(parentRun, ...args) {
+    return this.workflow.startAsChildWithOpts(parentRun, this.startOptsBuilder.build(), ...args);
+  }
+};
 
 // workflow.ts
 function workflow(params) {
@@ -1163,6 +1233,7 @@ export {
   createEventWaiters,
   createSleeper,
   event,
+  schedule,
   workflow,
   workflowRegistry,
   workflowRunHandle

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/workflow",
-	"version": "0.14.0",
+	"version": "0.16.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.14.0",
+		"@aikirun/types": "0.16.0",
 		"@standard-schema/spec": "^1.1.0"
 	},
 	"publishConfig": {