@aikirun/workflow 0.5.3

package/README.md

@@ -0,0 +1,258 @@
+# @aikirun/workflow
+
+Workflow SDK for Aiki durable execution platform - define durable workflows with tasks, sleeps, waits, and event handling.
+
+## Installation
+
+```bash
+npm install @aikirun/workflow
+```
+
+## Quick Start
+
+### Define a Workflow
+
+```typescript
+import { workflow } from "@aikirun/workflow";
+import { markUserVerified, sendVerificationEmail } from "./tasks.ts";
+
+export const onboardingWorkflow = workflow({ id: "user-onboarding" });
+
+export const onboardingWorkflowV1 = onboardingWorkflow.v("1.0", {
+	async handler(input: { email: string }, run) {
+		run.logger.info("Starting onboarding", { email: input.email });
+
+		// Execute a task to send verification email
+		await sendVerificationEmail.start(run, { email: input.email });
+
+		// Execute task to mark user as verified
+		// (In a real scenario, this would be triggered by an external event)
+		await markUserVerified.start(run, { email: input.email });
+
+		// Sleep for 24 hours before sending tips
+		await run.sleep({ id: "onboarding-delay", days: 1 });
+
+		// Send usage tips
+		await sendUsageTips.start(run, { email: input.email });
+
+		return { success: true, userId: input.email };
+	},
+});
+```
+
+## Features
+
+- **Durable Execution** - Automatically survives crashes and restarts
+- **Task Orchestration** - Coordinate multiple tasks in sequence
+- **Durable Sleep** - Sleep without consuming resources or blocking workers
+- **State Snapshots** - Automatically save state at each step
+- **Error Handling** - Built-in retry and recovery mechanisms
+- **Multiple Versions** - Run different workflow versions simultaneously
+- **Logging** - Built-in structured logging for debugging
+
+## Workflow Primitives
+
+### Execute Tasks
+
+```typescript
+const result = await createUserProfile.start(run, {
+	email: input.email,
+});
+```
+
+### Sleep for a Duration
+
+```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 });
+```
+
+### Sleep Cancellation
+
+Sleeps can be cancelled externally via the `wake()` method:
+
+```typescript
+const handle = await myWorkflow.start(client, input);
+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 });
+if (cancelled) {
+  // Handle early wake-up
+}
+```
+
+### Get Workflow State
+
+```typescript
+const { state } = await run.handle.getState();
+console.log("Workflow status:", state.status);
+```
+
+### Logging
+
+```typescript
+run.logger.info("Processing user", { email: input.email });
+run.logger.debug("User created", { userId: result.userId });
+```
+
+## Workflow Options
+
+### Delayed Trigger
+
+```typescript
+export const morningWorkflowV1 = morningWorkflow.v("1.0", {
+	// ... workflow definition
+	opts: {
+		trigger: {
+			type: "delayed",
+			delay: { seconds: 5 }, // or: delay: 5000
+		},
+	},
+});
+```
+
+### Retry Strategy
+
+```typescript
+export const paymentWorkflowV1 = paymentWorkflow.v("1.0", {
+	// ... workflow definition
+	opts: {
+		retry: {
+			type: "exponential",
+			maxAttempts: 3,
+			baseDelayMs: 1000,
+			maxDelayMs: 10000,
+		},
+	},
+});
+```
+
+### Idempotency Key
+
+```typescript
+export const orderWorkflowV1 = orderWorkflow.v("1.0", {
+	// ... workflow definition
+	opts: {
+		idempotencyKey: "order-${orderId}",
+	},
+});
+```
+
+## Running Workflows
+
+With the client:
+
+```typescript
+import { client } from "@aikirun/client";
+import { onboardingWorkflowV1 } from "./workflows.ts";
+
+const aikiClient = await client({
+	url: "http://localhost:9090",
+	redis: { host: "localhost", port: 6379 },
+});
+
+const handle = await onboardingWorkflowV1.start(aikiClient, {
+	email: "user@example.com",
+});
+
+// Wait for completion
+const result = await handle.wait(
+	{ type: "status", status: "completed" },
+	{ maxDurationMs: 60 * 1000, pollIntervalMs: 5_000 },
+);
+
+if (result.success) {
+	console.log("Workflow completed!", result.state);
+} else {
+	console.log("Workflow did not complete:", result.cause);
+}
+```
+
+With a worker:
+
+```typescript
+import { worker } from "@aikirun/worker";
+
+const aikiWorker = worker({
+	id: "my-worker",
+	workflows: [onboardingWorkflowV1],
+	opts: {
+		maxConcurrentWorkflowRuns: 10,
+	},
+});
+
+await aikiWorker.spawn(aikiClient);
+```
+
+## Execution Context
+
+The `run` parameter provides access to:
+
+```typescript
+interface WorkflowRunContext<Input, Output> {
+	id: WorkflowRunId; // Unique run ID
+	name: WorkflowName; // Workflow name
+	versionId: WorkflowVersionId; // Version ID
+	options: WorkflowOptions; // Execution options (trigger, retry, idempotencyKey)
+	handle: WorkflowRunHandle<Input, Output>; // Advanced state management
+	logger: Logger; // Logging (info, debug, warn, error, trace)
+	sleep(params: SleepParams): Promise<SleepResult>; // Durable sleep
+}
+```
+
+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 })`
+
+## Error Handling
+
+Workflows handle errors gracefully:
+
+```typescript
+try {
+	await risky.start(run, input);
+} catch (error) {
+	run.logger.error("Task failed", { error: error.message });
+	// Workflow can decide how to proceed
+}
+```
+
+Failed workflows transition to `awaiting_retry` state and are automatically retried by the server.
+
+### 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.
+
+## Best Practices
+
+1. **Keep Workflows Deterministic** - Same input should always produce same output
+2. **Expect Replays** - Code may execute multiple times during retries
+3. **Use Descriptive Events** - Name events clearly for debugging
+4. **Handle Timeouts** - Always check `event.received` after waiting
+5. **Log Strategically** - Use logger to track workflow progress
+6. **Version Your Workflows** - Deploy new versions alongside old ones
+
+## Related Packages
+
+- [@aikirun/task](https://www.npmjs.com/package/@aikirun/task) - Define tasks
+- [@aikirun/client](https://www.npmjs.com/package/@aikirun/client) - Start workflows
+- [@aikirun/worker](https://www.npmjs.com/package/@aikirun/worker) - Execute workflows
+- [@aikirun/types](https://www.npmjs.com/package/@aikirun/types) - Type definitions
+
+## Changelog
+
+See the [CHANGELOG](https://github.com/aikirun/aiki/blob/main/CHANGELOG.md) for version history.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import { WorkflowId, WorkflowVersionId } from '@aikirun/types/workflow';
+import { Client, Logger } 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 { TaskPath, TaskState } from '@aikirun/types/task';
+import { SerializableInput } from '@aikirun/types/error';
+
+type NonEmptyArray<T> = [T, ...T[]];
+
+type NonArrayObject<T> = T extends object ? (T extends ReadonlyArray<unknown> ? never : T) : never;
+type IsSubtype<SubT, SuperT> = SubT extends SuperT ? true : false;
+type And<T extends NonEmptyArray<boolean>> = T extends [infer First, ...infer Rest] ? false extends First ? false : Rest extends NonEmptyArray<boolean> ? And<Rest> : true : never;
+type Or<T extends NonEmptyArray<boolean>> = T extends [infer First, ...infer Rest] ? true extends First ? true : Rest extends NonEmptyArray<boolean> ? Or<Rest> : false : never;
+type PathFromObject<T, IncludeArrayKeys extends boolean = false> = T extends T ? PathFromObjectInternal<T, IncludeArrayKeys> : never;
+type PathFromObjectInternal<T, IncludeArrayKeys extends boolean> = And<[
+    IsSubtype<T, object>,
+    Or<[IncludeArrayKeys, NonArrayObject<T> extends never ? false : true]>
+]> extends true ? {
+    [K in Exclude<keyof T, symbol>]-?: And<[
+        IsSubtype<NonNullable<T[K]>, object>,
+        Or<[IncludeArrayKeys, NonArrayObject<NonNullable<T[K]>> extends never ? false : true]>
+    ]> extends true ? K | `${K}.${PathFromObjectInternal<NonNullable<T[K]>, IncludeArrayKeys>}` : K;
+}[Exclude<keyof T, symbol>] : "";
+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>(client: Client<unknown>, id: WorkflowRunId): Promise<WorkflowRunHandle<Input, Output>>;
+declare function workflowRunHandle<Input, Output>(client: Client<unknown>, run: WorkflowRun<Input, Output>, logger?: Logger): Promise<WorkflowRunHandle<Input, Output>>;
+interface WorkflowRunHandle<Input, Output> {
+    run: Readonly<WorkflowRun<Input, Output>>;
+    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>;
+    }>;
+    cancel: (reason?: string) => Promise<void>;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    [INTERNAL]: {
+        transitionState: (state: WorkflowRunState<Output>) => Promise<void>;
+        transitionTaskState: (taskPath: TaskPath, taskState: TaskState<unknown>) => Promise<void>;
+        assertExecutionAllowed: () => void;
+    };
+}
+interface WorkflowRunWaitOptions {
+    maxDurationMs: number;
+    pollIntervalMs?: number;
+    abortSignal?: AbortSignal;
+}
+
+interface WorkflowRunContext<Input, Output> {
+    id: WorkflowRunId;
+    workflowId: WorkflowId;
+    workflowVersionId: WorkflowVersionId;
+    options: WorkflowOptions;
+    logger: Logger;
+    sleep: (params: SleepParams) => Promise<SleepResult>;
+    [INTERNAL]: {
+        handle: WorkflowRunHandle<Input, Output>;
+    };
+}
+
+interface WorkflowVersionParams<Input, Output, AppContext> {
+    handler: (input: Input, run: Readonly<WorkflowRunContext<Input, Output>>, context: AppContext) => Promise<Output>;
+    opts?: WorkflowOptions;
+}
+interface WorkflowBuilder<Input, Output, AppContext> {
+    opt<Path extends PathFromObject<WorkflowOptions>>(path: Path, value: TypeOfValueAtPath<WorkflowOptions, Path>): WorkflowBuilder<Input, Output, AppContext>;
+    start: WorkflowVersion<Input, Output, AppContext>["start"];
+}
+interface WorkflowVersion<Input, Output, AppContext> {
+    id: WorkflowId;
+    versionId: WorkflowVersionId;
+    with(): WorkflowBuilder<Input, Output, AppContext>;
+    start: (client: Client<AppContext>, ...args: Input extends null ? [] : [Input]) => Promise<WorkflowRunHandle<Input, Output>>;
+    [INTERNAL]: {
+        handler: (input: Input, run: WorkflowRunContext<Input, Output>, context: AppContext) => Promise<void>;
+    };
+}
+declare class WorkflowVersionImpl<Input, Output, AppContext> implements WorkflowVersion<Input, Output, AppContext> {
+    readonly id: WorkflowId;
+    readonly versionId: WorkflowVersionId;
+    private readonly params;
+    readonly [INTERNAL]: WorkflowVersion<Input, Output, AppContext>[typeof INTERNAL];
+    constructor(id: WorkflowId, versionId: WorkflowVersionId, params: WorkflowVersionParams<Input, Output, AppContext>);
+    with(): WorkflowBuilder<Input, Output, AppContext>;
+    start(client: Client<AppContext>, ...args: Input extends null ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output>>;
+    private handler;
+    private tryExecuteWorkflow;
+    private assertRetryAllowed;
+    private createFailedState;
+    private createAwaitingRetryState;
+}
+
+declare function workflowRegistry(): WorkflowRegistry;
+type Workflow$1 = WorkflowVersion<unknown, unknown, unknown>;
+interface WorkflowRegistry {
+    add: (workflow: Workflow$1) => WorkflowRegistry;
+    addMany: (workflows: Workflow$1[]) => WorkflowRegistry;
+    remove: (workflow: Workflow$1) => WorkflowRegistry;
+    removeMany: (workflows: Workflow$1[]) => WorkflowRegistry;
+    removeAll: () => WorkflowRegistry;
+    getAll(): Workflow$1[];
+    get: (id: WorkflowId, versionId: WorkflowVersionId) => Workflow$1 | undefined;
+}
+
+interface SleeperOptions {
+    spinThresholdMs: number;
+}
+declare function createWorkflowRunSleeper(workflowRunHandle: WorkflowRunHandle<unknown, unknown>, logger: Logger, options: SleeperOptions): (params: SleepParams) => Promise<SleepResult>;
+
+/**
+ * Defines a durable workflow with versioning and multiple task execution.
+ *
+ * Workflows are long-running business processes that can span hours, days, or longer.
+ * They automatically survive crashes, timeouts, and infrastructure failures.
+ * 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
+ * @returns Workflow instance with version management methods
+ *
+ * @example
+ * ```typescript
+ * // Define a workflow
+ * export const userOnboarding = workflow({ id: "user-onboarding" });
+ *
+ * // Define version 1.0
+ * export const userOnboardingV1 = userOnboarding.v("1.0", {
+ *   async handler(input: { email: string }, run) {
+ *     run.logger.info("Starting onboarding", { email: input.email });
+ *
+ *     // Execute tasks
+ *     await sendWelcomeEmail.start(run, { email: input.email });
+ *     await createUserProfile.start(run, { email: input.email });
+ *
+ *     // Durable sleep
+ *     await run.sleep({ id: "onboarding-delay", days: 1 });
+ *
+ *     // More tasks
+ *     await sendUsageTips.start(run, { email: input.email });
+ *
+ *     return { success: true };
+ *   },
+ * });
+ *
+ * // Deploy version 2.0 alongside 1.0 (no downtime)
+ * export const userOnboardingV2 = userOnboarding.v("2.0", {
+ *   async handler(input: { email: string; trial: boolean }, run) {
+ *     // Enhanced version with different logic
+ *     // Existing v1.0 workflows continue with their version
+ *     // New workflows use v2.0
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link https://github.com/aikirun/aiki} for complete documentation
+ */
+declare function workflow(params: WorkflowParams): Workflow;
+interface WorkflowParams {
+    id: string;
+}
+interface Workflow {
+    id: WorkflowId;
+    v: <Input extends SerializableInput = null, Output = void, AppContext = null>(versionId: string, params: WorkflowVersionParams<Input, Output, AppContext>) => WorkflowVersion<Input, Output, AppContext>;
+    [INTERNAL]: {
+        getAllVersions: () => WorkflowVersion<unknown, unknown, unknown>[];
+        getVersion: (versionId: WorkflowVersionId) => WorkflowVersion<unknown, unknown, unknown> | undefined;
+    };
+}
+
+export { type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createWorkflowRunSleeper, workflow, workflowRegistry, workflowRunHandle };

package/dist/index.js

@@ -0,0 +1,611 @@
+// registry.ts
+function workflowRegistry() {
+  return new WorkflowRegistryImpl();
+}
+var WorkflowRegistryImpl = class {
+  workflowsById = /* @__PURE__ */ new Map();
+  add(workflow2) {
+    const workflows = this.workflowsById.get(workflow2.id);
+    if (!workflows) {
+      this.workflowsById.set(workflow2.id, /* @__PURE__ */ new Map([[workflow2.versionId, workflow2]]));
+      return this;
+    }
+    if (workflows.has(workflow2.versionId)) {
+      throw new Error(`Workflow "${workflow2.id}/${workflow2.versionId}" is already registered`);
+    }
+    workflows.set(workflow2.versionId, workflow2);
+    return this;
+  }
+  addMany(workflows) {
+    for (const workflow2 of workflows) {
+      this.add(workflow2);
+    }
+    return this;
+  }
+  remove(workflow2) {
+    const workflowVersinos = this.workflowsById.get(workflow2.id);
+    if (workflowVersinos) {
+      workflowVersinos.delete(workflow2.versionId);
+    }
+    return this;
+  }
+  removeMany(workflows) {
+    for (const workflow2 of workflows) {
+      this.remove(workflow2);
+    }
+    return this;
+  }
+  removeAll() {
+    this.workflowsById.clear();
+    return this;
+  }
+  getAll() {
+    const workflows = [];
+    for (const workflowVersions of this.workflowsById.values()) {
+      for (const workflow2 of workflowVersions.values()) {
+        workflows.push(workflow2);
+      }
+    }
+    return workflows;
+  }
+  get(id, versionId) {
+    return this.workflowsById.get(id)?.get(versionId);
+  }
+};
+
+// ../../lib/array/utils.ts
+function isNonEmptyArray(value) {
+  return value.length > 0;
+}
+
+// ../../lib/async/delay.ts
+function delay(ms, options) {
+  const abortSignal = options?.abortSignal;
+  if (abortSignal?.aborted) {
+    return Promise.reject(abortSignal.reason);
+  }
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timeout);
+      reject(abortSignal?.reason);
+    };
+    const timeout = setTimeout(() => {
+      abortSignal?.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    abortSignal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+// ../../lib/duration/convert.ts
+var MS_PER_SECOND = 1e3;
+var MS_PER_MINUTE = 60 * MS_PER_SECOND;
+var MS_PER_HOUR = 60 * MS_PER_MINUTE;
+var MS_PER_DAY = 24 * MS_PER_HOUR;
+function toMilliseconds(duration) {
+  if (typeof duration === "number") {
+    assertIsPositiveNumber(duration);
+    return duration;
+  }
+  let totalMs = 0;
+  if (duration.days !== void 0) {
+    assertIsPositiveNumber(duration.days, "days");
+    totalMs += duration.days * MS_PER_DAY;
+  }
+  if (duration.hours !== void 0) {
+    assertIsPositiveNumber(duration.hours, "hours");
+    totalMs += duration.hours * MS_PER_HOUR;
+  }
+  if (duration.minutes !== void 0) {
+    assertIsPositiveNumber(duration.minutes, "minutes");
+    totalMs += duration.minutes * MS_PER_MINUTE;
+  }
+  if (duration.seconds !== void 0) {
+    assertIsPositiveNumber(duration.seconds, "seconds");
+    totalMs += duration.seconds * MS_PER_SECOND;
+  }
+  if (duration.milliseconds !== void 0) {
+    assertIsPositiveNumber(duration.milliseconds, "milliseconds");
+    totalMs += duration.milliseconds;
+  }
+  return totalMs;
+}
+function assertIsPositiveNumber(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new Error(
+      field !== void 0 ? `'${field}' duration must be finite. Received: ${value}` : `Duration must be finite. Received: ${value}`
+    );
+  }
+  if (value < 0) {
+    throw new Error(
+      field !== void 0 ? `'${field}' duration must be non-negative. Received: ${value}` : `Duration must be non-negative. Received: ${value}`
+    );
+  }
+}
+
+// ../../lib/error/serializable.ts
+function createSerializableError(error) {
+  return error instanceof Error ? {
+    message: error.message,
+    name: error.name,
+    stack: error.stack,
+    cause: error.cause ? createSerializableError(error.cause) : void 0
+  } : {
+    message: String(error),
+    name: "UnknownError"
+  };
+}
+
+// ../../lib/object/overrider.ts
+function set(obj, path, value) {
+  const keys = path.split(".");
+  let currentValue = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    currentValue = currentValue[key];
+    if (currentValue === void 0 || currentValue === null) {
+      currentValue = {};
+      currentValue[key] = currentValue;
+    }
+  }
+  const lastKey = keys[keys.length - 1];
+  currentValue[lastKey] = value;
+}
+var objectOverrider = (defaultObj) => (obj) => {
+  const createBuilder = (overrides) => ({
+    with: (path, value) => createBuilder([...overrides, { path: `${path}`, value }]),
+    build: () => {
+      const clonedObject = structuredClone(obj ?? defaultObj);
+      for (const { path, value } of overrides) {
+        set(clonedObject, path, value);
+      }
+      return clonedObject;
+    }
+  });
+  return createBuilder([]);
+};
+
+// ../../lib/retry/strategy.ts
+function withRetry(fn, strategy, options) {
+  return {
+    run: async (...args) => {
+      let attempts = 0;
+      while (true) {
+        if (options?.abortSignal?.aborted) {
+          return {
+            state: "aborted",
+            reason: options.abortSignal.reason
+          };
+        }
+        attempts++;
+        let result;
+        try {
+          result = await fn(...args);
+          if (options?.shouldRetryOnResult === void 0 || !await options.shouldRetryOnResult(result)) {
+            return {
+              state: "completed",
+              result,
+              attempts
+            };
+          }
+        } catch (err) {
+          if (options?.shouldNotRetryOnError !== void 0 && await options.shouldNotRetryOnError(err)) {
+            throw err;
+          }
+        }
+        const retryParams = getRetryParams(attempts, strategy);
+        if (!retryParams.retriesLeft) {
+          return {
+            state: "timeout"
+          };
+        }
+        await delay(retryParams.delayMs, { abortSignal: options?.abortSignal });
+      }
+    }
+  };
+}
+function getRetryParams(attempts, strategy) {
+  const strategyType = strategy.type;
+  switch (strategyType) {
+    case "never":
+      return {
+        retriesLeft: false
+      };
+    case "fixed":
+      if (attempts >= strategy.maxAttempts) {
+        return {
+          retriesLeft: false
+        };
+      }
+      return {
+        retriesLeft: true,
+        delayMs: strategy.delayMs
+      };
+    case "exponential": {
+      if (attempts >= strategy.maxAttempts) {
+        return {
+          retriesLeft: false
+        };
+      }
+      const delayMs = strategy.baseDelayMs * (strategy.factor ?? 2) ** (attempts - 1);
+      return {
+        retriesLeft: true,
+        delayMs: Math.min(delayMs, strategy.maxDelayMs ?? Number.POSITIVE_INFINITY)
+      };
+    }
+    case "jittered": {
+      if (attempts >= strategy.maxAttempts) {
+        return {
+          retriesLeft: false
+        };
+      }
+      const base = strategy.baseDelayMs * (strategy.jitterFactor ?? 2) ** (attempts - 1);
+      const delayMs = Math.random() * base;
+      return {
+        retriesLeft: true,
+        delayMs: Math.min(delayMs, strategy.maxDelayMs ?? Number.POSITIVE_INFINITY)
+      };
+    }
+    default:
+      return strategyType;
+  }
+}
+
+// run/run-handle.ts
+import { INTERNAL } from "@aikirun/types/symbols";
+import {
+  WorkflowRunNotExecutableError
+} from "@aikirun/types/workflow-run";
+async function workflowRunHandle(client, runOrId, logger) {
+  const run = typeof runOrId !== "string" ? runOrId : (await client.api.workflowRun.getByIdV1({ id: runOrId })).run;
+  return new WorkflowRunHandleImpl(client.api, run, logger ?? client.logger.child({ "aiki.workflowRunId": run.id }));
+}
+var WorkflowRunHandleImpl = class {
+  constructor(api, _run, logger) {
+    this.api = api;
+    this._run = _run;
+    this.logger = logger;
+    this[INTERNAL] = {
+      transitionState: this.transitionState.bind(this),
+      transitionTaskState: this.transitionTaskState.bind(this),
+      assertExecutionAllowed: this.assertExecutionAllowed.bind(this)
+    };
+  }
+  [INTERNAL];
+  get run() {
+    return this._run;
+  }
+  async refresh() {
+    const { run: currentRun } = await this.api.workflowRun.getByIdV1({ id: this.run.id });
+    this._run = currentRun;
+  }
+  async wait(condition, options) {
+    if (options.abortSignal?.aborted) {
+      throw new Error("Wait operation aborted");
+    }
+    const delayMs = options.pollIntervalMs ?? 1e3;
+    const maxAttempts = Math.ceil(options.maxDurationMs / delayMs);
+    switch (condition.type) {
+      case "status": {
+        if (options.abortSignal !== void 0) {
+          const maybeResult2 = await withRetry(
+            async () => {
+              await this.refresh();
+              return this.run.state;
+            },
+            { type: "fixed", maxAttempts, delayMs },
+            {
+              abortSignal: options.abortSignal,
+              shouldRetryOnResult: (state) => Promise.resolve(state.status !== condition.status)
+            }
+          ).run();
+          if (maybeResult2.state === "timeout" || maybeResult2.state === "aborted") {
+            return { success: false, cause: maybeResult2.state };
+          }
+          return {
+            success: true,
+            state: maybeResult2.result
+          };
+        }
+        const maybeResult = await withRetry(
+          async () => {
+            await this.refresh();
+            return this.run.state;
+          },
+          { type: "fixed", maxAttempts, delayMs },
+          { shouldRetryOnResult: (state) => Promise.resolve(state.status !== condition.status) }
+        ).run();
+        if (maybeResult.state === "timeout") {
+          return { success: false, cause: maybeResult.state };
+        }
+        return {
+          success: true,
+          state: maybeResult.result
+        };
+      }
+      case "event": {
+        throw new Error("Event-based waiting is not yet implemented");
+      }
+      default:
+        return condition;
+    }
+  }
+  async cancel(reason) {
+    return this.transitionState({ status: "cancelled", reason });
+  }
+  async pause() {
+    return this.transitionState({ status: "paused", pausedAt: Date.now() });
+  }
+  async resume() {
+    return this.transitionState({ status: "scheduled", scheduledAt: Date.now(), reason: "resume" });
+  }
+  async transitionState(targetState) {
+    if (targetState.status === "scheduled" && (targetState.reason === "new" || targetState.reason === "resume") || targetState.status === "paused" || targetState.status === "cancelled") {
+      const { run: run2 } = await this.api.workflowRun.transitionStateV1({
+        type: "pessimistic",
+        id: this.run.id,
+        state: targetState
+      });
+      this._run = run2;
+      return;
+    }
+    const { run } = await this.api.workflowRun.transitionStateV1({
+      type: "optimistic",
+      id: this.run.id,
+      state: targetState,
+      expectedRevision: this.run.revision
+    });
+    this._run = run;
+  }
+  async transitionTaskState(taskPath, taskState) {
+    const { run } = await this.api.workflowRun.transitionTaskStateV1({
+      id: this.run.id,
+      taskPath,
+      taskState,
+      expectedRevision: this.run.revision
+    });
+    this._run = run;
+  }
+  assertExecutionAllowed() {
+    const status = this.run.state.status;
+    if (status !== "queued" && status !== "running") {
+      throw new WorkflowRunNotExecutableError(this.run.id, status);
+    }
+  }
+};
+
+// run/sleeper.ts
+import { INTERNAL as INTERNAL2 } from "@aikirun/types/symbols";
+import { WorkflowRunSuspendedError } from "@aikirun/types/workflow-run";
+var MAX_SLEEP_YEARS = 10;
+var MAX_SLEEP_MS = MAX_SLEEP_YEARS * 365 * 24 * 60 * 60 * 1e3;
+function createWorkflowRunSleeper(workflowRunHandle2, logger, options) {
+  return async (params) => {
+    const { id: sleepId, ...durationFields } = params;
+    const durationMs = toMilliseconds(durationFields);
+    if (durationMs > MAX_SLEEP_MS) {
+      throw new Error(`Sleep duration ${durationMs}ms exceeds maximum of ${MAX_SLEEP_YEARS} years`);
+    }
+    const sleepPath = `${sleepId}/${durationMs}`;
+    const sleepState = workflowRunHandle2.run.sleepsState[sleepPath] ?? { status: "none" };
+    if (sleepState.status === "completed") {
+      logger.debug("Sleep completed", {
+        "aiki.sleepId": sleepId,
+        "aiki.durationMs": durationMs
+      });
+      return { cancelled: false };
+    }
+    if (sleepState.status === "cancelled") {
+      logger.debug("Sleep cancelled", {
+        "aiki.sleepId": sleepId,
+        "aiki.durationMs": durationMs
+      });
+      return { cancelled: true };
+    }
+    if (sleepState.status === "sleeping") {
+      logger.debug("Already sleeping", {
+        "aiki.sleepId": sleepId,
+        "aiki.durationMs": durationMs
+      });
+      throw new WorkflowRunSuspendedError(workflowRunHandle2.run.id);
+    }
+    sleepState;
+    if (durationMs <= options.spinThresholdMs) {
+      logger.debug("Spinning for short sleep", {
+        "aiki.sleepId": sleepId,
+        "aiki.durationMs": durationMs
+      });
+      await delay(durationMs);
+      return { cancelled: false };
+    }
+    await workflowRunHandle2[INTERNAL2].transitionState({ status: "sleeping", sleepPath, durationMs });
+    logger.info("Workflow going to sleep", {
+      "aiki.sleepId": sleepId,
+      "aiki.durationMs": durationMs
+    });
+    throw new WorkflowRunSuspendedError(workflowRunHandle2.run.id);
+  };
+}
+
+// workflow.ts
+import { INTERNAL as INTERNAL4 } from "@aikirun/types/symbols";
+
+// workflow-version.ts
+import { INTERNAL as INTERNAL3 } from "@aikirun/types/symbols";
+import { TaskFailedError } from "@aikirun/types/task";
+import {
+  WorkflowRunFailedError,
+  WorkflowRunSuspendedError as WorkflowRunSuspendedError2
+} from "@aikirun/types/workflow-run";
+var WorkflowVersionImpl = class _WorkflowVersionImpl {
+  constructor(id, versionId, params) {
+    this.id = id;
+    this.versionId = versionId;
+    this.params = params;
+    this[INTERNAL3] = {
+      handler: this.handler.bind(this)
+    };
+  }
+  [INTERNAL3];
+  with() {
+    const optsOverrider = objectOverrider(this.params.opts ?? {});
+    const createBuilder = (optsBuilder) => ({
+      opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
+      start: (client, ...args) => new _WorkflowVersionImpl(this.id, this.versionId, { ...this.params, opts: optsBuilder.build() }).start(
+        client,
+        ...args
+      )
+    });
+    return createBuilder(optsOverrider());
+  }
+  async start(client, ...args) {
+    const { run } = await client.api.workflowRun.createV1({
+      workflowId: this.id,
+      workflowVersionId: this.versionId,
+      input: isNonEmptyArray(args) ? args[0] : null,
+      options: this.params.opts
+    });
+    return workflowRunHandle(client, run);
+  }
+  async handler(input, run, context) {
+    const { logger } = run;
+    const { handle } = run[INTERNAL3];
+    handle[INTERNAL3].assertExecutionAllowed();
+    const retryStrategy = this.params.opts?.retry ?? { type: "never" };
+    const state = handle.run.state;
+    if (state.status === "queued" && state.reason === "retry") {
+      this.assertRetryAllowed(handle.run.id, handle.run.attempts, retryStrategy, logger);
+    }
+    logger.info("Starting workflow");
+    await handle[INTERNAL3].transitionState({ status: "running" });
+    const output = await this.tryExecuteWorkflow(input, run, context, retryStrategy);
+    await handle[INTERNAL3].transitionState({ status: "completed", output });
+    logger.info("Workflow complete");
+  }
+  async tryExecuteWorkflow(input, run, context, retryStrategy) {
+    while (true) {
+      try {
+        return await this.params.handler(input, run, context);
+      } catch (error) {
+        if (error instanceof WorkflowRunSuspendedError2) {
+          throw error;
+        }
+        const attempts = run[INTERNAL3].handle.run.attempts;
+        const retryParams = getRetryParams(attempts, retryStrategy);
+        if (!retryParams.retriesLeft) {
+          const failedState = this.createFailedState(error);
+          await run[INTERNAL3].handle[INTERNAL3].transitionState(failedState);
+          const logMeta2 = {};
+          for (const [key, value] of Object.entries(failedState)) {
+            logMeta2[`aiki.${key}`] = value;
+          }
+          run.logger.error("Workflow failed", {
+            "aiki.attempts": attempts,
+            ...logMeta2
+          });
+          throw new WorkflowRunFailedError(run.id, attempts, failedState.reason, failedState.cause);
+        }
+        const nextAttemptAt = Date.now() + retryParams.delayMs;
+        const awaitingRetryState = this.createAwaitingRetryState(error, nextAttemptAt);
+        await run[INTERNAL3].handle[INTERNAL3].transitionState(awaitingRetryState);
+        const logMeta = {};
+        for (const [key, value] of Object.entries(awaitingRetryState)) {
+          logMeta[`aiki.${key}`] = value;
+        }
+        run.logger.info("Workflow failed. Awaiting retry", {
+          "aiki.attempts": attempts,
+          "aiki.nextAttemptAt": nextAttemptAt,
+          "aiki.delayMs": retryParams.delayMs,
+          ...logMeta
+        });
+        throw new WorkflowRunSuspendedError2(run.id);
+      }
+    }
+  }
+  assertRetryAllowed(id, attempts, retryStrategy, logger) {
+    const retryParams = getRetryParams(attempts, retryStrategy);
+    if (!retryParams.retriesLeft) {
+      logger.error("Workflow retry not allowed", {
+        "aiki.attempts": attempts
+      });
+      throw new WorkflowRunFailedError(id, attempts, "Workflow retry not allowed");
+    }
+  }
+  createFailedState(error) {
+    if (error instanceof TaskFailedError) {
+      return {
+        status: "failed",
+        cause: "task",
+        taskPath: error.taskPath,
+        reason: error.reason
+      };
+    }
+    const serializableError = createSerializableError(error);
+    return {
+      status: "failed",
+      cause: "self",
+      reason: serializableError.message,
+      error: serializableError
+    };
+  }
+  createAwaitingRetryState(error, nextAttemptAt) {
+    if (error instanceof TaskFailedError) {
+      return {
+        status: "awaiting_retry",
+        cause: "task",
+        reason: error.reason,
+        nextAttemptAt,
+        taskPath: error.taskPath
+      };
+    }
+    const serializableError = createSerializableError(error);
+    return {
+      status: "awaiting_retry",
+      cause: "self",
+      reason: serializableError.message,
+      nextAttemptAt,
+      error: serializableError
+    };
+  }
+};
+
+// workflow.ts
+function workflow(params) {
+  return new WorkflowImpl(params);
+}
+var WorkflowImpl = class {
+  id;
+  [INTERNAL4];
+  workflowVersions = /* @__PURE__ */ new Map();
+  constructor(params) {
+    this.id = params.id;
+    this[INTERNAL4] = {
+      getAllVersions: this.getAllVersions.bind(this),
+      getVersion: this.getVersion.bind(this)
+    };
+  }
+  v(versionId, params) {
+    if (this.workflowVersions.has(versionId)) {
+      throw new Error(`Workflow "${this.id}/${versionId}" already exists`);
+    }
+    const workflowVersion = new WorkflowVersionImpl(this.id, versionId, params);
+    this.workflowVersions.set(
+      versionId,
+      workflowVersion
+    );
+    return workflowVersion;
+  }
+  getAllVersions() {
+    return Array.from(this.workflowVersions.values());
+  }
+  getVersion(versionId) {
+    return this.workflowVersions.get(versionId);
+  }
+};
+export {
+  WorkflowVersionImpl,
+  createWorkflowRunSleeper,
+  workflow,
+  workflowRegistry,
+  workflowRunHandle
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@aikirun/workflow",
+	"version": "0.5.3",
+	"description": "Workflow SDK for Aiki - define durable workflows with tasks, sleeps, waits, and event handling",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup"
+	},
+	"dependencies": {
+		"@aikirun/types": "0.5.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "Apache-2.0"
+}