@redflow/client 0.0.1

package/src/client.ts

@@ -0,0 +1,1111 @@
+import { RedisClient, redis as defaultRedis } from "bun";
+import { createHash } from "node:crypto";
+import { Cron } from "croner";
+import type { ZodTypeAny } from "zod";
+import {
+  CanceledError,
+  InputValidationError,
+  NonRetriableError,
+  OutputSerializationError,
+  TimeoutError,
+  UnknownWorkflowError,
+  serializeError,
+  type SerializedError,
+} from "./internal/errors";
+import { keys } from "./internal/keys";
+import { safeJsonParse, safeJsonStringify, safeJsonTryParse } from "./internal/json";
+import { nowMs } from "./internal/time";
+import { sleep } from "./internal/sleep";
+import type {
+  EmitEventOptions,
+  ListedRun,
+  ListRunsParams,
+  RunHandle,
+  RunOptions,
+  ScheduleEventOptions,
+  RunState,
+  RunStatus,
+  StepState,
+  WorkflowMeta,
+} from "./types";
+import type { WorkflowRegistry } from "./registry";
+
+export type CreateClientOptions = {
+  redis?: RedisClient;
+  url?: string;
+  prefix?: string;
+};
+
+export type SyncRegistryOptions = {
+  /**
+   * Workflows are pruned only when they were last synced by the same owner.
+   * Set a stable service id (for example, app name) to enable safe stale cleanup.
+   */
+  owner?: string;
+};
+
+export function defaultPrefix(): string {
+  return process.env.REDFLOW_PREFIX || "redflow:v1";
+}
+
+const STALE_WORKFLOW_GRACE_MS = 30_000;
+const IDEMPOTENCY_TTL_SEC = 60 * 60 * 24 * 7;
+
+const ENQUEUE_RUN_LUA = `
+local runId = ARGV[1]
+local workflowName = ARGV[2]
+local queue = ARGV[3]
+local status = ARGV[4]
+local inputJson = ARGV[5]
+local createdAt = ARGV[6]
+local availableAt = ARGV[7]
+local maxAttempts = ARGV[8]
+local hasIdempotency = ARGV[9] == "1"
+local idempotencyTtlSec = ARGV[10]
+local runKeyPrefix = ARGV[11]
+
+if hasIdempotency then
+  local existingRunId = redis.call("get", KEYS[7])
+  if existingRunId and existingRunId ~= "" then
+    local existingStatus = redis.call("hget", runKeyPrefix .. existingRunId, "status")
+    if existingStatus then
+      redis.call("expire", KEYS[7], idempotencyTtlSec)
+      return { "existing", existingRunId }
+    end
+  end
+
+  redis.call("set", KEYS[7], runId, "EX", idempotencyTtlSec)
+end
+
+redis.call("hset", KEYS[1],
+  "workflow", workflowName,
+  "queue", queue,
+  "status", status,
+  "inputJson", inputJson,
+  "attempt", "0",
+  "maxAttempts", maxAttempts,
+  "createdAt", createdAt,
+  "availableAt", availableAt,
+  "cancelRequestedAt", "",
+  "cancelReason", ""
+)
+
+redis.call("zadd", KEYS[2], createdAt, runId)
+redis.call("zadd", KEYS[3], createdAt, runId)
+redis.call("zadd", KEYS[4], createdAt, runId)
+
+if status == "scheduled" then
+  redis.call("zadd", KEYS[6], availableAt, runId)
+else
+  redis.call("lpush", KEYS[5], runId)
+end
+
+return { "created", runId }
+`;
+
+const TRANSITION_IF_CURRENT_STATUS_LUA = `
+if redis.call("hget", KEYS[1], "status") ~= ARGV[2] then
+  return 0
+end
+redis.call("zrem", KEYS[2], ARGV[1])
+redis.call("hset", KEYS[1], "status", ARGV[3])
+if ARGV[3] ~= "scheduled" then
+  redis.call("hdel", KEYS[1], "availableAt")
+end
+redis.call("zadd", KEYS[3], ARGV[4], ARGV[1])
+return 1
+`;
+
+// Atomic version of transitionRunStatus: reads current status, removes from
+// old status index, sets new status, clears availableAt if not "scheduled",
+// and adds to new status index — all in one round-trip.
+const TRANSITION_RUN_STATUS_LUA = `
+local runKey = KEYS[1]
+local newStatusIndexKey = KEYS[2]
+local runId = ARGV[1]
+local nextStatus = ARGV[2]
+local updatedAt = ARGV[3]
+local statusIndexPrefix = ARGV[4]
+
+local prev = redis.call("hget", runKey, "status")
+if prev and prev ~= "" then
+  local oldIndexKey = statusIndexPrefix .. prev
+  redis.call("zrem", oldIndexKey, runId)
+end
+
+redis.call("hset", runKey, "status", nextStatus)
+if nextStatus ~= "scheduled" then
+  redis.call("hdel", runKey, "availableAt")
+end
+redis.call("zadd", newStatusIndexKey, updatedAt, runId)
+return 1
+`;
+
+// Atomically: set availableAt + errorJson on run hash, transition status to
+// "scheduled" (cleaning old status index), and zadd into the queue's scheduled
+// sorted set. Prevents a run from being stranded if the worker crashes
+// mid-retry between transitionRunStatus and the zadd.
+const SCHEDULE_RETRY_LUA = `
+local runKey = KEYS[1]
+local newStatusIndexKey = KEYS[2]
+local queueScheduledKey = KEYS[3]
+local runId = ARGV[1]
+local updatedAt = ARGV[2]
+local nextAt = ARGV[3]
+local errorJson = ARGV[4]
+local statusIndexPrefix = ARGV[5]
+
+local prev = redis.call("hget", runKey, "status")
+if prev and prev ~= "" then
+  local oldIndexKey = statusIndexPrefix .. prev
+  redis.call("zrem", oldIndexKey, runId)
+end
+
+redis.call("hset", runKey, "status", "scheduled", "availableAt", nextAt, "errorJson", errorJson)
+redis.call("zadd", newStatusIndexKey, updatedAt, runId)
+redis.call("zadd", queueScheduledKey, nextAt, runId)
+return 1
+`;
+
+const REQUEST_CANCELLATION_LUA = `
+local status = redis.call("hget", KEYS[1], "status")
+if not status then
+  return "__missing__"
+end
+if status == "succeeded" or status == "failed" or status == "canceled" then
+  return status
+end
+redis.call("hset", KEYS[1], "cancelRequestedAt", ARGV[1], "cancelReason", ARGV[2])
+return status
+`;
+
+const FINALIZE_TERMINAL_RUN_LUA = `
+local status = redis.call("hget", KEYS[1], "status")
+if not status then
+  return "__missing__"
+end
+
+local runId = ARGV[1]
+local requestedStatus = ARGV[2]
+local finishedAt = ARGV[3]
+local outputJson = ARGV[4]
+local errorJson = ARGV[5]
+local hasOutput = ARGV[6] == "1"
+local hasError = ARGV[7] == "1"
+
+local nextStatus = requestedStatus
+if requestedStatus == "succeeded" or requestedStatus == "failed" then
+  local cancelRequestedAt = redis.call("hget", KEYS[1], "cancelRequestedAt")
+  if cancelRequestedAt and cancelRequestedAt ~= "" then
+    nextStatus = "canceled"
+  end
+end
+
+for i = 2, 7 do
+  redis.call("zrem", KEYS[i], runId)
+end
+
+redis.call("hdel", KEYS[1], "availableAt")
+
+if nextStatus == "succeeded" then
+  redis.call("hdel", KEYS[1], "errorJson")
+  if hasOutput then
+    redis.call("hset", KEYS[1], "outputJson", outputJson)
+  else
+    redis.call("hdel", KEYS[1], "outputJson")
+  end
+  redis.call("hset", KEYS[1], "cancelRequestedAt", "", "cancelReason", "")
+elseif nextStatus == "failed" then
+  redis.call("hdel", KEYS[1], "outputJson")
+  if hasError then
+    redis.call("hset", KEYS[1], "errorJson", errorJson)
+  else
+    redis.call("hdel", KEYS[1], "errorJson")
+  end
+  redis.call("hset", KEYS[1], "cancelRequestedAt", "", "cancelReason", "")
+else
+  redis.call("hdel", KEYS[1], "outputJson")
+  if hasError then
+    redis.call("hset", KEYS[1], "errorJson", errorJson)
+  else
+    redis.call("hdel", KEYS[1], "errorJson")
+  end
+end
+
+redis.call("hset", KEYS[1], "status", nextStatus, "finishedAt", finishedAt)
+
+if nextStatus == "succeeded" then
+  redis.call("zadd", KEYS[5], finishedAt, runId)
+elseif nextStatus == "failed" then
+  redis.call("zadd", KEYS[6], finishedAt, runId)
+else
+  redis.call("zadd", KEYS[7], finishedAt, runId)
+end
+
+return nextStatus
+`;
+
+function encodeCompositePart(value: string): string {
+  return `${value.length}:${value}`;
+}
+
+function eventScopedIdempotencyKey(eventName: string, idempotencyKey: string): string {
+  return `event:${encodeCompositePart(eventName)}:${encodeCompositePart(idempotencyKey)}`;
+}
+
+function defaultRegistryOwner(): string {
+  const envOwner = process.env.REDFLOW_SYNC_OWNER?.trim();
+  if (envOwner) return envOwner;
+
+  const argvOwner = process.argv[1]?.trim();
+  if (argvOwner) return argvOwner;
+
+  return "redflow:unknown-owner";
+}
+
+function parseEnqueueScriptResult(value: unknown): { kind: "created" | "existing"; runId: string } | null {
+  if (Array.isArray(value) && value.length === 1 && Array.isArray(value[0])) {
+    return parseEnqueueScriptResult(value[0]);
+  }
+
+  if (!Array.isArray(value) || value.length < 2) return null;
+
+  const kind = value[0];
+  const runId = value[1];
+  if ((kind !== "created" && kind !== "existing") || typeof runId !== "string" || runId === "") {
+    return null;
+  }
+
+  return { kind, runId };
+}
+
+function parseScanResult(value: unknown): { cursor: string; keys: string[] } | null {
+  if (Array.isArray(value) && value.length === 1 && Array.isArray(value[0])) {
+    return parseScanResult(value[0]);
+  }
+
+  if (!Array.isArray(value) || value.length < 2) return null;
+
+  const cursorRaw = value[0];
+  const keysRaw = value[1];
+  const cursor =
+    typeof cursorRaw === "string" ? cursorRaw : typeof cursorRaw === "number" ? String(Math.floor(cursorRaw)) : null;
+  if (!cursor || !Array.isArray(keysRaw)) return null;
+
+  const keys: string[] = [];
+  for (const item of keysRaw) {
+    if (typeof item === "string" && item) keys.push(item);
+  }
+
+  return { cursor, keys };
+}
+
+function parseRedisInteger(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) return Math.max(0, Math.floor(value));
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return Math.max(0, Math.floor(parsed));
+  }
+  return 0;
+}
+
+function isValidDate(value: Date): boolean {
+  return value instanceof Date && Number.isFinite(value.getTime());
+}
+
+export class RedflowClient {
+  constructor(
+    public readonly redis: RedisClient,
+    public readonly prefix: string,
+  ) {}
+
+  async close(): Promise<void> {
+    this.redis.close();
+  }
+
+  async resetState(): Promise<{ deleted: number }> {
+    const normalizedPrefix = this.prefix.endsWith(":") ? this.prefix.slice(0, -1) : this.prefix;
+    const pattern = `${normalizedPrefix}:*`;
+    let cursor = "0";
+    let deleted = 0;
+
+    while (true) {
+      const scanned = parseScanResult(await this.redis.send("SCAN", [cursor, "MATCH", pattern, "COUNT", "500"]));
+      if (!scanned) {
+        throw new Error("Unexpected Redis SCAN response while resetting state");
+      }
+
+      cursor = scanned.cursor;
+      if (scanned.keys.length > 0) {
+        deleted += parseRedisInteger(await this.redis.send("UNLINK", scanned.keys));
+      }
+
+      if (cursor === "0") break;
+    }
+
+    deleted += parseRedisInteger(await this.redis.send("UNLINK", [normalizedPrefix]));
+
+    return { deleted };
+  }
+
+  async listWorkflows(): Promise<string[]> {
+    return await this.redis.smembers(keys.workflows(this.prefix));
+  }
+
+  async getWorkflowMeta(name: string): Promise<WorkflowMeta | null> {
+    const data = await this.redis.hgetall(keys.workflow(this.prefix, name));
+    if (!data || Object.keys(data).length === 0) return null;
+
+    const triggers = safeJsonTryParse<any>(data.triggersJson ?? null) as any;
+    const retries = safeJsonTryParse<any>(data.retriesJson ?? null) as any;
+    const updatedAt = Number(data.updatedAt ?? "0");
+    const queue = data.queue ?? "default";
+    return {
+      name,
+      queue,
+      triggers,
+      retries,
+      updatedAt,
+    };
+  }
+
+  async emitEvent(name: string, payload: unknown, options?: EmitEventOptions): Promise<string[]> {
+    return await this.dispatchEvent(name, payload, {
+      idempotencyKey: options?.idempotencyKey,
+      idempotencyTtl: options?.idempotencyTtl,
+    });
+  }
+
+  async scheduleEvent(name: string, payload: unknown, options: ScheduleEventOptions): Promise<string[]> {
+    if (!options || !isValidDate(options.availableAt)) {
+      throw new Error("Invalid 'availableAt' for scheduleEvent");
+    }
+
+    return await this.dispatchEvent(name, payload, {
+      idempotencyKey: options.idempotencyKey,
+      idempotencyTtl: options.idempotencyTtl,
+      availableAt: options.availableAt,
+    });
+  }
+
+  private async dispatchEvent(
+    name: string,
+    payload: unknown,
+    options: { idempotencyKey?: string; idempotencyTtl?: number; availableAt?: Date },
+  ): Promise<string[]> {
+    const subsKey = keys.eventWorkflows(this.prefix, name);
+    const workflowNames = await this.redis.smembers(subsKey);
+    const runIds: string[] = [];
+
+    for (const workflowName of workflowNames) {
+      const idempotencyKey = options.idempotencyKey ? eventScopedIdempotencyKey(name, options.idempotencyKey) : undefined;
+      try {
+        const handle = await this.runByName(workflowName, payload, {
+          idempotencyKey,
+          idempotencyTtl: options.idempotencyTtl,
+          availableAt: options.availableAt,
+        });
+        runIds.push(handle.id);
+      } catch (err) {
+        if (err instanceof UnknownWorkflowError) {
+          // Stale event subscriptions can remain briefly across deployments.
+          // Drop them lazily so valid subscribers still receive events.
+          await this.redis.srem(subsKey, workflowName);
+          continue;
+        }
+        throw err;
+      }
+    }
+
+    return runIds;
+  }
+
+  async runByName<TOutput = unknown>(workflowName: string, input: unknown, options?: RunOptions): Promise<RunHandle<TOutput>> {
+    const queueFromRegistry = await this.getQueueForWorkflow(workflowName);
+    const queue = options?.queueOverride ?? queueFromRegistry;
+    if (!queue) {
+      throw new UnknownWorkflowError(workflowName);
+    }
+
+    const maxAttemptsOverride =
+      typeof options?.__maxAttemptsOverride === "number" &&
+      Number.isFinite(options.__maxAttemptsOverride) &&
+      options.__maxAttemptsOverride > 0
+        ? Math.floor(options.__maxAttemptsOverride)
+        : null;
+
+    const maxAttempts = maxAttemptsOverride ?? (await this.getMaxAttemptsForWorkflow(workflowName)) ?? 1;
+
+    return await this.enqueueRun<TOutput>({
+      workflowName,
+      queue,
+      input,
+      availableAt: options?.availableAt,
+      idempotencyKey: options?.idempotencyKey,
+      idempotencyTtl: options?.idempotencyTtl,
+      maxAttempts,
+    });
+  }
+
+  async cancelRun(runId: string, options?: { reason?: string }): Promise<boolean> {
+    const runKey = keys.run(this.prefix, runId);
+    const ts = nowMs();
+    const reason = options?.reason ?? "";
+
+    const requestedFrom = await this.requestCancellation(runId, ts, reason);
+    if (requestedFrom === "__missing__") {
+      return false;
+    }
+
+    if (requestedFrom === "succeeded" || requestedFrom === "failed" || requestedFrom === "canceled") {
+      return false;
+    }
+
+    if (requestedFrom === "running") {
+      // Cooperative cancellation for in-flight handlers.
+      return true;
+    }
+
+    const queue = (await this.redis.hget(runKey, "queue")) ?? "default";
+
+    const canceledNow = await this.transitionRunStatusIfCurrent(runId, requestedFrom, "canceled", ts);
+    if (canceledNow) {
+      await this.finalizeCanceledRunImmediately(runId, queue, ts);
+      return true;
+    }
+
+    // The status changed after we requested cancellation; retry immediate cancel if it's
+    // still not running/terminal, otherwise respect the latest terminal state.
+    const latestStatus = (await this.redis.hget(runKey, "status")) as RunStatus | null;
+    if (latestStatus === "queued" || latestStatus === "scheduled") {
+      const canceledLatest = await this.transitionRunStatusIfCurrent(runId, latestStatus, "canceled", ts);
+      if (canceledLatest) {
+        await this.finalizeCanceledRunImmediately(runId, queue, ts);
+        return true;
+      }
+    }
+
+    const finalStatus = (await this.redis.hget(runKey, "status")) as RunStatus | null;
+    if (finalStatus === "running") return true;
+    if (finalStatus === "queued" || finalStatus === "scheduled") return true;
+    if (finalStatus === "canceled") return true;
+    return false;
+  }
+
+  async getRun(runId: string): Promise<RunState | null> {
+    const runKey = keys.run(this.prefix, runId);
+    const data = await this.redis.hgetall(runKey);
+    if (!data || Object.keys(data).length === 0) return null;
+
+    const input = safeJsonParse(data.inputJson ?? "null");
+    const output = safeJsonTryParse(data.outputJson ?? null);
+    const error = safeJsonTryParse(data.errorJson ?? null);
+
+    return {
+      id: runId,
+      workflow: data.workflow ?? "",
+      queue: data.queue ?? "default",
+      status: (data.status as RunStatus) ?? "queued",
+      input,
+      output,
+      error,
+      attempt: Number(data.attempt ?? "0"),
+      maxAttempts: Number(data.maxAttempts ?? "1"),
+      createdAt: Number(data.createdAt ?? "0"),
+      availableAt: data.availableAt ? Number(data.availableAt) : undefined,
+      startedAt: data.startedAt ? Number(data.startedAt) : undefined,
+      finishedAt: data.finishedAt ? Number(data.finishedAt) : undefined,
+      cancelRequestedAt: data.cancelRequestedAt ? Number(data.cancelRequestedAt) : undefined,
+      cancelReason: data.cancelReason || undefined,
+    };
+  }
+
+  async getRunSteps(runId: string): Promise<StepState[]> {
+    const stepsKey = keys.runSteps(this.prefix, runId);
+    const data = await this.redis.hgetall(stepsKey);
+    const result: Array<{ order: number; step: StepState }> = [];
+
+    for (const [name, raw] of Object.entries(data)) {
+      const parsed = safeJsonParse<any>(raw);
+      const order = typeof parsed.seq === "number" ? parsed.seq : Number(parsed.startedAt ?? 0);
+      result.push({
+        order,
+        step: {
+          name,
+          status: parsed.status,
+          startedAt: parsed.startedAt,
+          finishedAt: parsed.finishedAt,
+          output: safeJsonTryParse(parsed.outputJson ?? null),
+          error: safeJsonTryParse(parsed.errorJson ?? null),
+        },
+      });
+    }
+
+    result.sort((a, b) => a.order - b.order);
+    return result.map((r) => r.step);
+  }
+
+  async listRuns(params?: ListRunsParams): Promise<ListedRun[]> {
+    const limitRaw = params?.limit ?? 50;
+    const offsetRaw = params?.offset ?? 0;
+    const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.floor(limitRaw)) : 50;
+    const offset = Number.isFinite(offsetRaw) ? Math.max(0, Math.floor(offsetRaw)) : 0;
+    const status = params?.status;
+    const workflow = params?.workflow;
+
+    if (status && workflow) {
+      const workflowIndexKey = keys.workflowRuns(this.prefix, workflow);
+      const result: ListedRun[] = [];
+      let cursor = 0;
+      let skipped = 0;
+      const batchSize = Math.max(100, limit * 2);
+
+      while (result.length < limit) {
+        const runIds = await this.redis.zrevrange(workflowIndexKey, cursor, cursor + batchSize - 1);
+        if (runIds.length === 0) break;
+        cursor += runIds.length;
+
+        for (const runId of runIds) {
+          const run = await this.getRun(runId);
+          if (!run || run.status !== status) continue;
+
+          if (skipped < offset) {
+            skipped += 1;
+            continue;
+          }
+
+          result.push(this.toListedRun(run));
+          if (result.length >= limit) break;
+        }
+      }
+
+      return result;
+    }
+
+    let indexKey = keys.runsCreated(this.prefix);
+    if (status) indexKey = keys.runsStatus(this.prefix, status);
+    if (workflow) indexKey = keys.workflowRuns(this.prefix, workflow);
+
+    const runIds = await this.redis.zrevrange(indexKey, offset, offset + limit - 1);
+    const runs: ListedRun[] = [];
+    for (const runId of runIds) {
+      const run = await this.getRun(runId);
+      if (!run) continue;
+      runs.push(this.toListedRun(run));
+    }
+    return runs;
+  }
+
+  makeRunHandle<TOutput = unknown>(runId: string): RunHandle<TOutput> {
+    return {
+      id: runId,
+      getState: () => this.getRun(runId),
+      result: (options) => this.waitForResult<TOutput>(runId, options),
+    };
+  }
+
+  async waitForResult<TOutput = unknown>(
+    runId: string,
+    options?: { timeoutMs?: number; pollMs?: number },
+  ): Promise<TOutput> {
+    const timeoutMs = options?.timeoutMs ?? 30_000;
+    const pollMs = options?.pollMs ?? 250;
+    const deadline = nowMs() + timeoutMs;
+    const missingGraceMs = Math.max(250, Math.min(2000, pollMs * 4));
+
+    let missingSince: number | null = null;
+    let seenState = false;
+
+    while (true) {
+      const state = await this.getRun(runId);
+      if (!state) {
+        const t = nowMs();
+        if (missingSince == null) missingSince = t;
+
+        if (t - missingSince >= missingGraceMs) {
+          if (seenState) {
+            throw new Error(`Run state unavailable: ${runId}`);
+          }
+          throw new Error(`Run not found: ${runId}`);
+        }
+
+        if (t > deadline) throw new TimeoutError(`Timed out waiting for run result (${runId})`);
+        await sleep(pollMs);
+        continue;
+      }
+
+      seenState = true;
+      missingSince = null;
+
+      if (state.status === "succeeded") return state.output as TOutput;
+      if (state.status === "failed") throw new Error(`Run failed: ${safeJsonStringify(state.error)}`);
+      if (state.status === "canceled") throw new CanceledError(state.cancelReason ? `Run canceled: ${state.cancelReason}` : "Run canceled");
+
+      if (nowMs() > deadline) throw new TimeoutError(`Timed out waiting for run result (${runId})`);
+      await sleep(pollMs);
+    }
+  }
+
+  async syncRegistry(registry: WorkflowRegistry, options?: SyncRegistryOptions): Promise<void> {
+    const defs = registry.list();
+    const syncStartedAt = nowMs();
+    const owner = options?.owner?.trim() || defaultRegistryOwner();
+    const registeredNames = new Set(defs.map((def) => def.options.name));
+
+    await this.cleanupStaleWorkflows(registeredNames, syncStartedAt, owner);
+
+    for (const def of defs) {
+      const name = def.options.name;
+      const queue = def.options.queue ?? "default";
+      const triggers = def.options.triggers ?? {};
+      const retries = def.options.retries ?? {};
+      const updatedAt = nowMs();
+
+      const customCronIds = new Set<string>();
+      for (const cron of triggers.cron ?? []) {
+        if (!cron.id) continue;
+        if (customCronIds.has(cron.id)) {
+          throw new Error(`Duplicate cron trigger id '${cron.id}' in workflow '${name}'`);
+        }
+        customCronIds.add(cron.id);
+      }
+
+      const workflowKey = keys.workflow(this.prefix, name);
+      await this.redis.sadd(keys.workflows(this.prefix), name);
+
+      const prevEvents = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "eventsJson")) ?? [];
+      const nextEvents = Array.from(new Set(triggers.events ?? [])).sort();
+
+      for (const ev of prevEvents) {
+        if (!nextEvents.includes(ev)) {
+          await this.redis.srem(keys.eventWorkflows(this.prefix, ev), name);
+        }
+      }
+
+      for (const ev of nextEvents) {
+        if (!prevEvents.includes(ev)) {
+          await this.redis.sadd(keys.eventWorkflows(this.prefix, ev), name);
+        }
+      }
+
+      const prevCronIds = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "cronIdsJson")) ?? [];
+      const nextCronIds = (triggers.cron ?? []).map((c) => this.computeCronId(name, c.id, c.expression, c.timezone, c.input));
+
+      const nextCronIdSet = new Set(nextCronIds);
+      for (const oldId of prevCronIds) {
+        if (!nextCronIdSet.has(oldId)) {
+          await this.redis.hdel(keys.cronDef(this.prefix), oldId);
+          await this.redis.zrem(keys.cronNext(this.prefix), oldId);
+        }
+      }
+
+      for (let i = 0; i < (triggers.cron ?? []).length; i++) {
+        const cron = triggers.cron![i]!;
+        const cronId = nextCronIds[i]!;
+        const cronInput = Object.prototype.hasOwnProperty.call(cron, "input") ? cron.input : {};
+
+        const cronDef = {
+          id: cronId,
+          workflow: name,
+          queue,
+          expression: cron.expression,
+          timezone: cron.timezone,
+          inputJson: safeJsonStringify(cronInput),
+        };
+
+        await this.redis.hset(keys.cronDef(this.prefix), { [cronId]: safeJsonStringify(cronDef) });
+
+        const nextAt = this.computeNextCronAtMs(cron.expression, cron.timezone);
+        if (nextAt != null) {
+          await this.redis.zadd(keys.cronNext(this.prefix), nextAt, cronId);
+        } else {
+          await this.redis.zrem(keys.cronNext(this.prefix), cronId);
+        }
+      }
+
+      const meta: Record<string, string> = {
+        name,
+        queue,
+        owner,
+        updatedAt: String(updatedAt),
+        triggersJson: safeJsonStringify(triggers),
+        retriesJson: safeJsonStringify(retries),
+        eventsJson: safeJsonStringify(nextEvents),
+        cronIdsJson: safeJsonStringify(nextCronIds),
+      };
+
+      await this.redis.hset(workflowKey, meta);
+    }
+  }
+
+  // ----------------------
+  // Internal run utilities
+  // ----------------------
+
+  private async getQueueForWorkflow(workflowName: string): Promise<string | null> {
+    const metaKey = keys.workflow(this.prefix, workflowName);
+    return await this.redis.hget(metaKey, "queue");
+  }
+
+  private async getMaxAttemptsForWorkflow(workflowName: string): Promise<number | null> {
+    const metaKey = keys.workflow(this.prefix, workflowName);
+    const retriesJson = await this.redis.hget(metaKey, "retriesJson");
+    if (!retriesJson) return null;
+    const retries = safeJsonParse<any>(retriesJson);
+    const maxAttempts = retries?.maxAttempts;
+    if (typeof maxAttempts === "number" && Number.isFinite(maxAttempts) && maxAttempts > 0) return maxAttempts;
+    return null;
+  }
+
+  private computeCronId(
+    workflowName: string,
+    userId: string | undefined,
+    expression: string,
+    timezone: string | undefined,
+    input: unknown,
+  ): string {
+    if (userId) {
+      const stable = safeJsonStringify({ workflowName, userId });
+      const hash = createHash("sha256").update(stable).digest("hex").slice(0, 24);
+      return `cron_user_${hash}`;
+    }
+
+    const stable = safeJsonStringify({ workflowName, expression, timezone: timezone ?? null, input });
+    const hash = createHash("sha256").update(stable).digest("hex").slice(0, 24);
+    return `cron_auto_${hash}`;
+  }
+
+  private async cleanupStaleWorkflows(
+    registeredNames: Set<string>,
+    syncStartedAt: number,
+    owner: string,
+  ): Promise<void> {
+    const existingNames = await this.redis.smembers(keys.workflows(this.prefix));
+
+    for (const existingName of existingNames) {
+      if (registeredNames.has(existingName)) continue;
+
+      const workflowKey = keys.workflow(this.prefix, existingName);
+      const workflowOwner = (await this.redis.hget(workflowKey, "owner")) ?? "";
+      if (!workflowOwner || workflowOwner !== owner) {
+        continue;
+      }
+
+      const updatedAt = Number((await this.redis.hget(workflowKey, "updatedAt")) ?? "0");
+      if (Number.isFinite(updatedAt) && updatedAt > 0 && syncStartedAt - updatedAt < STALE_WORKFLOW_GRACE_MS) {
+        continue;
+      }
+
+      await this.deleteWorkflowMetadata(existingName);
+    }
+  }
+
+  private async deleteWorkflowMetadata(workflowName: string): Promise<void> {
+    const workflowKey = keys.workflow(this.prefix, workflowName);
+
+    const prevEvents = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "eventsJson")) ?? [];
+    for (const eventName of prevEvents) {
+      await this.redis.srem(keys.eventWorkflows(this.prefix, eventName), workflowName);
+    }
+
+    const prevCronIds = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "cronIdsJson")) ?? [];
+    for (const cronId of prevCronIds) {
+      await this.redis.hdel(keys.cronDef(this.prefix), cronId);
+      await this.redis.zrem(keys.cronNext(this.prefix), cronId);
+    }
+
+    await this.redis.del(workflowKey);
+    await this.redis.srem(keys.workflows(this.prefix), workflowName);
+  }
+
+  private toListedRun(run: RunState): ListedRun {
+    return {
+      id: run.id,
+      workflow: run.workflow,
+      queue: run.queue,
+      status: run.status,
+      error: run.error,
+      createdAt: run.createdAt,
+      availableAt: run.availableAt,
+      startedAt: run.startedAt,
+      finishedAt: run.finishedAt,
+      attempt: run.attempt,
+      maxAttempts: run.maxAttempts,
+    };
+  }
+
+  private computeNextCronAtMs(expression: string, timezone?: string): number | null {
+    try {
+      const job = new Cron(expression, { timezone, catch: true });
+      const next = job.nextRun();
+      job.stop();
+      if (!next) return null;
+      return next.getTime();
+    } catch {
+      return null;
+    }
+  }
+
+  private async repairExistingRunPlacement(runId: string): Promise<void> {
+    const runKey = keys.run(this.prefix, runId);
+    const run = await this.redis.hgetall(runKey);
+    if (!run || Object.keys(run).length === 0) return;
+
+    const status = (run.status as RunStatus | undefined) ?? undefined;
+    const queue = run.queue ?? "default";
+    const workflow = run.workflow ?? "";
+    const createdAtRaw = Number(run.createdAt ?? "0");
+    const createdAt = Number.isFinite(createdAtRaw) && createdAtRaw > 0 ? createdAtRaw : nowMs();
+
+    // Repair indexes in case a producer crashed mid-enqueue.
+    await this.redis.zadd(keys.runsCreated(this.prefix), createdAt, runId);
+    if (status) {
+      await this.redis.zadd(keys.runsStatus(this.prefix, status), createdAt, runId);
+    }
+    if (workflow) {
+      await this.redis.zadd(keys.workflowRuns(this.prefix, workflow), createdAt, runId);
+    }
+
+    if (status === "queued") {
+      const readyKey = keys.queueReady(this.prefix, queue);
+      const processingKey = keys.queueProcessing(this.prefix, queue);
+      const [ready, processing] = await Promise.all([
+        this.redis.lrange(readyKey, 0, -1),
+        this.redis.lrange(processingKey, 0, -1),
+      ]);
+
+      if (!ready.includes(runId) && !processing.includes(runId)) {
+        await this.redis.lpush(readyKey, runId);
+      }
+      return;
+    }
+
+    if (status === "scheduled") {
+      const scheduledKey = keys.queueScheduled(this.prefix, queue);
+      const score = await this.redis.send("ZSCORE", [scheduledKey, runId]);
+      if (score == null) {
+        const availableAtRaw = Number(run.availableAt ?? "0");
+        const availableAt = Number.isFinite(availableAtRaw) && availableAtRaw > 0 ? availableAtRaw : nowMs();
+        await this.redis.zadd(scheduledKey, availableAt, runId);
+      }
+    }
+  }
+
+  private async requestCancellation(
+    runId: string,
+    requestedAt: number,
+    reason: string,
+  ): Promise<RunStatus | "__missing__"> {
+    const result = await this.redis.send("EVAL", [
+      REQUEST_CANCELLATION_LUA,
+      "1",
+      keys.run(this.prefix, runId),
+      String(requestedAt),
+      reason,
+    ]);
+
+    if (typeof result !== "string") return "__missing__";
+    if (result === "__missing__") return "__missing__";
+    return result as RunStatus;
+  }
+
+  private async finalizeCanceledRunImmediately(runId: string, queue: string, finishedAt: number): Promise<void> {
+    const runKey = keys.run(this.prefix, runId);
+    await this.redis.zrem(keys.queueScheduled(this.prefix, queue), runId);
+    await this.redis.lrem(keys.queueReady(this.prefix, queue), 0, runId);
+    // Also clean processing list — the run could have been moved there
+    // between cancelRun's status check and this cleanup.
+    await this.redis.lrem(keys.queueProcessing(this.prefix, queue), 0, runId);
+    await this.redis.hdel(runKey, "availableAt");
+    await this.redis.hdel(runKey, "outputJson");
+    await this.redis.hdel(runKey, "errorJson");
+    await this.redis.hset(runKey, { finishedAt: String(finishedAt) });
+  }
+
+  private async enqueueRun<TOutput>(args: {
+    workflowName: string;
+    queue: string;
+    input: unknown;
+    availableAt?: Date;
+    idempotencyKey?: string;
+    idempotencyTtl?: number;
+    maxAttempts: number;
+  }): Promise<RunHandle<TOutput>> {
+    const createdAt = nowMs();
+    const availableAtMs = args.availableAt ? args.availableAt.getTime() : undefined;
+    const shouldSchedule = availableAtMs != null && availableAtMs > createdAt;
+    const runId = `run_${crypto.randomUUID()}`;
+    const status: RunStatus = shouldSchedule ? "scheduled" : "queued";
+    const runKey = keys.run(this.prefix, runId);
+    const idempotencyRedisKey = args.idempotencyKey
+      ? keys.idempotency(this.prefix, args.workflowName, args.idempotencyKey)
+      : keys.idempotency(this.prefix, "__unused__", runId);
+
+    const result = await this.redis.send("EVAL", [
+      ENQUEUE_RUN_LUA,
+      "7",
+      runKey,
+      keys.runsCreated(this.prefix),
+      keys.runsStatus(this.prefix, status),
+      keys.workflowRuns(this.prefix, args.workflowName),
+      keys.queueReady(this.prefix, args.queue),
+      keys.queueScheduled(this.prefix, args.queue),
+      idempotencyRedisKey,
+      runId,
+      args.workflowName,
+      args.queue,
+      status,
+      safeJsonStringify(args.input),
+      String(createdAt),
+      shouldSchedule ? String(availableAtMs) : "",
+      String(args.maxAttempts),
+      args.idempotencyKey ? "1" : "0",
+      String(args.idempotencyTtl ?? IDEMPOTENCY_TTL_SEC),
+      keys.run(this.prefix, ""),
+    ]);
+
+    const parsed = parseEnqueueScriptResult(result);
+    if (!parsed) {
+      throw new Error(`Failed to enqueue run '${args.workflowName}': unexpected Redis response`);
+    }
+
+    if (parsed.kind === "existing") {
+      await this.repairExistingRunPlacement(parsed.runId);
+    }
+
+    return this.makeRunHandle(parsed.runId);
+  }
+
+  async transitionRunStatus(runId: string, nextStatus: RunStatus, updatedAt: number): Promise<void> {
+    // Atomic: reads prev status, zrem from old index, hset new status,
+    // hdel availableAt if not scheduled, zadd to new index.
+    const statusIndexPrefix = keys.runsStatus(this.prefix, ""); // e.g. "redflow:v1:runs:status:"
+    await this.redis.send("EVAL", [
+      TRANSITION_RUN_STATUS_LUA,
+      "2",
+      keys.run(this.prefix, runId),
+      keys.runsStatus(this.prefix, nextStatus),
+      runId,
+      nextStatus,
+      String(updatedAt),
+      statusIndexPrefix,
+    ]);
+  }
+
+  /**
+   * Atomically schedule a retry: sets availableAt + errorJson on the run,
+   * transitions status to "scheduled", and adds to queue's scheduled set.
+   * Prevents stranded runs if the worker crashes mid-retry.
+   */
+  async scheduleRetry(runId: string, args: {
+    queue: string;
+    nextAt: number;
+    errorJson: string;
+    updatedAt: number;
+  }): Promise<void> {
+    const statusIndexPrefix = keys.runsStatus(this.prefix, "");
+    await this.redis.send("EVAL", [
+      SCHEDULE_RETRY_LUA,
+      "3",
+      keys.run(this.prefix, runId),
+      keys.runsStatus(this.prefix, "scheduled"),
+      keys.queueScheduled(this.prefix, args.queue),
+      runId,
+      String(args.updatedAt),
+      String(args.nextAt),
+      args.errorJson,
+      statusIndexPrefix,
+    ]);
+  }
+
+  async transitionRunStatusIfCurrent(
+    runId: string,
+    expectedStatus: RunStatus,
+    nextStatus: RunStatus,
+    updatedAt: number,
+  ): Promise<boolean> {
+    const changed = await this.redis.send("EVAL", [
+      TRANSITION_IF_CURRENT_STATUS_LUA,
+      "3",
+      keys.run(this.prefix, runId),
+      keys.runsStatus(this.prefix, expectedStatus),
+      keys.runsStatus(this.prefix, nextStatus),
+      runId,
+      expectedStatus,
+      nextStatus,
+      String(updatedAt),
+    ]);
+    return changed === 1 || changed === "1";
+  }
+
+  async finalizeRun(runId: string, args: { status: RunStatus; outputJson?: string; errorJson?: string; finishedAt: number }): Promise<void> {
+    const result = await this.redis.send("EVAL", [
+      FINALIZE_TERMINAL_RUN_LUA,
+      "7",
+      keys.run(this.prefix, runId),
+      keys.runsStatus(this.prefix, "scheduled"),
+      keys.runsStatus(this.prefix, "queued"),
+      keys.runsStatus(this.prefix, "running"),
+      keys.runsStatus(this.prefix, "succeeded"),
+      keys.runsStatus(this.prefix, "failed"),
+      keys.runsStatus(this.prefix, "canceled"),
+      runId,
+      args.status,
+      String(args.finishedAt),
+      args.outputJson ?? "",
+      args.errorJson ?? "",
+      args.outputJson != null ? "1" : "0",
+      args.errorJson != null ? "1" : "0",
+    ]);
+
+    if (result === "__missing__") {
+      throw new Error(`Run not found: ${runId}`);
+    }
+  }
+}
+
+export function createClient(options?: CreateClientOptions): RedflowClient {
+  const prefix = options?.prefix ?? defaultPrefix();
+  const redis = options?.redis ?? (options?.url ? new RedisClient(options.url) : defaultRedis);
+  return new RedflowClient(redis, prefix);
+}
+
+export function validateInputWithSchema(schema: ZodTypeAny, input: unknown): unknown {
+  try {
+    return schema.parse(input);
+  } catch (err: any) {
+    // zod v4 error format is stable enough for display, but we store it as raw.
+    throw new InputValidationError("Workflow input validation failed", err);
+  }
+}
+
+export function isTerminalStatus(status: RunStatus): boolean {
+  return status === "succeeded" || status === "failed" || status === "canceled";
+}
+
+export function isRetryableError(err: unknown): boolean {
+  if (err instanceof InputValidationError) return false;
+  if (err instanceof UnknownWorkflowError) return false;
+  if (err instanceof OutputSerializationError) return false;
+  if (err instanceof CanceledError) return false;
+  if (err instanceof NonRetriableError) return false;
+  return true;
+}
+
+export function computeRetryDelayMs(attempt: number): number {
+  // attempt is 1-based (first attempt = 1). Backoff starts on retry.
+  const base = 250;
+  const max = 30_000;
+  const exp = Math.min(max, base * Math.pow(2, Math.max(0, attempt - 1)));
+  const jitter = Math.floor(Math.random() * 100);
+  return exp + jitter;
+}
+
+export function makeErrorJson(err: unknown): string {
+  try {
+    const serialized: SerializedError = serializeError(err);
+    return safeJsonStringify(serialized);
+  } catch {
+    return '{"name":"Error","message":"Failed to serialize original error","kind":"error"}';
+  }
+}