@aikirun/workflow 0.13.0 → 0.15.0

package/README.md

@@ -44,6 +44,22 @@ 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({
+	name: "daily-report",
+	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 +69,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, ScheduleName, 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,33 @@ 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;
+    name: ScheduleName;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    delete(): Promise<void>;
+}
+type ScheduleDefinition = ScheduleParams & {
+    name: ScheduleName;
+    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: {
+    name: string;
+} & ScheduleParams): ScheduleDefinition;
+
 /**
  * Defines a durable workflow with versioning and multiple task execution.
  *
@@ -355,11 +385,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

@@ -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", {
@@ -548,15 +546,15 @@ var WorkflowRunHandleImpl = class {
       await this.refresh();
       return this.run.state;
     };
-    const isNeitherExpectedNorTerminal = (state) => Promise.resolve(state.status !== expectedStatus && !isTerminalWorkflowRunStatus(state.status));
+    const isNeitherExpectedNorTerminal = (state) => state.status !== expectedStatus && !isTerminalWorkflowRunStatus(state.status);
     if (!Number.isFinite(maxAttempts) && !options?.abortSignal) {
       const maybeResult2 = await withRetry(loadState, retryStrategy, {
-        shouldRetryOnResult: isNeitherExpectedNorTerminal
+        shouldRetryOnResult: async (state) => isNeitherExpectedNorTerminal(state)
       }).run();
       if (maybeResult2.state === "timeout") {
         throw new Error("Something's wrong, this should've never timed out");
       }
-      if (await isNeitherExpectedNorTerminal(maybeResult2.result)) {
+      if (maybeResult2.result.status !== expectedStatus) {
         return {
           success: false,
           cause: "run_terminated"
@@ -569,10 +567,13 @@ var WorkflowRunHandleImpl = class {
     }
     const maybeResult = options?.abortSignal ? await withRetry(loadState, retryStrategy, {
       abortSignal: options.abortSignal,
-      shouldRetryOnResult: isNeitherExpectedNorTerminal
-    }).run() : await withRetry(loadState, retryStrategy, { shouldRetryOnResult: isNeitherExpectedNorTerminal }).run();
+      shouldRetryOnResult: async (state) => isNeitherExpectedNorTerminal(state)
+    }).run() : await withRetry(loadState, retryStrategy, {
+      shouldRetryOnResult: async (state) => isNeitherExpectedNorTerminal(state)
+    }).run();
+    this.logger.info("Maybe result", { maybeResult });
     if (maybeResult.state === "completed") {
-      if (await isNeitherExpectedNorTerminal(maybeResult.result)) {
+      if (maybeResult.result.status !== expectedStatus) {
         return {
           success: false,
           cause: "run_terminated"
@@ -734,11 +735,59 @@ function createSleeper(handle, logger) {
   };
 }
 
+// schedule.ts
+function schedule(params) {
+  const { name, ...scheduleParams } = params;
+  return {
+    name,
+    ...scheduleParams,
+    async activate(client, workflow2, ...args) {
+      const input = args[0];
+      let scheduleSpec;
+      if (scheduleParams.type === "interval") {
+        const { every, ...rest } = scheduleParams;
+        scheduleSpec = {
+          ...rest,
+          everyMs: toMilliseconds(every)
+        };
+      } else {
+        scheduleSpec = scheduleParams;
+      }
+      const { schedule: schedule2 } = await client.api.schedule.activateV1({
+        name,
+        workflowName: workflow2.name,
+        workflowVersionId: workflow2.versionId,
+        spec: scheduleSpec,
+        input
+      });
+      client.logger.info("Schedule activated", {
+        scheduleSpec,
+        workflowName: workflow2.name,
+        workflowVersionId: workflow2.versionId
+      });
+      const scheduleId = schedule2.id;
+      return {
+        id: scheduleId,
+        name,
+        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 });
+        }
+      };
+    }
+  };
+}
+
 // 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}`;
 }
 
@@ -777,7 +826,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++;
@@ -846,7 +895,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;
@@ -861,28 +910,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 });
@@ -894,7 +933,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,
@@ -904,15 +943,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,
@@ -943,9 +985,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,
@@ -968,8 +1010,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", {
@@ -1120,6 +1162,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) {
@@ -1160,6 +1217,7 @@ export {
   createEventWaiters,
   createSleeper,
   event,
+  schedule,
   workflow,
   workflowRegistry,
   workflowRunHandle

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/workflow",
-	"version": "0.13.0",
+	"version": "0.15.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.13.0",
+		"@aikirun/types": "0.15.0",
 		"@standard-schema/spec": "^1.1.0"
 	},
 	"publishConfig": {