@voyantjs/workflows 0.0.0

package/src/handler/index.ts

@@ -0,0 +1,361 @@
+// @voyantjs/workflows/handler
+//
+// The tenant side of the runtime protocol (see docs/runtime-protocol.md §2).
+// The orchestrator invokes `POST /__voyant/workflow-step`; the tenant
+// Worker responds by running the workflow body once (one invocation of
+// the executor) and returning the executor response as JSON.
+//
+//   export default { fetch: createStepHandler() }
+//
+// is enough to make a tenant Worker protocol-conformant. Auth is
+// optional at the SDK level: in production, wire the HMAC verifier
+// bundled by `voyant build`; for local dev, leave it unset.
+//
+// The executor's native response shape is returned verbatim — the wire
+// document calls for compensated/compensation_failed to be folded into
+// "failed" for the first draft, but since the draft is not yet locked
+// and the executor-shape already round-trips losslessly, we keep the
+// full discriminated union here. The orchestrator adapter can collapse.
+
+import { executeWorkflowStep, type ExecuteWorkflowStepRequest, type ExecuteWorkflowStepResponse, type StepRunner } from "../runtime/executor.js";
+
+export { executeWorkflowStep };
+export type { StepRunner, ExecuteWorkflowStepRequest, ExecuteWorkflowStepResponse };
+export type { StepJournalEntry } from "../runtime/journal.js";
+import type { JournalSlice, StepJournalEntry } from "../runtime/journal.js";
+import type { RuntimeEnvironment } from "../runtime/ctx.js";
+import { getWorkflow } from "../workflow.js";
+import type { RunTrigger } from "../types.js";
+import type { RateLimiter } from "../rate-limit/index.js";
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../protocol/index.js";
+
+export interface StepHandlerDeps {
+  /**
+   * Optional. Called before parsing the body. Should throw / reject
+   * if the request is not from a trusted orchestrator. In production
+   * this verifies the `X-Voyant-Dispatch-Auth` HMAC against a public
+   * key embedded by `voyant build`.
+   */
+  verifyRequest?: (req: Request) => void | Promise<void>;
+  /** Injectable clock. Defaults to Date.now. */
+  now?: () => number;
+  /** Optional structured logger. */
+  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+  /**
+   * Rate limiter shared across step invocations. Required when any
+   * registered workflow declares `options.rateLimit` on a step; see
+   * `createInMemoryRateLimiter` in `@voyantjs/workflows/rate-limit` for
+   * the reference impl. One instance per Worker process is the
+   * intended cardinality — state is kept in the limiter's closure.
+   */
+  rateLimiter?: RateLimiter;
+  /**
+   * Runner for steps declared with `options.runtime === "node"`.
+   * Leave unset for handlers that only run edge steps; any node step
+   * will then fail with `NODE_RUNTIME_UNAVAILABLE`.
+   *
+   * Typical impl dispatches to a separate sandboxed context:
+   *   - Local dev: an in-process passthrough (same Node process).
+   *   - CF production: a Cloudflare Container binding, via
+   *     `createCfContainerStepRunner` from `@voyantjs/workflows-orchestrator-cloudflare`.
+   *
+   * This is bring-your-own because the right dispatch shape depends on
+   * the target runtime; the executor only cares that a runner exists.
+   */
+  nodeStepRunner?: StepRunner;
+}
+
+/** The HTTP request body the orchestrator sends. */
+export interface WorkflowStepRequest {
+  protocolVersion: ProtocolVersion;
+  runId: string;
+  workflowId: string;
+  workflowVersion: string;
+  invocationCount: number;
+  input: unknown;
+  journal: JournalSlice;
+  environment: "production" | "preview" | "development";
+  deadline: number;
+  tenantMeta: {
+    tenantId: string;
+    projectId: string;
+    organizationId: string;
+    projectSlug?: string;
+    organizationSlug?: string;
+  };
+  runMeta: {
+    number: number;
+    attempt: number;
+    triggeredBy: RunTrigger;
+    tags: string[];
+    startedAt: number;
+  };
+}
+
+/** The JSON response body the tenant returns. */
+export type WorkflowStepResponse = ExecuteWorkflowStepResponse;
+
+/** Error-response envelope used for HTTP 4xx/5xx. */
+export interface StepHandlerError {
+  error: string;
+  message: string;
+  details?: unknown;
+}
+
+/** Build an HTTP fetch-style handler. */
+export function createStepHandler(
+  deps: StepHandlerDeps = {},
+): (req: Request) => Promise<Response> {
+  return async (req) => {
+    if (req.method !== "POST") {
+      return jsonResponse(405, errorBody("method_not_allowed", "POST required"));
+    }
+    try {
+      if (deps.verifyRequest) await deps.verifyRequest(req);
+    } catch (err) {
+      deps.logger?.("warn", "step handler: auth rejected", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return jsonResponse(401, errorBody("unauthorized", errMessage(err)));
+    }
+    let raw: unknown;
+    try {
+      raw = await req.json();
+    } catch (err) {
+      return jsonResponse(400, errorBody("invalid_json", errMessage(err)));
+    }
+    // The incoming Request carries its own AbortSignal; threading it
+    // through lets `ctx.signal` observe client-side aborts (orchestrator
+    // cancellations, closed fetches, etc.) during step execution.
+    const out = await runStepInner(raw, deps, { signal: req.signal });
+    return jsonResponse(out.status, out.body);
+  };
+}
+
+/** Per-invocation options available to callers of the transport-free entry point. */
+export interface StepRequestOptions {
+  /** AbortSignal forwarded to `ctx.signal` inside the step body. */
+  signal?: AbortSignal;
+  /**
+   * Fires synchronously from `ctx.stream.*` as each chunk is produced.
+   * Used by orchestrators that want to broadcast chunks live
+   * (dashboards, queues) before the invocation returns.
+   */
+  onStreamChunk?: (
+    chunk: import("../runtime/executor.js").StreamChunk,
+  ) => void;
+}
+
+/**
+ * Transport-free entry point. Callers that already parsed the body
+ * (e.g. local orchestrator in-memory, tests) invoke this directly.
+ * Returns either the step response or an error envelope with the HTTP
+ * status the caller should use.
+ */
+export async function handleStepRequest(
+  raw: unknown,
+  deps: StepHandlerDeps = {},
+  opts: StepRequestOptions = {},
+): Promise<
+  | { status: number; body: WorkflowStepResponse }
+  | { status: number; body: StepHandlerError }
+> {
+  return runStepInner(raw, deps, opts);
+}
+
+async function runStepInner(
+  raw: unknown,
+  deps: StepHandlerDeps,
+  opts: StepRequestOptions = {},
+): Promise<
+  | { status: number; body: WorkflowStepResponse }
+  | { status: number; body: StepHandlerError }
+> {
+  const parsed = parseRequest(raw);
+  if (!parsed.ok) return { status: 400, body: errorBody("invalid_request", parsed.message) };
+
+  const reqBody = parsed.value;
+  if (reqBody.protocolVersion !== PROTOCOL_VERSION) {
+    return {
+      status: 426,
+      body: errorBody(
+        "protocol_version_mismatch",
+        `tenant supports protocol ${PROTOCOL_VERSION}, got ${String(reqBody.protocolVersion)}`,
+      ),
+    };
+  }
+
+  const def = getWorkflow(reqBody.workflowId);
+  if (!def) {
+    return {
+      status: 404,
+      body: errorBody("workflow_not_found", `workflow "${reqBody.workflowId}" is not registered in this bundle`),
+    };
+  }
+
+  const now = deps.now ?? (() => Date.now());
+  const stepRunner = createInProcessStepRunner(now);
+
+  const runtimeEnv: RuntimeEnvironment = {
+    run: {
+      id: reqBody.runId,
+      number: reqBody.runMeta.number,
+      attempt: reqBody.runMeta.attempt,
+      triggeredBy: reqBody.runMeta.triggeredBy,
+      tags: reqBody.runMeta.tags,
+      startedAt: reqBody.runMeta.startedAt,
+    },
+    workflow: { id: reqBody.workflowId, version: reqBody.workflowVersion },
+    environment: { name: reqBody.environment },
+    project: {
+      id: reqBody.tenantMeta.projectId,
+      slug: reqBody.tenantMeta.projectSlug ?? reqBody.tenantMeta.projectId,
+    },
+    organization: {
+      id: reqBody.tenantMeta.organizationId,
+      slug: reqBody.tenantMeta.organizationSlug ?? reqBody.tenantMeta.organizationId,
+    },
+  };
+
+  try {
+    const response = await executeWorkflowStep(def, {
+      runId: reqBody.runId,
+      workflowId: reqBody.workflowId,
+      workflowVersion: reqBody.workflowVersion,
+      input: reqBody.input,
+      journal: reqBody.journal,
+      invocationCount: reqBody.invocationCount,
+      environment: runtimeEnv,
+      triggeredBy: reqBody.runMeta.triggeredBy,
+      runStartedAt: reqBody.runMeta.startedAt,
+      tags: reqBody.runMeta.tags,
+      stepRunner,
+      nodeStepRunner: deps.nodeStepRunner,
+      rateLimiter: deps.rateLimiter,
+      now,
+      abortSignal: opts.signal,
+      onStreamChunk: opts.onStreamChunk,
+    });
+    return { status: 200, body: response };
+  } catch (err) {
+    deps.logger?.("error", "step handler: executor threw", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return {
+      status: 500,
+      body: errorBody("executor_error", errMessage(err)),
+    };
+  }
+}
+
+/**
+ * Build a step runner that executes the step body in the same
+ * process. Suitable for `runtime: "edge"`. Container-runtime steps
+ * will swap this for a dispatching runner that POSTs to a pod.
+ */
+function createInProcessStepRunner(now: () => number): StepRunner {
+  return async ({ stepId, attempt, fn, stepCtx }): Promise<StepJournalEntry> => {
+    const startedAt = now();
+    try {
+      const output = await fn(stepCtx);
+      return {
+        attempt,
+        status: "ok",
+        output,
+        startedAt,
+        finishedAt: now(),
+      };
+    } catch (err) {
+      const e = err as Error;
+      const code = typeof (err as { code?: unknown }).code === "string"
+        ? (err as { code: string }).code
+        : "UNKNOWN";
+      const retryAfter = (err as { retryAfter?: unknown }).retryAfter;
+      return {
+        attempt,
+        status: "err",
+        error: {
+          category: "USER_ERROR",
+          code,
+          message: e?.message ?? String(err),
+          name: e?.name,
+          stack: e?.stack,
+          data: retryAfter !== undefined ? { retryAfter } : undefined,
+        },
+        startedAt,
+        finishedAt: now(),
+      };
+    }
+  };
+}
+
+// ---- Parsing ----
+
+function parseRequest(
+  raw: unknown,
+): { ok: true; value: WorkflowStepRequest } | { ok: false; message: string } {
+  if (raw === null || typeof raw !== "object") {
+    return { ok: false, message: "body must be a JSON object" };
+  }
+  const r = raw as Record<string, unknown>;
+  const required: (keyof WorkflowStepRequest)[] = [
+    "protocolVersion",
+    "runId",
+    "workflowId",
+    "workflowVersion",
+    "invocationCount",
+    "journal",
+    "environment",
+    "deadline",
+    "tenantMeta",
+    "runMeta",
+  ];
+  for (const k of required) {
+    if (!(k in r)) return { ok: false, message: `missing required field "${k}"` };
+  }
+  if (typeof r.protocolVersion !== "number") {
+    return { ok: false, message: "`protocolVersion` must be a number" };
+  }
+  if (typeof r.runId !== "string" || r.runId.length === 0) {
+    return { ok: false, message: "`runId` must be a non-empty string" };
+  }
+  if (typeof r.workflowId !== "string" || r.workflowId.length === 0) {
+    return { ok: false, message: "`workflowId` must be a non-empty string" };
+  }
+  if (typeof r.invocationCount !== "number" || r.invocationCount < 1) {
+    return { ok: false, message: "`invocationCount` must be >= 1" };
+  }
+  if (!r.journal || typeof r.journal !== "object") {
+    return { ok: false, message: "`journal` must be an object" };
+  }
+  const env = r.environment;
+  if (env !== "production" && env !== "preview" && env !== "development") {
+    return { ok: false, message: "`environment` must be production | preview | development" };
+  }
+  if (!r.tenantMeta || typeof r.tenantMeta !== "object") {
+    return { ok: false, message: "`tenantMeta` must be an object" };
+  }
+  if (!r.runMeta || typeof r.runMeta !== "object") {
+    return { ok: false, message: "`runMeta` must be an object" };
+  }
+  return { ok: true, value: r as unknown as WorkflowStepRequest };
+}
+
+// ---- Helpers ----
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+}
+
+function errorBody(error: string, message: string, details?: unknown): StepHandlerError {
+  const out: StepHandlerError = { error, message };
+  if (details !== undefined) out.details = details;
+  return out;
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// @voyantjs/workflows
+//
+// Authoring SDK for Voyant Workflows. Full contract in:
+//   docs/sdk-surface.md §2–§8
+//   docs/design.md §3–§4
+
+export * from "./types.js";
+export * from "./workflow.js";
+export * from "./trigger.js";
+export * from "./conditions.js";
+export {
+  FatalError,
+  RetryableError,
+  TimeoutError,
+  HookConflictError,
+  QuotaExceededError,
+  ValidationError,
+} from "@voyantjs/workflows-errors";

package/src/protocol/index.ts

@@ -0,0 +1,133 @@
+// @voyantjs/workflows/protocol
+//
+// Wire-protocol types shared with the orchestrator. Full contract
+// in docs/runtime-protocol.md; types here are exported so callers
+// (test harness, adapters, dashboards) can build and inspect wire
+// payloads without reaching into runtime internals.
+
+export type ProtocolVersion = 1;
+export const PROTOCOL_VERSION: ProtocolVersion = 1;
+
+// Journal types: shape of the tenant-side view of a run's state.
+// Re-exported so orchestrators and tools can build/inspect journals
+// without reaching into the runtime subpath.
+export type {
+  JournalSlice,
+  StepJournalEntry,
+  WaitpointResolutionEntry,
+  CompensationJournalEntry,
+} from "../runtime/journal.js";
+
+export type ExecutionStatus =
+  | "CREATED"
+  | "QUEUED"
+  | "EXECUTING"
+  | "EXECUTING_WITH_WAITPOINTS"
+  | "SUSPENDED"
+  | "PENDING_CANCEL"
+  | "FINISHED";
+
+export type WaitpointKind = "DATETIME" | "EVENT" | "SIGNAL" | "RUN" | "MANUAL";
+
+export interface SerializedError {
+  category: "USER_ERROR" | "RUNTIME_ERROR";
+  code: string;
+  message: string;
+  name?: string;
+  stack?: string;
+  cause?: SerializedError;
+  data?: Record<string, unknown>;
+}
+
+export type PayloadLocation = "INLINE" | "EXTERNAL";
+
+export interface WorkflowManifest {
+  schemaVersion: 1;
+  projectId: string;
+  versionId: string;
+  builtAt: number;
+  builderVersion: string;
+  capabilities: string[];
+  workflows: WorkflowManifestEntry[];
+  eventFilters: EventFilterManifestEntry[];
+  bindings: Record<string, { type: "d1" | "r2" | "kv" | "queue"; name: string }>;
+  environments: Record<string, { customDomain?: string }>;
+}
+
+export interface WorkflowManifestEntry {
+  id: string;
+  version: string;
+  inputSchema?: unknown;
+  outputSchema?: unknown;
+  steps: ManifestStep[];
+  schedules: ManifestSchedule[];
+  defaultRuntime: "edge" | "node";
+  hasCompensation: boolean;
+  sourceLocation: { file: string; line: number };
+}
+
+export interface ManifestStep {
+  id: string;
+  runtime: "edge" | "node";
+  hasCompensation: boolean;
+  sourceLocation: { file: string; line: number };
+}
+
+export interface ManifestSchedule {
+  cron?: string;
+  every?: string;
+  at?: string;
+  timezone?: string;
+  environments?: ("production" | "preview" | "development")[];
+  name?: string;
+}
+
+export interface EventFilterManifestEntry {
+  id: string;
+  eventType: string;
+  scope?: string;
+  matchExpression?: string;
+  payloadHash: string;
+  targetWorkflowId: string;
+}
+
+// WebSocket stream events — full union in docs/runtime-protocol.md §6.2.
+export type StreamEvent =
+  | { kind: "step.started"; eventId: string; at: number; stepId: string; runtime: "edge" | "node"; machine?: string }
+  | { kind: "step.ok"; eventId: string; at: number; stepId: string; attempt: number; durationMs: number; output?: unknown }
+  | { kind: "step.err"; eventId: string; at: number; stepId: string; attempt: number; error: SerializedError }
+  | { kind: "step.skipped"; eventId: string; at: number; stepId: string; reason: string }
+  | { kind: "step.compensated"; eventId: string; at: number; stepId: string; status: "ok" | "err"; error?: SerializedError }
+  | { kind: "waitpoint.registered"; eventId: string; at: number; waitpointId: string; waitpointKind: WaitpointKind; meta: Record<string, unknown> }
+  | { kind: "waitpoint.resolved"; eventId: string; at: number; waitpointId: string; payload?: unknown; source: "live" | "inbox" | "replay" }
+  | { kind: "metadata.changed"; eventId: string; at: number; metadata: Record<string, unknown> }
+  | { kind: "stream.chunk"; eventId: string; at: number; streamId: string; chunk: unknown; encoding: "json" | "text" | "base64"; final: boolean }
+  | { kind: "log"; eventId: string; at: number; level: "info" | "warn" | "error"; message: string; stepId?: string; data?: object }
+  | { kind: "version.rebased"; eventId: string; at: number; fromVersion: string; toVersion: string }
+  | { kind: "run.cancelled"; eventId: string; at: number; reason?: string }
+  | { kind: "run.finished"; eventId: string; at: number; status: string; output?: unknown; error?: SerializedError };
+
+// Shared envelope for journal events written by the orchestrator,
+// the tenant worker, or a node-runtime container. Concrete `kind`
+// discriminants are owned by the emitting layer.
+export interface JournalEventEnvelope<TKind extends string = string, TData = unknown> {
+  eventId: string;
+  runId: string;
+  createdAt: number;
+  kind: TKind;
+  data: TData;
+  snapshotId?: string;
+  writtenBy: "orchestrator" | "tenant" | "node";
+}
+
+export interface PublicAccessTokenClaims {
+  sub: "pat";
+  tenantId: string;
+  environment: "production" | "preview" | "development";
+  scope: ("read" | "trigger" | "cancel")[];
+  target:
+    | { kind: "run"; runId: string }
+    | { kind: "workflow"; workflowId: string }
+    | { kind: "tag"; tag: string };
+  exp: number;
+}

package/src/rate-limit/index.ts

@@ -0,0 +1,182 @@
+// @voyantjs/workflows/rate-limit
+//
+// Reference rate limiter used by `ctx.step({ rateLimit: ... })`.
+//
+// A RateLimiter is a small interface: `acquire()` blocks (or throws,
+// depending on `onLimit`) until `units` are available under `key` for
+// a sliding window of `windowMs`. One shared limiter instance lives
+// per tenant Worker process — callers wire it into `createStepHandler`
+// via `{ rateLimiter: createInMemoryRateLimiter() }`.
+//
+// The in-memory impl is a token bucket: `capacity = limit`, refill
+// rate = `limit / windowMs`. It's suitable for local dev and
+// single-process deployments. Multi-region / sharded deployments
+// should swap in a Durable-Object or Redis-backed implementation that
+// shares state across isolates.
+
+import type { Duration } from "../types.js";
+
+export interface AcquireArgs {
+  /** Bucket key — usually a tenant id, a url host, a user id, etc. */
+  key: string;
+  /** Maximum units the bucket can hold. */
+  limit: number;
+  /** Units the current call consumes. */
+  units: number;
+  /** Refill window in ms. `limit` tokens per `windowMs`. */
+  windowMs: number;
+  /** `queue` → wait until capacity; `fail` → throw immediately. */
+  onLimit: "queue" | "fail";
+  /** Forwarded from the run; limiter observes aborts during queue waits. */
+  signal?: AbortSignal;
+}
+
+export interface RateLimiter {
+  acquire(args: AcquireArgs): Promise<void>;
+}
+
+/** Error thrown when `onLimit === "fail"` and the bucket is empty. */
+export class RateLimitExceededError extends Error {
+  readonly code = "RATE_LIMITED";
+  readonly retryAfterMs: number;
+  constructor(key: string, retryAfterMs: number) {
+    super(`rate limit exceeded for key "${key}" (retry after ${retryAfterMs}ms)`);
+    this.name = "RateLimitExceededError";
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+interface Bucket {
+  tokens: number;
+  capacity: number;
+  refillPerMs: number;
+  lastRefillAt: number;
+}
+
+export interface InMemoryLimiterOptions {
+  /** Injectable clock, ms since epoch. Defaults to Date.now. */
+  now?: () => number;
+  /** Injectable delay; defaults to setTimeout. Tests override this. */
+  delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/**
+ * Token-bucket rate limiter held in-process. Independent buckets per
+ * `key`; bucket parameters (`capacity`, `refillPerMs`) come from the
+ * `limit` / `windowMs` of the first `acquire` call and are updated on
+ * subsequent calls that change them.
+ */
+export function createInMemoryRateLimiter(
+  opts: InMemoryLimiterOptions = {},
+): RateLimiter {
+  const now = opts.now ?? (() => Date.now());
+  const delay = opts.delay ?? defaultDelay;
+  const buckets = new Map<string, Bucket>();
+
+  return {
+    async acquire(args) {
+      if (args.units <= 0) return;
+      if (args.limit <= 0) {
+        throw new Error(
+          `rate-limit: "limit" must be > 0 (got ${args.limit}) for key "${args.key}"`,
+        );
+      }
+      if (args.windowMs <= 0) {
+        throw new Error(
+          `rate-limit: "windowMs" must be > 0 (got ${args.windowMs}) for key "${args.key}"`,
+        );
+      }
+      if (args.units > args.limit) {
+        // The step will never be admissible — short-circuit regardless
+        // of onLimit to avoid hanging indefinitely under queue mode.
+        throw new Error(
+          `rate-limit: units (${args.units}) > limit (${args.limit}) for key "${args.key}" — step can never be admitted`,
+        );
+      }
+
+      while (true) {
+        const bucket = refill(buckets, args, now());
+        if (bucket.tokens >= args.units) {
+          bucket.tokens -= args.units;
+          return;
+        }
+        const missing = args.units - bucket.tokens;
+        const waitMs = Math.ceil(missing / bucket.refillPerMs);
+        if (args.onLimit === "fail") {
+          throw new RateLimitExceededError(args.key, waitMs);
+        }
+        await delay(waitMs, args.signal);
+        if (args.signal?.aborted) {
+          throw args.signal.reason ?? new Error("rate-limit: aborted while queued");
+        }
+      }
+    },
+  };
+}
+
+function refill(
+  buckets: Map<string, Bucket>,
+  args: AcquireArgs,
+  nowMs: number,
+): Bucket {
+  const refillPerMs = args.limit / args.windowMs;
+  let b = buckets.get(args.key);
+  if (!b) {
+    b = {
+      tokens: args.limit,
+      capacity: args.limit,
+      refillPerMs,
+      lastRefillAt: nowMs,
+    };
+    buckets.set(args.key, b);
+    return b;
+  }
+  // Re-parameterize if the caller changed limit / windowMs. Clamp
+  // tokens to the new capacity so a shrink doesn't leave stale excess.
+  if (b.capacity !== args.limit || b.refillPerMs !== refillPerMs) {
+    b.capacity = args.limit;
+    b.refillPerMs = refillPerMs;
+    if (b.tokens > b.capacity) b.tokens = b.capacity;
+  }
+  const elapsed = Math.max(0, nowMs - b.lastRefillAt);
+  if (elapsed > 0) {
+    b.tokens = Math.min(b.capacity, b.tokens + elapsed * b.refillPerMs);
+    b.lastRefillAt = nowMs;
+  }
+  return b;
+}
+
+function defaultDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Normalize a Duration to milliseconds. Same units as `toMs` in ctx.ts. */
+export function durationToMs(d: Duration): number {
+  if (typeof d === "number") return d;
+  const m = /^(\d+)(ms|s|m|h|d|w)$/.exec(d);
+  if (!m) throw new Error(`rate-limit: invalid duration "${d}"`);
+  const n = Number(m[1]);
+  switch (m[2]) {
+    case "ms": return n;
+    case "s": return n * 1_000;
+    case "m": return n * 60_000;
+    case "h": return n * 3_600_000;
+    case "d": return n * 86_400_000;
+    case "w": return n * 604_800_000;
+    default: throw new Error(`rate-limit: invalid duration "${d}"`);
+  }
+}