@redflow/client 0.0.1

package/tests/redflow.e2e.test.ts

@@ -0,0 +1,3154 @@
+import { afterAll, beforeAll, beforeEach, expect, test } from "bun:test";
+import { RedisClient } from "bun";
+import { z } from "zod";
+import {
+  createClient,
+  CanceledError,
+  NonRetriableError,
+  UnknownWorkflowError,
+  defineWorkflow,
+  setDefaultClient,
+  startWorker,
+  type RunStatus,
+} from "../src/index";
+import { RedflowClient } from "../src/client";
+import { keys } from "../src/internal/keys";
+import { __unstableResetDefaultRegistryForTests, getDefaultRegistry } from "../src/registry";
+import { safeJsonParse, safeJsonStringify } from "../src/internal/json";
+import { waitFor } from "./helpers/waitFor";
+import { startRedisTestServer } from "./helpers/redisTestServer";
+
+let redisServer: Awaited<ReturnType<typeof startRedisTestServer>>;
+
+beforeAll(async () => {
+  redisServer = await startRedisTestServer();
+});
+
+afterAll(async () => {
+  await redisServer.stop();
+});
+
+beforeEach(() => {
+  __unstableResetDefaultRegistryForTests();
+});
+
+function testPrefix(): string {
+  return `redflow:test:${crypto.randomUUID()}`;
+}
+
+test("manual run: succeeds and records steps", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow(
+    {
+      name: "manual-success",
+      queue: "q1",
+      schema: z.object({ n: z.number().int() }),
+    },
+    async ({ input, step }) => {
+      const a = await step.run({ name: "a" }, async () => input.n + 1);
+      const b = await step.run({ name: "b" }, async () => a + 1);
+      return { ok: true, b };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q1"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({ n: 1 });
+  const result = await handle.result({ timeoutMs: 3000, pollMs: 50 });
+  expect(result).toEqual({ ok: true, b: 3 });
+
+  const steps = await client.getRunSteps(handle.id);
+  expect(steps.map((s) => s.name)).toEqual(["a", "b"]);
+  expect(steps.map((s) => s.status)).toEqual(["succeeded", "succeeded"]);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("availableAt: scheduled -> promoted -> executed", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow({ name: "delayed", queue: "q2" }, async ({ step }) => {
+    await step.run({ name: "do" }, async () => true);
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q2"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const runAt = new Date(Date.now() + 1200);
+  const handle = await wf.run({}, { availableAt: runAt });
+  const state1 = await client.getRun(handle.id);
+  expect(state1?.status).toBe("scheduled");
+
+  const result = await handle.result({ timeoutMs: 4000, pollMs: 50 });
+  expect(result).toEqual({ ok: true });
+
+  const state2 = await client.getRun(handle.id);
+  expect(state2?.status).toBe("succeeded");
+  expect((state2?.startedAt ?? 0) + 40).toBeGreaterThanOrEqual(runAt.getTime());
+  expect(state2?.availableAt).toBeUndefined();
+
+  await worker.stop();
+  redis.close();
+});
+
+test("availableAt: cleared after retry exhaustion final failure", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow(
+    {
+      name: "retry-failure-clears-available-at",
+      queue: "q2_retry_fail",
+      retries: { maxAttempts: 2 },
+    },
+    async () => {
+      throw new Error("boom");
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q2_retry_fail"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+  await expect(handle.result({ timeoutMs: 8000, pollMs: 50 })).rejects.toThrow("Run failed");
+
+  const state = await client.getRun(handle.id);
+  expect(state?.status).toBe("failed");
+  expect(state?.attempt).toBe(2);
+  expect(state?.availableAt).toBeUndefined();
+
+  await worker.stop();
+  redis.close();
+});
+
+test("NonRetriableError: skips retries and fails immediately on attempt 1", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow(
+    {
+      name: "non-retriable-error-wf",
+      queue: "q_non_retriable",
+      retries: { maxAttempts: 3 },
+    },
+    async () => {
+      throw new NonRetriableError("permanent failure");
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_non_retriable"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+  await expect(handle.result({ timeoutMs: 8000, pollMs: 50 })).rejects.toThrow("Run failed");
+
+  const state = await client.getRun(handle.id);
+  expect(state?.status).toBe("failed");
+  // Should fail on the first attempt without retrying
+  expect(state?.attempt).toBe(1);
+
+  // Verify the error is serialized correctly
+  const error = state?.error as Record<string, unknown> | undefined;
+  expect(error?.kind).toBe("non_retriable");
+  expect(error?.message).toBe("permanent failure");
+
+  await worker.stop();
+  redis.close();
+});
+
+test("onFailure: called after retry exhaustion with correct context", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  let failureCtx: any = null;
+
+  const wf = defineWorkflow(
+    {
+      name: "on-failure-retry-exhaustion",
+      queue: "q_on_failure_1",
+      retries: { maxAttempts: 2 },
+      onFailure: (ctx) => {
+        failureCtx = ctx;
+      },
+    },
+    async () => {
+      throw new Error("always fails");
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_on_failure_1"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({ some: "data" });
+  await expect(handle.result({ timeoutMs: 8000, pollMs: 50 })).rejects.toThrow("Run failed");
+
+  expect(failureCtx).not.toBeNull();
+  expect(failureCtx.error).toBeInstanceOf(Error);
+  expect(failureCtx.error.message).toBe("always fails");
+  expect(failureCtx.input).toEqual({ some: "data" });
+  expect(failureCtx.run.id).toBe(handle.id);
+  expect(failureCtx.run.workflow).toBe("on-failure-retry-exhaustion");
+  expect(failureCtx.run.queue).toBe("q_on_failure_1");
+  expect(failureCtx.run.attempt).toBe(2);
+  expect(failureCtx.run.maxAttempts).toBe(2);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("onFailure: called immediately with NonRetriableError", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  let failureCtx: any = null;
+
+  const wf = defineWorkflow(
+    {
+      name: "on-failure-non-retriable",
+      queue: "q_on_failure_2",
+      retries: { maxAttempts: 5 },
+      onFailure: (ctx) => {
+        failureCtx = ctx;
+      },
+    },
+    async () => {
+      throw new NonRetriableError("permanent");
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_on_failure_2"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+  await expect(handle.result({ timeoutMs: 8000, pollMs: 50 })).rejects.toThrow("Run failed");
+
+  expect(failureCtx).not.toBeNull();
+  expect(failureCtx.error).toBeInstanceOf(NonRetriableError);
+  expect(failureCtx.run.attempt).toBe(1);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("onFailure: NOT called on cancellation", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  let onFailureCalled = false;
+
+  const wf = defineWorkflow(
+    {
+      name: "on-failure-not-on-cancel",
+      queue: "q_on_failure_3",
+      onFailure: () => {
+        onFailureCalled = true;
+      },
+    },
+    async ({ signal }) => {
+      // Long-running work that will be canceled
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, 60_000);
+        signal.addEventListener("abort", () => {
+          clearTimeout(timer);
+          reject(new Error("aborted"));
+        });
+      });
+      return {};
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_on_failure_3"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+
+  // Wait for the run to start
+  await waitFor(async () => {
+    const state = await client.getRun(handle.id);
+    return state?.status === "running";
+  }, { timeoutMs: 5000, label: "run starts" });
+
+  await client.cancelRun(handle.id);
+
+  await waitFor(async () => {
+    const state = await client.getRun(handle.id);
+    return state?.status === "canceled";
+  }, { timeoutMs: 5000, label: "run canceled" });
+
+  // Give a small window for any erroneous onFailure call
+  await new Promise((r) => setTimeout(r, 200));
+  expect(onFailureCalled).toBe(false);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("cron: creates runs and executes workflow", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const counterKey = `${prefix}:t:cronCount`;
+
+  defineWorkflow(
+    {
+      name: "cron-wf",
+      queue: "q4",
+      triggers: { cron: [{ expression: "*/1 * * * * *", input: { x: 1 } }] },
+    },
+    async ({ step }) => {
+      await step.run({ name: "tick" }, async () => {
+        await redis.incr(counterKey);
+        return true;
+      });
+      return { ok: true };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q4"],
+    runtime: { leaseMs: 500 },
+  });
+
+  await waitFor(
+    async () => {
+      const v = await redis.get(counterKey);
+      return Number(v ?? "0") >= 1;
+    },
+    { timeoutMs: 5000, label: "cron tick" },
+  );
+
+  await worker.stop();
+  redis.close();
+});
+
+test("step.runWorkflow: auto idempotency and override are forwarded to child runs", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const observedIdempotencyKeys: string[] = [];
+  const originalRunByName: RedflowClient["runByName"] = RedflowClient.prototype.runByName;
+
+  RedflowClient.prototype.runByName = (async function (
+    this: RedflowClient,
+    workflowName: string,
+    input: unknown,
+    options?: Parameters<RedflowClient["runByName"]>[2],
+  ): Promise<Awaited<ReturnType<RedflowClient["runByName"]>>> {
+    if (workflowName === "child-rw-forward") {
+      observedIdempotencyKeys.push(options?.idempotencyKey ?? "");
+    }
+    return await originalRunByName.call(this, workflowName, input, options);
+  }) as RedflowClient["runByName"];
+
+  const child = defineWorkflow({ name: "child-rw-forward", queue: "q_rw_child" }, async ({ input }) => input);
+
+  const encodePart = (value: string) => `${value.length}:${value}`;
+  let expectedAutoIdempotencyKey = "";
+
+  const parent = defineWorkflow({ name: "parent-rw-forward", queue: "q_rw_parent" }, async ({ run, step }) => {
+    expectedAutoIdempotencyKey =
+      `stepwf:${encodePart(run.id)}:${encodePart("child-auto")}:${encodePart(child.name)}`;
+
+    const auto = await step.runWorkflow({ name: "child-auto" }, child, { n: 1 });
+    const custom = await step.runWorkflow({ name: "child-custom", idempotencyKey: "custom-idem" }, child, { n: 2 });
+
+    return { auto, custom };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_rw_parent", "q_rw_child"],
+    concurrency: 2,
+    runtime: { leaseMs: 500 },
+  });
+
+  try {
+    const handle = await parent.run({});
+    const out = await handle.result({ timeoutMs: 5000, pollMs: 50 });
+    expect(out).toEqual({
+      auto: { n: 1 },
+      custom: { n: 2 },
+    });
+
+    expect(observedIdempotencyKeys.length).toBe(2);
+    expect(observedIdempotencyKeys[0]).toBe(expectedAutoIdempotencyKey);
+    expect(observedIdempotencyKeys[1]).toBe("custom-idem");
+  } finally {
+    RedflowClient.prototype.runByName = originalRunByName;
+    await worker.stop();
+    redis.close();
+  }
+}, { timeout: 15_000 });
+
+test("step.runWorkflow: child workflow executes once across parent retries", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const childCountKey = `${prefix}:t:child-runWorkflow-count`;
+  const failOnceKey = `${prefix}:t:parent-runWorkflow-fail-once`;
+
+  const child = defineWorkflow({ name: "child-rw-retry", queue: "q_rw_retry_child" }, async ({ step }) => {
+    await step.run({ name: "count-child" }, async () => {
+      await redis.incr(childCountKey);
+      return true;
+    });
+
+    return { ok: true };
+  });
+
+  const parent = defineWorkflow(
+    {
+      name: "parent-rw-retry",
+      queue: "q_rw_retry_parent",
+      retries: { maxAttempts: 2 },
+    },
+    async ({ step }) => {
+      const childOut = await step.runWorkflow({ name: "invoke-child" }, child, {});
+
+      await step.run({ name: "fail-once" }, async () => {
+        const seen = await redis.get(failOnceKey);
+        if (!seen) {
+          await redis.set(failOnceKey, "1");
+          throw new Error("boom once");
+        }
+        return true;
+      });
+
+      return childOut;
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_rw_retry_parent", "q_rw_retry_child"],
+    concurrency: 2,
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await parent.run({});
+  const out = await handle.result({ timeoutMs: 8000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const childCount = Number((await redis.get(childCountKey)) ?? "0");
+  expect(childCount).toBe(1);
+
+  const childRuns = await client.listRuns({ workflow: "child-rw-retry", limit: 10 });
+  expect(childRuns.length).toBe(1);
+
+  const parentState = await client.getRun(handle.id);
+  expect(parentState?.status).toBe("succeeded");
+  expect(parentState?.attempt).toBe(2);
+
+  await worker.stop();
+  redis.close();
+}, { timeout: 15_000 });
+
+test("step.runWorkflow: same queue avoids self-deadlock with concurrency 1", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const childFailOnceKey = `${prefix}:t:child-rw-fail-once`;
+  const childCountKey = `${prefix}:t:child-rw-count`;
+
+  const child = defineWorkflow(
+    {
+      name: "child-rw-single-worker",
+      queue: "q_rw_single",
+      retries: { maxAttempts: 2 },
+    },
+    async ({ step }) => {
+      await step.run({ name: "do-child" }, async () => {
+        const seen = await redis.get(childFailOnceKey);
+        if (!seen) {
+          await redis.set(childFailOnceKey, "1");
+          throw new Error("child fails once");
+        }
+        await redis.incr(childCountKey);
+        return true;
+      });
+
+      return { ok: true };
+    },
+  );
+
+  const parent = defineWorkflow({ name: "parent-rw-single-worker", queue: "q_rw_single" }, async ({ step }) => {
+    return await step.runWorkflow({ name: "call-child" }, child, {});
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_rw_single"],
+    concurrency: 1,
+    runtime: { leaseMs: 500, blmoveTimeoutSec: 0.2, reaperIntervalMs: 50 },
+  });
+
+  const handle = await parent.run({});
+  const out = await handle.result({ timeoutMs: 10_000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const childCount = Number((await redis.get(childCountKey)) ?? "0");
+  expect(childCount).toBe(1);
+
+  const childRuns = await client.listRuns({ workflow: "child-rw-single-worker", limit: 10 });
+  expect(childRuns.length).toBe(1);
+  expect(childRuns[0]?.status).toBe("succeeded");
+  expect(childRuns[0]?.attempt).toBe(2);
+
+  await worker.stop();
+  redis.close();
+}, { timeout: 20_000 });
+
+test("step.emitEvent: auto idempotency and override are forwarded", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const observedIdempotencyKeys: string[] = [];
+  const originalEmitEvent: RedflowClient["emitEvent"] = RedflowClient.prototype.emitEvent;
+
+  RedflowClient.prototype.emitEvent = (async function (
+    this: RedflowClient,
+    name: string,
+    payload: unknown,
+    options?: Parameters<RedflowClient["emitEvent"]>[2],
+  ): Promise<Awaited<ReturnType<RedflowClient["emitEvent"]>>> {
+    if (name === "step.emit.forward" || name === "step.emit.forward.custom") {
+      observedIdempotencyKeys.push(options?.idempotencyKey ?? "");
+    }
+    return await originalEmitEvent.call(this, name, payload, options);
+  }) as RedflowClient["emitEvent"];
+
+  defineWorkflow(
+    { name: "step-emit-consumer-a", queue: "q_emit_a", triggers: { events: ["step.emit.forward"] } },
+    async () => ({ ok: true }),
+  );
+
+  defineWorkflow(
+    { name: "step-emit-consumer-b", queue: "q_emit_b", triggers: { events: ["step.emit.forward.custom"] } },
+    async () => ({ ok: true }),
+  );
+
+  const encodePart = (value: string) => `${value.length}:${value}`;
+  let expectedAutoIdempotencyKey = "";
+
+  const parent = defineWorkflow({ name: "step-emit-parent-forward", queue: "q_emit_parent" }, async ({ run, step }) => {
+    expectedAutoIdempotencyKey =
+      `stepev:${encodePart(run.id)}:${encodePart("emit-auto")}:${encodePart("step.emit.forward")}`;
+
+    const auto = await step.emitEvent({ name: "emit-auto", event: "step.emit.forward" }, { ok: 1 });
+    const custom = await step.emitEvent(
+      { name: "emit-custom", event: "step.emit.forward.custom", idempotencyKey: "evt-custom" },
+      { ok: 2 },
+    );
+
+    return {
+      autoCount: auto.length,
+      customCount: custom.length,
+    };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_emit_parent", "q_emit_a", "q_emit_b"],
+    concurrency: 2,
+    runtime: { leaseMs: 500 },
+  });
+
+  try {
+    const handle = await parent.run({});
+    const out = await handle.result({ timeoutMs: 5000, pollMs: 50 });
+    expect(out).toEqual({ autoCount: 1, customCount: 1 });
+
+    expect(observedIdempotencyKeys.length).toBe(2);
+    expect(observedIdempotencyKeys[0]).toBe(expectedAutoIdempotencyKey);
+    expect(observedIdempotencyKeys[1]).toBe("evt-custom");
+  } finally {
+    RedflowClient.prototype.emitEvent = originalEmitEvent;
+    await worker.stop();
+    redis.close();
+  }
+}, { timeout: 15_000 });
+
+test("step.emitEvent: emitted workflows execute once across parent retries", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const counterKey = `${prefix}:t:step-emit-once`;
+  const failOnceKey = `${prefix}:t:step-emit-parent-fail`;
+
+  defineWorkflow(
+    {
+      name: "step-emit-consumer-once",
+      queue: "q_emit_retry_consumer",
+      triggers: { events: ["step.emit.once"] },
+    },
+    async ({ step }) => {
+      await step.run({ name: "count" }, async () => {
+        await redis.incr(counterKey);
+        return true;
+      });
+      return { ok: true };
+    },
+  );
+
+  const parent = defineWorkflow(
+    {
+      name: "step-emit-parent-retry",
+      queue: "q_emit_retry_parent",
+      retries: { maxAttempts: 2 },
+    },
+    async ({ step }) => {
+      const runIds = await step.emitEvent({ name: "emit-once", event: "step.emit.once" }, { v: 1 });
+
+      await step.run({ name: "fail-once" }, async () => {
+        const seen = await redis.get(failOnceKey);
+        if (!seen) {
+          await redis.set(failOnceKey, "1");
+          throw new Error("fail once");
+        }
+        return true;
+      });
+
+      return { emitted: runIds.length };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_emit_retry_parent", "q_emit_retry_consumer"],
+    concurrency: 2,
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await parent.run({});
+  const out = await handle.result({ timeoutMs: 8000, pollMs: 50 });
+  expect(out).toEqual({ emitted: 1 });
+
+  await waitFor(
+    async () => Number((await redis.get(counterKey)) ?? "0") >= 1,
+    { timeoutMs: 5000, label: "step.emitEvent consumer run" },
+  );
+
+  await new Promise((r) => setTimeout(r, 200));
+  const counter = Number((await redis.get(counterKey)) ?? "0");
+  expect(counter).toBe(1);
+
+  const consumerRuns = await client.listRuns({ workflow: "step-emit-consumer-once", limit: 10 });
+  expect(consumerRuns.length).toBe(1);
+
+  const parentState = await client.getRun(handle.id);
+  expect(parentState?.status).toBe("succeeded");
+  expect(parentState?.attempt).toBe(2);
+
+  await worker.stop();
+  redis.close();
+}, { timeout: 15_000 });
+
+test("step.scheduleEvent: scheduled workflows execute once across parent retries", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const counterKey = `${prefix}:t:step-schedule-once`;
+  const failOnceKey = `${prefix}:t:step-schedule-parent-fail`;
+
+  defineWorkflow(
+    {
+      name: "step-schedule-consumer-once",
+      queue: "q_schedule_retry_consumer",
+      triggers: { events: ["step.schedule.once"] },
+    },
+    async ({ step }) => {
+      await step.run({ name: "count" }, async () => {
+        await redis.incr(counterKey);
+        return true;
+      });
+      return { ok: true };
+    },
+  );
+
+  const parent = defineWorkflow(
+    {
+      name: "step-schedule-parent-retry",
+      queue: "q_schedule_retry_parent",
+      retries: { maxAttempts: 2 },
+    },
+    async ({ step }) => {
+      const runIds = await step.scheduleEvent(
+        {
+          name: "schedule-once",
+          event: "step.schedule.once",
+          schedule: { availableAt: new Date(Date.now() + 250) },
+        },
+        { v: 1 },
+      );
+
+      await step.run({ name: "fail-once" }, async () => {
+        const seen = await redis.get(failOnceKey);
+        if (!seen) {
+          await redis.set(failOnceKey, "1");
+          throw new Error("fail once");
+        }
+        return true;
+      });
+
+      return { emitted: runIds.length };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_schedule_retry_parent", "q_schedule_retry_consumer"],
+    concurrency: 2,
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await parent.run({});
+  const out = await handle.result({ timeoutMs: 8000, pollMs: 50 });
+  expect(out).toEqual({ emitted: 1 });
+
+  await waitFor(
+    async () => Number((await redis.get(counterKey)) ?? "0") >= 1,
+    { timeoutMs: 6000, label: "step.scheduleEvent consumer run" },
+  );
+
+  await new Promise((r) => setTimeout(r, 250));
+  const counter = Number((await redis.get(counterKey)) ?? "0");
+  expect(counter).toBe(1);
+
+  const consumerRuns = await client.listRuns({ workflow: "step-schedule-consumer-once", limit: 10 });
+  expect(consumerRuns.length).toBe(1);
+
+  const parentState = await client.getRun(handle.id);
+  expect(parentState?.status).toBe("succeeded");
+  expect(parentState?.attempt).toBe(2);
+
+  await worker.stop();
+  redis.close();
+}, { timeout: 15_000 });
+
+test("retries: step results are cached across attempts", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const step1CountKey = `${prefix}:t:step1Count`;
+  const failOnceKey = `${prefix}:t:failOnce`;
+
+  const wf = defineWorkflow(
+    {
+      name: "retry-wf",
+      queue: "q5",
+      retries: { maxAttempts: 2 },
+    },
+    async ({ step }) => {
+      await step.run({ name: "step1" }, async () => {
+        await redis.incr(step1CountKey);
+        return { ok: true };
+      });
+
+      await step.run({ name: "step2" }, async () => {
+        const seen = await redis.get(failOnceKey);
+        if (!seen) {
+          await redis.set(failOnceKey, "1");
+          throw new Error("boom");
+        }
+        return true;
+      });
+
+      return { ok: true };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q5"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+  const out = await handle.result({ timeoutMs: 8000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const step1Count = Number((await redis.get(step1CountKey)) ?? "0");
+  expect(step1Count).toBe(1);
+
+  const state = await client.getRun(handle.id);
+  expect(state?.attempt).toBe(2);
+  expect(state?.status).toBe("succeeded");
+
+  await worker.stop();
+  redis.close();
+});
+
+test("retries: run queued before worker start keeps workflow maxAttempts", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const failOnceKey = `${prefix}:t:retry-before-sync`;
+
+  const wf = defineWorkflow(
+    {
+      name: "retry-before-sync",
+      queue: "q5_before_sync",
+      retries: { maxAttempts: 2 },
+    },
+    async () => {
+      const seen = await redis.get(failOnceKey);
+      if (!seen) {
+        await redis.set(failOnceKey, "1");
+        throw new Error("fail once");
+      }
+
+      return { ok: true };
+    },
+  );
+
+  const handle = await wf.run({});
+  const queuedState = await client.getRun(handle.id);
+  expect(queuedState?.maxAttempts).toBe(2);
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q5_before_sync"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const out = await handle.result({ timeoutMs: 8000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const state = await client.getRun(handle.id);
+  expect(state?.status).toBe("succeeded");
+  expect(state?.attempt).toBe(2);
+  expect(state?.maxAttempts).toBe(2);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("step timeout: run fails and error is recorded", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow({ name: "timeout-wf", queue: "q6" }, async ({ step }) => {
+    await step.run({ name: "slow", timeoutMs: 80 }, async () => {
+      await new Promise((r) => setTimeout(r, 250));
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q6"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+  await waitFor(
+    async () => {
+      const st = await client.getRun(handle.id);
+      return st?.status === "failed";
+    },
+    { timeoutMs: 6000, label: "run fail" },
+  );
+
+  const state = await client.getRun(handle.id);
+  expect(state?.status).toBe("failed");
+  expect((state?.error as any)?.kind).toBe("timeout");
+
+  const steps = await client.getRunSteps(handle.id);
+  expect(steps[0]?.status).toBe("failed");
+  expect((steps[0]?.error as any)?.kind).toBe("timeout");
+
+  await worker.stop();
+  redis.close();
+});
+
+test("cancellation: scheduled/queued/running", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const touchedKey = `${prefix}:t:touched`;
+
+  const wf = defineWorkflow({ name: "cancel-wf", queue: "q7" }, async ({ step }) => {
+    await step.run({ name: "hold" }, async () => {
+      await new Promise((r) => setTimeout(r, 600));
+      return true;
+    });
+    await step.run({ name: "touch" }, async () => {
+      await redis.incr(touchedKey);
+      return true;
+    });
+    return { ok: true };
+  });
+
+  // Scheduled cancel.
+  {
+    const worker = await startWorker({
+      redis,
+      prefix,
+      queues: ["q7"],
+      runtime: { leaseMs: 300 },
+    });
+
+    const handle = await wf.run({}, { availableAt: new Date(Date.now() + 300) });
+    const canceled = await client.cancelRun(handle.id, { reason: "test" });
+    expect(canceled).toBe(true);
+
+    await waitFor(
+      async () => {
+        const st = await client.getRun(handle.id);
+        return st?.status === "canceled";
+      },
+      { timeoutMs: 2000, label: "scheduled cancel" },
+    );
+
+    await worker.stop();
+  }
+
+  // Queued cancel (no worker running).
+  {
+    const handle = await wf.run({});
+    const st = await client.getRun(handle.id);
+    expect(st?.status).toBe("queued");
+
+    const ok = await client.cancelRun(handle.id, { reason: "test" });
+    expect(ok).toBe(true);
+    const st2 = await client.getRun(handle.id);
+    expect(st2?.status).toBe("canceled");
+  }
+
+  // Running cancel.
+  {
+    const worker = await startWorker({
+      redis,
+      prefix,
+      queues: ["q7"],
+      runtime: { leaseMs: 500 },
+    });
+
+    const handle = await wf.run({});
+    await waitFor(
+      async () => {
+        const st = await client.getRun(handle.id);
+        return st?.status === "running";
+      },
+      { timeoutMs: 4000, label: "running status" },
+    );
+
+    await client.cancelRun(handle.id, { reason: "test" });
+    await waitFor(
+      async () => {
+        const st = await client.getRun(handle.id);
+        return st?.status === "canceled";
+      },
+      { timeoutMs: 5000, label: "running cancel" },
+    );
+
+    const touched = Number((await redis.get(touchedKey)) ?? "0");
+    expect(touched).toBe(0);
+
+    await worker.stop();
+  }
+
+  redis.close();
+});
+
+test("cancel race: queued cancel before start does not execute handler", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q7_race";
+  const sideEffectsKey = `${prefix}:t:cancelRaceSideEffects`;
+
+  const wf = defineWorkflow({ name: "cancel-race-wf", queue }, async () => {
+    await redis.incr(sideEffectsKey);
+    return { ok: true };
+  });
+
+  const originalTransitionRunStatus: RedflowClient["transitionRunStatus"] = RedflowClient.prototype.transitionRunStatus;
+  const originalTransitionRunStatusIfCurrent: RedflowClient["transitionRunStatusIfCurrent"] =
+    RedflowClient.prototype.transitionRunStatusIfCurrent;
+
+  let transitionDelayed = false;
+
+  RedflowClient.prototype.transitionRunStatus = (async function (
+    this: RedflowClient,
+    runId: string,
+    nextStatus: RunStatus,
+    updatedAt: number,
+  ): Promise<void> {
+    if (!transitionDelayed && nextStatus === "running") {
+      transitionDelayed = true;
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    return await originalTransitionRunStatus.call(this, runId, nextStatus, updatedAt);
+  }) as RedflowClient["transitionRunStatus"];
+
+  RedflowClient.prototype.transitionRunStatusIfCurrent = (async function (
+    this: RedflowClient,
+    runId: string,
+    expectedStatus: RunStatus,
+    nextStatus: RunStatus,
+    updatedAt: number,
+  ): Promise<boolean> {
+    if (!transitionDelayed && expectedStatus === "queued" && nextStatus === "running") {
+      transitionDelayed = true;
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    return await originalTransitionRunStatusIfCurrent.call(this, runId, expectedStatus, nextStatus, updatedAt);
+  }) as RedflowClient["transitionRunStatusIfCurrent"];
+
+  let worker: Awaited<ReturnType<typeof startWorker>> | null = null;
+  try {
+    worker = await startWorker({
+      redis,
+      prefix,
+      queues: [queue],
+      runtime: { leaseMs: 500, blmoveTimeoutSec: 0.2, reaperIntervalMs: 50 },
+    });
+
+    const handle = await wf.run({});
+
+    await waitFor(
+      async () => {
+        const processing = await redis.lrange(`${prefix}:q:${queue}:processing`, 0, -1);
+        return processing.includes(handle.id);
+      },
+      { timeoutMs: 4000, label: "run moved to processing" },
+    );
+
+    const canceled = await client.cancelRun(handle.id, { reason: "race" });
+    expect(canceled).toBe(true);
+
+    await waitFor(
+      async () => {
+        const st = await client.getRun(handle.id);
+        return st?.status === "canceled";
+      },
+      { timeoutMs: 6000, label: "run canceled" },
+    );
+
+    await new Promise((r) => setTimeout(r, 400));
+    const sideEffects = Number((await redis.get(sideEffectsKey)) ?? "0");
+    expect(sideEffects).toBe(0);
+  } finally {
+    if (worker) await worker.stop();
+    RedflowClient.prototype.transitionRunStatus = originalTransitionRunStatus;
+    RedflowClient.prototype.transitionRunStatusIfCurrent = originalTransitionRunStatusIfCurrent;
+    redis.close();
+  }
+});
+
+test("crash recovery: processing item is re-queued and cached steps are not re-run", async () => {
+  const prefix = testPrefix();
+  const workflowName = "crash-recover";
+  const queue = "q8";
+  const step1Key = `${prefix}:t:crashStep1`;
+
+  // Spawn a crashing worker.
+  const crashProc = Bun.spawn({
+    cmd: ["bun", "tests/fixtures/worker-crash.ts"],
+    env: {
+      ...process.env,
+      REDIS_URL: redisServer.url,
+      REDFLOW_PREFIX: prefix,
+      TEST_WORKFLOW: workflowName,
+      TEST_QUEUE: queue,
+      TEST_STEP1_KEY: step1Key,
+    },
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  // Wait for workflow meta to appear (crash worker syncRegistry).
+  await waitFor(
+    async () => {
+      const meta = await client.getWorkflowMeta(workflowName);
+      return !!meta;
+    },
+    { timeoutMs: 5000, label: "workflow meta" },
+  );
+
+  const handle = await client.runByName(workflowName, { ok: true }, { queueOverride: queue });
+
+  // Wait for the crash worker to exit.
+  await crashProc.exited;
+
+  // Spawn a recovery worker that will requeue and complete the run, then exit.
+  const recoverProc = Bun.spawn({
+    cmd: ["bun", "tests/fixtures/worker-recover.ts"],
+    env: {
+      ...process.env,
+      REDIS_URL: redisServer.url,
+      REDFLOW_PREFIX: prefix,
+      TEST_WORKFLOW: workflowName,
+      TEST_QUEUE: queue,
+      TEST_STEP1_KEY: step1Key,
+      TEST_RUN_ID: handle.id,
+    },
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+
+  const code = await recoverProc.exited;
+  expect(code).toBe(0);
+
+  const state = await client.getRun(handle.id);
+  expect(state?.status).toBe("succeeded");
+
+  const step1Count = Number((await redis.get(step1Key)) ?? "0");
+  expect(step1Count).toBe(1);
+
+  redis.close();
+});
+
+test("idempotencyKey: same key returns same run id and executes once", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const countKey = `${prefix}:t:idemCount`;
+
+  const wf = defineWorkflow({ name: "idem-wf", queue: "q9" }, async ({ step }) => {
+    await step.run({ name: "do" }, async () => {
+      await redis.incr(countKey);
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q9"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const [h1, h2] = await Promise.all([wf.run({}, { idempotencyKey: "k" }), wf.run({}, { idempotencyKey: "k" })]);
+  expect(h1.id).toBe(h2.id);
+
+  const out = await h1.result({ timeoutMs: 4000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  // Give the worker a moment to potentially pick duplicates.
+  await new Promise((r) => setTimeout(r, 200));
+  const cnt = Number((await redis.get(countKey)) ?? "0");
+  expect(cnt).toBe(1);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("idempotencyKey: delayed TTL refresh cannot fork duplicate runs", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const countKey = `${prefix}:t:idem-race-fix-count`;
+
+  const wf = defineWorkflow({ name: "idem-race-fix", queue: "q9_race_fix" }, async ({ step }) => {
+    await step.run({ name: "do" }, async () => {
+      await redis.incr(countKey);
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q9_race_fix"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const originalExpire = redis.expire.bind(redis);
+  let delayedExpire = false;
+  redis.expire = (async (...args: Parameters<RedisClient["expire"]>) => {
+    if (!delayedExpire) {
+      delayedExpire = true;
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    return await originalExpire(...args);
+  }) as RedisClient["expire"];
+
+  try {
+    const [h1, h2] = await Promise.all([
+      wf.run({}, { idempotencyKey: "race-key" }),
+      wf.run({}, { idempotencyKey: "race-key" }),
+    ]);
+
+    expect(h1.id).toBe(h2.id);
+
+    const [out1, out2] = await Promise.all([
+      h1.result({ timeoutMs: 5000, pollMs: 50 }),
+      h2.result({ timeoutMs: 5000, pollMs: 50 }),
+    ]);
+    expect(out1).toEqual({ ok: true });
+    expect(out2).toEqual({ ok: true });
+
+    const count = Number((await redis.get(countKey)) ?? "0");
+    expect(count).toBe(1);
+  } finally {
+    redis.expire = originalExpire;
+    await worker.stop();
+    redis.close();
+  }
+});
+
+test("enqueue: producer-side zadd failure does not leave runs orphaned", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow({ name: "enqueue-atomic", queue: "q_enqueue_atomic" }, async () => ({ ok: true }));
+  await client.syncRegistry(getDefaultRegistry());
+
+  const originalZadd = redis.zadd.bind(redis);
+  let injected = false;
+  redis.zadd = (async (...args: Parameters<RedisClient["zadd"]>) => {
+    if (!injected) {
+      injected = true;
+      throw new Error("injected zadd failure");
+    }
+    return await originalZadd(...args);
+  }) as RedisClient["zadd"];
+
+  let handle: Awaited<ReturnType<typeof wf.run>>;
+  try {
+    handle = await wf.run({});
+  } finally {
+    redis.zadd = originalZadd;
+  }
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_enqueue_atomic"],
+    runtime: { leaseMs: 500 },
+  });
+
+  try {
+    const out = await handle.result({ timeoutMs: 6000, pollMs: 50 });
+    expect(out).toEqual({ ok: true });
+  } finally {
+    await worker.stop();
+    redis.close();
+  }
+});
+
+test("idempotencyKey: delimiter-like workflow/key pairs do not collide", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wfA = defineWorkflow({ name: "idem:a", queue: "q9a" }, async () => ({ workflow: "idem:a" }));
+  const wfB = defineWorkflow({ name: "idem:a:b", queue: "q9b" }, async () => ({ workflow: "idem:a:b" }));
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q9a", "q9b"],
+    concurrency: 2,
+    runtime: { leaseMs: 500 },
+  });
+
+  const [h1, h2] = await Promise.all([
+    wfA.run({}, { idempotencyKey: "b:c" }),
+    wfB.run({}, { idempotencyKey: "c" }),
+  ]);
+
+  expect(h1.id).not.toBe(h2.id);
+
+  const [out1, out2] = await Promise.all([
+    h1.result({ timeoutMs: 5000, pollMs: 50 }),
+    h2.result({ timeoutMs: 5000, pollMs: 50 }),
+  ]);
+
+  expect(out1).toEqual({ workflow: "idem:a" });
+  expect(out2).toEqual({ workflow: "idem:a:b" });
+
+  await worker.stop();
+  redis.close();
+});
+
+test("idempotencyTtl: short TTL expires and allows a new run with same key", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const countKey = `${prefix}:t:idemTtlCount`;
+
+  const wf = defineWorkflow({ name: "idem-ttl-wf", queue: "q_idem_ttl" }, async ({ step }) => {
+    await step.run({ name: "count" }, async () => {
+      await redis.incr(countKey);
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_idem_ttl"],
+    runtime: { leaseMs: 500 },
+  });
+
+  // First run with 1-second TTL
+  const h1 = await wf.run({}, { idempotencyKey: "ttl-key", idempotencyTtl: 1 });
+  const out1 = await h1.result({ timeoutMs: 5000, pollMs: 50 });
+  expect(out1).toEqual({ ok: true });
+
+  // Same key within TTL — returns existing run
+  const h2 = await wf.run({}, { idempotencyKey: "ttl-key", idempotencyTtl: 1 });
+  expect(h2.id).toBe(h1.id);
+
+  // Wait for TTL to expire
+  await new Promise((r) => setTimeout(r, 1200));
+
+  // Same key after TTL — creates a new run
+  const h3 = await wf.run({}, { idempotencyKey: "ttl-key", idempotencyTtl: 1 });
+  expect(h3.id).not.toBe(h1.id);
+
+  const out3 = await h3.result({ timeoutMs: 5000, pollMs: 50 });
+  expect(out3).toEqual({ ok: true });
+
+  // Handler executed twice (once per unique run)
+  const count = Number((await redis.get(countKey)) ?? "0");
+  expect(count).toBe(2);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("emitEvent idempotency: same key across different events does not collide", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const countKey = `${prefix}:t:evtScopeCount`;
+
+  defineWorkflow(
+    {
+      name: "evt-idem-scope",
+      queue: "q10_scope",
+      triggers: { events: ["dup.event.a", "dup.event.b"] },
+    },
+    async ({ step }) => {
+      await step.run({ name: "count" }, async () => {
+        await redis.incr(countKey);
+        return true;
+      });
+      return { ok: true };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q10_scope"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const runIdsA = await client.emitEvent("dup.event.a", { a: 1 }, { idempotencyKey: "evt_shared" });
+  const runIdsB = await client.emitEvent("dup.event.b", { b: 1 }, { idempotencyKey: "evt_shared" });
+
+  expect(runIdsA.length).toBe(1);
+  expect(runIdsB.length).toBe(1);
+  expect(runIdsA[0]).not.toBe(runIdsB[0]);
+
+  await Promise.all([
+    client.makeRunHandle(runIdsA[0]!).result({ timeoutMs: 5000, pollMs: 50 }),
+    client.makeRunHandle(runIdsB[0]!).result({ timeoutMs: 5000, pollMs: 50 }),
+  ]);
+
+  const cnt = Number((await redis.get(countKey)) ?? "0");
+  expect(cnt).toBe(2);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("scheduleEvent: delayed fan-out is idempotent", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const event = "schedule.event";
+  const countKey = `${prefix}:t:schedule-event-count`;
+
+  defineWorkflow(
+    { name: "schedule-consumer", queue: "q10_schedule", triggers: { events: [event] } },
+    async ({ step }) => {
+      await step.run({ name: "count" }, async () => {
+        await redis.incr(countKey);
+        return true;
+      });
+      return { ok: true };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q10_schedule"],
+    runtime: { leaseMs: 500 },
+  });
+
+  try {
+    const availableAt = new Date(Date.now() + 1200);
+    const [runIds1, runIds2] = await Promise.all([
+      client.scheduleEvent(event, { x: 1 }, { availableAt, idempotencyKey: "sched-shared" }),
+      client.scheduleEvent(event, { x: 1 }, { availableAt, idempotencyKey: "sched-shared" }),
+    ]);
+
+    expect(runIds1.length).toBe(1);
+    expect(runIds2.length).toBe(1);
+    expect(runIds1[0]).toBe(runIds2[0]);
+
+    const runId = runIds1[0]!;
+    const stateBefore = await client.getRun(runId);
+    expect(stateBefore?.status).toBe("scheduled");
+
+    const out = await client.makeRunHandle(runId).result({ timeoutMs: 7000, pollMs: 50 });
+    expect(out).toEqual({ ok: true });
+
+    const stateAfter = await client.getRun(runId);
+    expect((stateAfter?.startedAt ?? 0) + 40).toBeGreaterThanOrEqual(availableAt.getTime());
+
+    const count = Number((await redis.get(countKey)) ?? "0");
+    expect(count).toBe(1);
+  } finally {
+    await worker.stop();
+    redis.close();
+  }
+});
+
+test("emitEvent: stale subscribers are pruned and do not break fan-out", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const event = "stale.subscribers.event";
+  defineWorkflow(
+    { name: "stale-subscriber-live", queue: "q10_stale_subs", triggers: { events: [event] } },
+    async () => ({ ok: true }),
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q10_stale_subs"],
+    runtime: { leaseMs: 500 },
+  });
+
+  try {
+    await redis.sadd(keys.eventWorkflows(prefix, event), "stale-subscriber-ghost");
+
+    const runIds = await client.emitEvent(event, { v: 1 });
+    expect(runIds.length).toBe(1);
+
+    const subscribers = await redis.smembers(keys.eventWorkflows(prefix, event));
+    expect(subscribers.includes("stale-subscriber-ghost")).toBe(false);
+
+    const out = await client.makeRunHandle(runIds[0]!).result({ timeoutMs: 5000, pollMs: 50 });
+    expect(out).toEqual({ ok: true });
+  } finally {
+    await worker.stop();
+    redis.close();
+  }
+});
+
+test("input validation: invalid input fails once and is not retried", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  defineWorkflow(
+    {
+      name: "validate-wf",
+      queue: "q11",
+      schema: z.object({ x: z.number() }),
+      retries: { maxAttempts: 3 },
+    },
+    async () => {
+      return { ok: true };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q11"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await client.runByName("validate-wf", { x: "nope" }, { queueOverride: "q11" });
+
+  await waitFor(
+    async () => {
+      const st = await client.getRun(handle.id);
+      return st?.status === "failed";
+    },
+    { timeoutMs: 6000, label: "validation fail" },
+  );
+
+  const st = await client.getRun(handle.id);
+  expect(st?.status).toBe("failed");
+  expect(st?.attempt).toBe(1);
+  expect((st?.error as any)?.kind).toBe("validation");
+
+  const schedKey = `${prefix}:q:q11:scheduled`;
+  const scheduled = await redis.zrange(schedKey, 0, -1);
+  expect(scheduled.includes(handle.id)).toBe(false);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("unknown workflow: run fails and is not retried", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["qx"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await client.runByName("no-such-wf", { ok: true }, { queueOverride: "qx" });
+
+  await waitFor(
+    async () => {
+      const st = await client.getRun(handle.id);
+      return st?.status === "failed";
+    },
+    { timeoutMs: 6000, label: "unknown wf" },
+  );
+
+  const st = await client.getRun(handle.id);
+  expect(st?.status).toBe("failed");
+  expect(st?.attempt).toBe(1);
+  expect((st?.error as any)?.kind).toBe("unknown_workflow");
+
+  await worker.stop();
+  redis.close();
+});
+
+test("runByName: unknown workflow without queueOverride fails fast", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  await expect(client.runByName("no-such-wf", { ok: true })).rejects.toBeInstanceOf(UnknownWorkflowError);
+
+  const runs = await client.listRuns({ limit: 1 });
+  expect(runs).toEqual([]);
+
+  redis.close();
+});
+
+test("cancel during step: run becomes canceled and step error kind is canceled", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow({ name: "cancel-mid-step", queue: "q12" }, async ({ step }) => {
+    await step.run({ name: "slow" }, async () => {
+      await new Promise((r) => setTimeout(r, 2000));
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q12"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+
+  await waitFor(
+    async () => {
+      const st = await client.getRun(handle.id);
+      return st?.status === "running";
+    },
+    { timeoutMs: 4000, label: "running" },
+  );
+
+  await client.cancelRun(handle.id, { reason: "test" });
+
+  await waitFor(
+    async () => {
+      const st = await client.getRun(handle.id);
+      return st?.status === "canceled";
+    },
+    { timeoutMs: 6000, label: "canceled" },
+  );
+
+  const st = await client.getRun(handle.id);
+  expect(st?.status).toBe("canceled");
+
+  const steps = await client.getRunSteps(handle.id);
+  expect(steps.length).toBe(1);
+  expect((steps[0]?.error as any)?.kind).toBe("canceled");
+
+  // `result()` should reject with CanceledError.
+  await expect(handle.result({ timeoutMs: 1000, pollMs: 50 })).rejects.toBeInstanceOf(CanceledError);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("terminal run re-queued is ignored (no re-execution)", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q13";
+  const countKey = `${prefix}:t:termCount`;
+
+  const wf = defineWorkflow({ name: "term-wf", queue }, async ({ step }) => {
+    await step.run({ name: "do" }, async () => {
+      await redis.incr(countKey);
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    concurrency: 2,
+    runtime: { leaseMs: 400, reaperIntervalMs: 50 },
+  });
+
+  const handle = await wf.run({});
+  const out = await handle.result({ timeoutMs: 4000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const cnt1 = Number((await redis.get(countKey)) ?? "0");
+  expect(cnt1).toBe(1);
+
+  // Malicious/buggy duplicate enqueue of the same run id.
+  await redis.lpush(`${prefix}:q:${queue}:ready`, handle.id);
+  await new Promise((r) => setTimeout(r, 400));
+
+  const cnt2 = Number((await redis.get(countKey)) ?? "0");
+  expect(cnt2).toBe(1);
+
+  const st = await client.getRun(handle.id);
+  expect(st?.status).toBe("succeeded");
+  expect(st?.attempt).toBe(1);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("lease+reaper: long running step is not duplicated", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q14";
+  const countKey = `${prefix}:t:leaseCount`;
+
+  const wf = defineWorkflow({ name: "lease-wf", queue }, async ({ step }) => {
+    await step.run({ name: "long" }, async () => {
+      await redis.incr(countKey);
+      await new Promise((r) => setTimeout(r, 700));
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    concurrency: 2,
+    runtime: { leaseMs: 200, reaperIntervalMs: 20, blmoveTimeoutSec: 0.2 },
+  });
+
+  const handle = await wf.run({});
+  const out = await handle.result({ timeoutMs: 8000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const cnt = Number((await redis.get(countKey)) ?? "0");
+  expect(cnt).toBe(1);
+
+  const st = await client.getRun(handle.id);
+  expect(st?.attempt).toBe(1);
+
+  await worker.stop();
+  redis.close();
+});
+
+test(
+  "cron lock: two workers do not double-schedule",
+  async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q15";
+  const counterKey = `${prefix}:t:cronLockCount`;
+
+  defineWorkflow(
+    {
+      name: "cron-lock-wf",
+      queue,
+      triggers: { cron: [{ expression: "*/1 * * * * *" }] },
+    },
+    async ({ step }) => {
+      await step.run({ name: "tick" }, async () => {
+        await redis.incr(counterKey);
+        return true;
+      });
+      return { ok: true };
+    },
+  );
+
+  const w1 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+  const w2 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+
+  await new Promise((r) => setTimeout(r, 3500));
+  const count = Number((await redis.get(counterKey)) ?? "0");
+  // With a single scheduler, we expect ~3-4 ticks. Allow some slack for timing.
+  expect(count).toBeGreaterThan(0);
+  expect(count).toBeLessThan(7);
+
+  await w1.stop();
+  await w2.stop();
+  redis.close();
+  },
+  { timeout: 15_000 },
+);
+
+test(
+  "production: parent waits for child; child retries and caches steps",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+    const client = createClient({ redis, prefix });
+    setDefaultClient(client);
+
+    const childStep1CountKey = `${prefix}:t:childStep1Count`;
+    const childFailOnceKey = `${prefix}:t:childFailOnce`;
+    const parentBeforeKey = `${prefix}:t:parentBefore`;
+
+    const child = defineWorkflow(
+      {
+        name: "child-wf",
+        queue: "q_child",
+        retries: { maxAttempts: 2 },
+      },
+      async ({ step, run }) => {
+        await step.run({ name: "fetch" }, async () => {
+          await redis.incr(childStep1CountKey);
+          return { ok: true };
+        });
+
+        await step.run({ name: "send" }, async () => {
+          const seen = await redis.get(childFailOnceKey);
+          if (!seen) {
+            await redis.set(childFailOnceKey, "1");
+            throw new Error("transient child failure");
+          }
+          return true;
+        });
+
+        return { ok: true, attempt: run.attempt };
+      },
+    );
+
+    const parent = defineWorkflow(
+      {
+        name: "parent-wf",
+        queue: "q_parent",
+      },
+      async ({ step }) => {
+        await step.run({ name: "before" }, async () => {
+          await redis.incr(parentBeforeKey);
+          return true;
+        });
+
+        const childOut = await step.run({ name: "child" }, async () => {
+          const h = await child.run({});
+          return await h.result({ timeoutMs: 10_000, pollMs: 50 });
+        });
+
+        return { ok: true, child: childOut };
+      },
+    );
+
+    const worker = await startWorker({
+      redis,
+      prefix,
+      queues: ["q_parent", "q_child"],
+      concurrency: 2,
+      runtime: { leaseMs: 500 },
+    });
+
+    const handle = await parent.run({});
+    const out = await handle.result({ timeoutMs: 15_000, pollMs: 50 });
+    expect(out.ok).toBe(true);
+    expect(out.child.ok).toBe(true);
+    expect(out.child.attempt).toBe(2);
+
+    const childStep1Count = Number((await redis.get(childStep1CountKey)) ?? "0");
+    expect(childStep1Count).toBe(1);
+
+    const parentBeforeCount = Number((await redis.get(parentBeforeKey)) ?? "0");
+    expect(parentBeforeCount).toBe(1);
+
+    const childRuns = await client.listRuns({ workflow: "child-wf", limit: 10 });
+    expect(childRuns.length).toBe(1);
+    const childState = await client.getRun(childRuns[0]!.id);
+    expect(childState?.status).toBe("succeeded");
+    expect(childState?.attempt).toBe(2);
+
+    await worker.stop();
+    redis.close();
+  },
+  { timeout: 25_000 },
+);
+
+test(
+  "production: runs queued before worker start are picked and status indexes move",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+    const client = createClient({ redis, prefix });
+    setDefaultClient(client);
+
+    const queue = "q_status";
+    const wf = defineWorkflow({ name: "status-wf", queue }, async ({ step }) => {
+      await step.run({ name: "sleep" }, async () => {
+        await new Promise((r) => setTimeout(r, 350));
+        return true;
+      });
+      return { ok: true };
+    });
+
+    const handle = await wf.run({});
+
+    const queuedIndex = `${prefix}:runs:status:queued`;
+    const queuedMembers = await redis.zrange(queuedIndex, 0, -1);
+    expect(queuedMembers.includes(handle.id)).toBe(true);
+
+    const worker = await startWorker({
+      redis,
+      prefix,
+      queues: [queue],
+      runtime: { leaseMs: 500 },
+    });
+
+    await waitFor(
+      async () => (await client.getRun(handle.id))?.status === "running",
+      { timeoutMs: 8000, label: "becomes running" },
+    );
+
+    const runningMembers = await redis.zrange(`${prefix}:runs:status:running`, 0, -1);
+    expect(runningMembers.includes(handle.id)).toBe(true);
+    const queuedMembers2 = await redis.zrange(queuedIndex, 0, -1);
+    expect(queuedMembers2.includes(handle.id)).toBe(false);
+
+    const out = await handle.result({ timeoutMs: 8000, pollMs: 50 });
+    expect(out).toEqual({ ok: true });
+
+    const succeededMembers = await redis.zrange(`${prefix}:runs:status:succeeded`, 0, -1);
+    expect(succeededMembers.includes(handle.id)).toBe(true);
+    const runningMembers2 = await redis.zrange(`${prefix}:runs:status:running`, 0, -1);
+    expect(runningMembers2.includes(handle.id)).toBe(false);
+
+    await worker.stop();
+    redis.close();
+  },
+  { timeout: 20_000 },
+);
+
+test(
+  "production: registry sync updates triggers (events move, cron removed)",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+    const client = createClient({ redis, prefix });
+    setDefaultClient(client);
+
+    const name = "update-wf";
+    const eventA = "evt.a";
+    const eventB = "evt.b";
+
+    defineWorkflow(
+      {
+        name,
+        queue: "q_update",
+        triggers: {
+          events: [eventA],
+          cron: [{ expression: "*/1 * * * * *" }],
+        },
+      },
+      async () => ({ ok: true }),
+    );
+
+    await client.syncRegistry(getDefaultRegistry());
+
+    const subsA1 = await redis.smembers(`${prefix}:event:${eventA}:workflows`);
+    const subsB1 = await redis.smembers(`${prefix}:event:${eventB}:workflows`);
+    expect(subsA1.includes(name)).toBe(true);
+    expect(subsB1.includes(name)).toBe(false);
+
+    const workflowKey = `${prefix}:workflow:${name}`;
+    const cronIdsJson = await redis.hget(workflowKey, "cronIdsJson");
+    expect(cronIdsJson).not.toBeNull();
+    const cronIds = JSON.parse(cronIdsJson!) as string[];
+    expect(cronIds.length).toBe(1);
+    const cronId = cronIds[0]!;
+    expect(await redis.hget(`${prefix}:cron:def`, cronId)).not.toBeNull();
+    const cronNext = await redis.zrange(`${prefix}:cron:next`, 0, -1);
+    expect(cronNext.includes(cronId)).toBe(true);
+
+    // Simulate a new deployment: same workflow name, different triggers.
+    __unstableResetDefaultRegistryForTests();
+    defineWorkflow(
+      {
+        name,
+        queue: "q_update",
+        triggers: { events: [eventB] },
+      },
+      async () => ({ ok: true }),
+    );
+
+    await client.syncRegistry(getDefaultRegistry());
+
+    const subsA2 = await redis.smembers(`${prefix}:event:${eventA}:workflows`);
+    const subsB2 = await redis.smembers(`${prefix}:event:${eventB}:workflows`);
+    expect(subsA2.includes(name)).toBe(false);
+    expect(subsB2.includes(name)).toBe(true);
+
+    // Old cron removed.
+    expect(await redis.hget(`${prefix}:cron:def`, cronId)).toBeNull();
+    const cronNext2 = await redis.zrange(`${prefix}:cron:next`, 0, -1);
+    expect(cronNext2.includes(cronId)).toBe(false);
+
+    redis.close();
+  },
+  { timeout: 20_000 },
+);
+
+test(
+  "production: retry uses delayed backoff (attempt 2 starts later)",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+    const client = createClient({ redis, prefix });
+    setDefaultClient(client);
+
+    const queue = "q_backoff";
+    const t1Key = `${prefix}:t:attempt1`;
+    const t2Key = `${prefix}:t:attempt2`;
+
+    const wf = defineWorkflow(
+      {
+        name: "backoff-wf",
+        queue,
+        retries: { maxAttempts: 2 },
+      },
+      async ({ run }) => {
+        const key = run.attempt === 1 ? t1Key : t2Key;
+        await redis.set(key, String(Date.now()));
+        if (run.attempt === 1) throw new Error("fail once");
+        return { ok: true };
+      },
+    );
+
+    const worker = await startWorker({
+      redis,
+      prefix,
+      queues: [queue],
+      runtime: { leaseMs: 500 },
+    });
+
+    const handle = await wf.run({});
+    const out = await handle.result({ timeoutMs: 15_000, pollMs: 50 });
+    expect(out).toEqual({ ok: true });
+
+    const t1 = Number((await redis.get(t1Key)) ?? "0");
+    const t2 = Number((await redis.get(t2Key)) ?? "0");
+    expect(t1).toBeGreaterThan(0);
+    expect(t2).toBeGreaterThan(0);
+    expect(t2 - t1).toBeGreaterThan(200);
+
+    const st = await client.getRun(handle.id);
+    expect(st?.attempt).toBe(2);
+    expect(st?.status).toBe("succeeded");
+
+    await worker.stop();
+    redis.close();
+  },
+  { timeout: 25_000 },
+);
+
+test(
+  "production: cron leader failover (ticks continue after one worker stops)",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+    const client = createClient({ redis, prefix });
+    setDefaultClient(client);
+
+    const queue = "q_failover";
+    const counterKey = `${prefix}:t:cronFailoverCount`;
+
+    defineWorkflow(
+      {
+        name: "cron-failover-wf",
+        queue,
+        triggers: { cron: [{ expression: "*/1 * * * * *" }] },
+      },
+      async ({ step }) => {
+        await step.run({ name: "tick" }, async () => {
+          await redis.incr(counterKey);
+          return true;
+        });
+        return { ok: true };
+      },
+    );
+
+    const w1 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+    const w2 = await startWorker({ redis, prefix, queues: [queue], concurrency: 1, runtime: { leaseMs: 500 } });
+
+    await waitFor(
+      async () => Number((await redis.get(counterKey)) ?? "0") >= 1,
+      { timeoutMs: 8000, label: "first tick" },
+    );
+
+    await w1.stop();
+    const before = Number((await redis.get(counterKey)) ?? "0");
+
+    // After the lock expires, the other worker should continue ticking.
+    await waitFor(
+      async () => Number((await redis.get(counterKey)) ?? "0") > before,
+      { timeoutMs: 10_000, label: "ticks continue" },
+    );
+
+    await w2.stop();
+    redis.close();
+  },
+  { timeout: 25_000 },
+);
+
+test("listRuns: status + workflow filters are applied together", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q_filters";
+
+  const succeeds = defineWorkflow({ name: "filters-success", queue }, async () => ({ ok: true }));
+  const fails = defineWorkflow({ name: "filters-fail", queue }, async () => {
+    throw new Error("expected failure");
+  });
+
+  const worker = await startWorker({ redis, prefix, queues: [queue], runtime: { leaseMs: 500 } });
+
+  const successHandle = await succeeds.run({});
+  const failHandle = await fails.run({});
+
+  await successHandle.result({ timeoutMs: 4000, pollMs: 50 });
+  await waitFor(
+    async () => (await client.getRun(failHandle.id))?.status === "failed",
+    { timeoutMs: 6000, label: "failed run" },
+  );
+
+  const shouldBeEmpty = await client.listRuns({
+    workflow: "filters-success",
+    status: "failed" satisfies RunStatus,
+    limit: 20,
+  });
+  expect(shouldBeEmpty).toEqual([]);
+
+  const failedForWorkflow = await client.listRuns({
+    workflow: "filters-fail",
+    status: "failed" satisfies RunStatus,
+    limit: 20,
+  });
+  expect(failedForWorkflow.length).toBeGreaterThan(0);
+  expect(failedForWorkflow.some((r) => r.id === failHandle.id)).toBe(true);
+  for (const run of failedForWorkflow) {
+    expect(run.status).toBe("failed");
+    expect(run.workflow).toBe("filters-fail");
+  }
+
+  await worker.stop();
+  redis.close();
+});
+
+test("cron trigger ids: same custom id in two workflows does not collide", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  defineWorkflow(
+    {
+      name: "cron-id-a",
+      queue: "qa",
+      triggers: { cron: [{ id: "shared", expression: "*/5 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  defineWorkflow(
+    {
+      name: "cron-id-b",
+      queue: "qb",
+      triggers: { cron: [{ id: "shared", expression: "*/5 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  await client.syncRegistry(getDefaultRegistry());
+
+  const idsA = JSON.parse((await redis.hget(`${prefix}:workflow:cron-id-a`, "cronIdsJson")) ?? "[]") as string[];
+  const idsB = JSON.parse((await redis.hget(`${prefix}:workflow:cron-id-b`, "cronIdsJson")) ?? "[]") as string[];
+
+  expect(idsA.length).toBe(1);
+  expect(idsB.length).toBe(1);
+  expect(idsA[0]).not.toBe(idsB[0]);
+
+  expect(await redis.hget(`${prefix}:cron:def`, idsA[0]!)).not.toBeNull();
+  expect(await redis.hget(`${prefix}:cron:def`, idsB[0]!)).not.toBeNull();
+
+  redis.close();
+});
+
+test("syncRegistry: cron trigger with explicit null input preserves null payload", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  const workflowName = "cron-null-input";
+
+  defineWorkflow(
+    {
+      name: workflowName,
+      queue: "q-cron-null",
+      triggers: { cron: [{ id: "null-input", expression: "*/5 * * * * *", input: null }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  await client.syncRegistry(getDefaultRegistry());
+
+  const workflowKey = `${prefix}:workflow:${workflowName}`;
+  const cronIds = JSON.parse((await redis.hget(workflowKey, "cronIdsJson")) ?? "[]") as string[];
+  expect(cronIds.length).toBe(1);
+
+  const cronDefRaw = await redis.hget(`${prefix}:cron:def`, cronIds[0]!);
+  expect(cronDefRaw).not.toBeNull();
+
+  const cronDef = safeJsonParse<{ inputJson: string }>(cronDefRaw!);
+  const parsedInput = safeJsonParse(cronDef.inputJson);
+  expect(parsedInput).toBeNull();
+
+  redis.close();
+});
+
+test("syncRegistry: invalid cron expression removes existing next schedule for same custom id", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  const workflowName = "cron-invalid-update";
+  const workflowKey = `${prefix}:workflow:${workflowName}`;
+  const cronNextKey = `${prefix}:cron:next`;
+
+  defineWorkflow(
+    {
+      name: workflowName,
+      queue: "q-cron-invalid",
+      triggers: { cron: [{ id: "stable", expression: "*/5 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  await client.syncRegistry(getDefaultRegistry());
+
+  const cronIds = JSON.parse((await redis.hget(workflowKey, "cronIdsJson")) ?? "[]") as string[];
+  expect(cronIds.length).toBe(1);
+  const cronId = cronIds[0]!;
+
+  const before = await redis.zrange(cronNextKey, 0, -1);
+  expect(before.includes(cronId)).toBe(true);
+
+  __unstableResetDefaultRegistryForTests();
+  defineWorkflow(
+    {
+      name: workflowName,
+      queue: "q-cron-invalid",
+      triggers: { cron: [{ id: "stable", expression: "not a valid cron" }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  await client.syncRegistry(getDefaultRegistry());
+
+  const after = await redis.zrange(cronNextKey, 0, -1);
+  expect(after.includes(cronId)).toBe(false);
+
+  redis.close();
+});
+
+test("syncRegistry: removes stale workflow metadata (events + cron)", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  const workflowName = "stale-workflow";
+  const eventName = "stale.event";
+
+  defineWorkflow(
+    {
+      name: workflowName,
+      queue: "q-stale",
+      triggers: { events: [eventName], cron: [{ id: "stale", expression: "*/10 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  await client.syncRegistry(getDefaultRegistry());
+
+  const workflowKey = `${prefix}:workflow:${workflowName}`;
+  const cronIds = JSON.parse((await redis.hget(workflowKey, "cronIdsJson")) ?? "[]") as string[];
+  expect(cronIds.length).toBe(1);
+  const cronId = cronIds[0]!;
+
+  expect((await redis.smembers(`${prefix}:event:${eventName}:workflows`)).includes(workflowName)).toBe(true);
+  expect(await redis.hget(`${prefix}:cron:def`, cronId)).not.toBeNull();
+
+  // Force stale age beyond grace period and sync an empty registry.
+  await redis.hset(workflowKey, { updatedAt: "1" });
+  __unstableResetDefaultRegistryForTests();
+  await client.syncRegistry(getDefaultRegistry());
+
+  expect((await redis.smembers(`${prefix}:workflows`)).includes(workflowName)).toBe(false);
+  expect((await redis.smembers(`${prefix}:event:${eventName}:workflows`)).includes(workflowName)).toBe(false);
+  expect(await redis.hget(workflowKey, "queue")).toBeNull();
+  expect(await redis.hget(`${prefix}:cron:def`, cronId)).toBeNull();
+  const cronNext = await redis.zrange(`${prefix}:cron:next`, 0, -1);
+  expect(cronNext.includes(cronId)).toBe(false);
+
+  redis.close();
+});
+
+test("syncRegistry: stale cleanup is isolated by owner", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  __unstableResetDefaultRegistryForTests();
+  defineWorkflow(
+    {
+      name: "owner-a-wf",
+      queue: "qa",
+      triggers: { events: ["owner.a"], cron: [{ id: "a", expression: "*/30 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+  await client.syncRegistry(getDefaultRegistry(), { owner: "svc-a" });
+
+  __unstableResetDefaultRegistryForTests();
+  defineWorkflow(
+    {
+      name: "owner-b-wf",
+      queue: "qb",
+      triggers: { events: ["owner.b"], cron: [{ id: "b", expression: "*/30 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+  await client.syncRegistry(getDefaultRegistry(), { owner: "svc-b" });
+
+  await redis.hset(`${prefix}:workflow:owner-a-wf`, { updatedAt: "1" });
+  await redis.hset(`${prefix}:workflow:owner-b-wf`, { updatedAt: "1" });
+
+  __unstableResetDefaultRegistryForTests();
+  await client.syncRegistry(getDefaultRegistry(), { owner: "svc-a" });
+
+  expect(await redis.hget(`${prefix}:workflow:owner-a-wf`, "queue")).toBeNull();
+  expect(await redis.hget(`${prefix}:workflow:owner-b-wf`, "queue")).not.toBeNull();
+  expect((await redis.smembers(`${prefix}:workflows`)).includes("owner-a-wf")).toBe(false);
+  expect((await redis.smembers(`${prefix}:workflows`)).includes("owner-b-wf")).toBe(true);
+
+  redis.close();
+});
+
+test("cancelRun: terminal runs are unchanged", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow({ name: "cancel-terminal", queue: "q_cancel_terminal" }, async () => ({ ok: true }));
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_cancel_terminal"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+  await handle.result({ timeoutMs: 4000, pollMs: 50 });
+
+  const before = await client.getRun(handle.id);
+  const canceled = await client.cancelRun(handle.id, { reason: "late" });
+  const after = await client.getRun(handle.id);
+
+  expect(canceled).toBe(false);
+  expect(after?.status).toBe("succeeded");
+  expect(after?.cancelRequestedAt).toBe(before?.cancelRequestedAt);
+  expect(after?.cancelReason).toBe(before?.cancelReason);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("output serialization: non-JSON output fails once and is not stuck", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow(
+    {
+      name: "serialization-fail",
+      queue: "q_serial",
+      retries: { maxAttempts: 3 },
+    },
+    async () => ({ bad: 1n }),
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_serial"],
+    runtime: { leaseMs: 300, reaperIntervalMs: 50, blmoveTimeoutSec: 0.2 },
+  });
+
+  const handle = await wf.run({});
+  await waitFor(
+    async () => (await client.getRun(handle.id))?.status === "failed",
+    { timeoutMs: 8000, label: "serialization failure" },
+  );
+
+  const state = await client.getRun(handle.id);
+  expect(state?.status).toBe("failed");
+  expect(state?.attempt).toBe(1);
+  expect((state?.error as any)?.kind).toBe("serialization");
+
+  const ready = await redis.lrange(`${prefix}:q:q_serial:ready`, 0, -1);
+  const processing = await redis.lrange(`${prefix}:q:q_serial:processing`, 0, -1);
+  expect(ready.includes(handle.id)).toBe(false);
+  expect(processing.includes(handle.id)).toBe(false);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("retry step sequence: new steps keep monotonic order after cached steps", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const failOnceKey = `${prefix}:t:seq-fail-once`;
+
+  const wf = defineWorkflow(
+    {
+      name: "seq-retry",
+      queue: "q_seq",
+      retries: { maxAttempts: 2 },
+    },
+    async ({ step }) => {
+      await step.run({ name: "step1" }, async () => true);
+
+      await step.run({ name: "step2" }, async () => {
+        const seen = await redis.get(failOnceKey);
+        if (!seen) {
+          await redis.set(failOnceKey, "1");
+          throw new Error("fail once");
+        }
+        return true;
+      });
+
+      await step.run({ name: "step3" }, async () => true);
+      return { ok: true };
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_seq"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await wf.run({});
+  await handle.result({ timeoutMs: 12_000, pollMs: 50 });
+
+  const rawSteps = await redis.hgetall(`${prefix}:run:${handle.id}:steps`);
+  const seq1 = safeJsonParse<any>(rawSteps.step1 ?? null).seq;
+  const seq2 = safeJsonParse<any>(rawSteps.step2 ?? null).seq;
+  const seq3 = safeJsonParse<any>(rawSteps.step3 ?? null).seq;
+  expect(seq1).toBeLessThan(seq2);
+  expect(seq2).toBeLessThan(seq3);
+
+  const steps = await client.getRunSteps(handle.id);
+  expect(steps.map((s) => s.name)).toEqual(["step1", "step2", "step3"]);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("listRuns: negative offset is clamped to zero", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow({ name: "offset-wf", queue: "q_offset" }, async () => ({ ok: true }));
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_offset"],
+    runtime: { leaseMs: 500 },
+  });
+
+  const h1 = await wf.run({});
+  await h1.result({ timeoutMs: 4000, pollMs: 50 });
+  await new Promise((r) => setTimeout(r, 5));
+  const h2 = await wf.run({});
+  await h2.result({ timeoutMs: 4000, pollMs: 50 });
+  await new Promise((r) => setTimeout(r, 5));
+  const h3 = await wf.run({});
+  await h3.result({ timeoutMs: 4000, pollMs: 50 });
+
+  const fromZero = await client.listRuns({ workflow: "offset-wf", limit: 1, offset: 0 });
+  const fromNegative = await client.listRuns({ workflow: "offset-wf", limit: 1, offset: -1 });
+
+  expect(fromZero.length).toBe(1);
+  expect(fromNegative.length).toBe(1);
+  expect(fromNegative[0]!.id).toBe(fromZero[0]!.id);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("json utils: sentinel-shaped objects are preserved as data", () => {
+  const userObject = { __redflow_undefined__: true };
+  const encoded = safeJsonStringify(userObject);
+  const decoded = safeJsonParse<typeof userObject>(encoded);
+  expect(decoded).toEqual(userObject);
+
+  const sentinelShapeWithKind = {
+    __redflow_undefined__: true,
+    __redflow_kind__: "undefined:v2",
+  };
+  const fullEncoded = safeJsonStringify(sentinelShapeWithKind);
+  const fullDecoded = safeJsonParse<typeof sentinelShapeWithKind>(fullEncoded);
+  expect(fullDecoded).toEqual(sentinelShapeWithKind);
+
+  const encodedUndefined = safeJsonStringify(undefined);
+  const decodedUndefined = safeJsonParse(encodedUndefined);
+  expect(decodedUndefined).toBeUndefined();
+
+  const sentinelRaw = '{"__redflow_undefined__":true,"__redflow_kind__":"undefined:v2"}';
+  const decodedSentinelRaw = safeJsonParse<typeof sentinelShapeWithKind>(sentinelRaw);
+  expect(decodedSentinelRaw).toEqual(sentinelShapeWithKind);
+});
+
+test("error serialization: non-serializable thrown values do not wedge a run", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const wf = defineWorkflow(
+    {
+      name: "throw-bigint",
+      queue: "q_bigint",
+      retries: { maxAttempts: 2 },
+    },
+    async () => {
+      throw 1n;
+    },
+  );
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: ["q_bigint"],
+    runtime: { leaseMs: 300, reaperIntervalMs: 50, blmoveTimeoutSec: 0.2 },
+  });
+
+  const handle = await wf.run({});
+  await waitFor(
+    async () => (await client.getRun(handle.id))?.status === "failed",
+    { timeoutMs: 12_000, label: "bigint failure" },
+  );
+
+  const state = await client.getRun(handle.id);
+  expect(state?.status).toBe("failed");
+  expect(state?.attempt).toBe(2);
+  expect((state?.error as any)?.kind).toBe("error");
+  expect(typeof (state?.error as any)?.message).toBe("string");
+
+  const processing = await redis.lrange(`${prefix}:q:q_bigint:processing`, 0, -1);
+  expect(processing.includes(handle.id)).toBe(false);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("cron trigger ids: delimiter-like custom ids do not collide", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  defineWorkflow(
+    {
+      name: "wf:a",
+      queue: "qa",
+      triggers: { cron: [{ id: "b:c", expression: "*/5 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  defineWorkflow(
+    {
+      name: "wf:a:b",
+      queue: "qb",
+      triggers: { cron: [{ id: "c", expression: "*/5 * * * * *" }] },
+    },
+    async () => ({ ok: true }),
+  );
+
+  await client.syncRegistry(getDefaultRegistry());
+
+  const idsA = JSON.parse((await redis.hget(`${prefix}:workflow:wf:a`, "cronIdsJson")) ?? "[]") as string[];
+  const idsB = JSON.parse((await redis.hget(`${prefix}:workflow:wf:a:b`, "cronIdsJson")) ?? "[]") as string[];
+
+  expect(idsA.length).toBe(1);
+  expect(idsB.length).toBe(1);
+  expect(idsA[0]).not.toBe(idsB[0]);
+
+  const defA = await redis.hget(`${prefix}:cron:def`, idsA[0]!);
+  const defB = await redis.hget(`${prefix}:cron:def`, idsB[0]!);
+  expect(defA).not.toBeNull();
+  expect(defB).not.toBeNull();
+
+  const parsedA = JSON.parse(defA!) as { workflow: string };
+  const parsedB = JSON.parse(defB!) as { workflow: string };
+  expect(parsedA.workflow).toBe("wf:a");
+  expect(parsedB.workflow).toBe("wf:a:b");
+
+  redis.close();
+});
+
+test("idempotencyKey: stale pointer is recovered instead of returning missing run", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q_idem_recover";
+  const workflowName = "idem-recover";
+  const idem = "stale-key";
+
+  const wf = defineWorkflow({ name: workflowName, queue }, async () => ({ ok: true }));
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    runtime: { leaseMs: 500 },
+  });
+
+  const staleRunId = `run_stale_${crypto.randomUUID()}`;
+  const idempotencyRedisKey = keys.idempotency(prefix, workflowName, idem);
+  await redis.set(idempotencyRedisKey, staleRunId);
+
+  const handle = await wf.run({}, { idempotencyKey: idem });
+  expect(handle.id).not.toBe(staleRunId);
+
+  const out = await handle.result({ timeoutMs: 5000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const resolved = await redis.get(idempotencyRedisKey);
+  expect(resolved).toBe(handle.id);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("idempotencyKey: partial existing run is repaired and executed", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q_idem_partial";
+  const workflowName = "idem-partial";
+  const idem = "partial-key";
+  const countKey = `${prefix}:t:idem-partial-count`;
+
+  const wf = defineWorkflow({ name: workflowName, queue }, async ({ step }) => {
+    await step.run({ name: "do" }, async () => {
+      await redis.incr(countKey);
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    runtime: { leaseMs: 500 },
+  });
+
+  const runId = `run_partial_${crypto.randomUUID()}`;
+  const idempotencyRedisKey = keys.idempotency(prefix, workflowName, idem);
+
+  // Simulate a producer crash after writing run hash but before queue/index writes.
+  await redis.set(idempotencyRedisKey, runId);
+  await redis.hset(keys.run(prefix, runId), {
+    workflow: workflowName,
+    queue,
+    status: "queued",
+    inputJson: safeJsonStringify({}),
+    attempt: 0,
+    maxAttempts: 1,
+    createdAt: Date.now(),
+    availableAt: "",
+    cancelRequestedAt: "",
+    cancelReason: "",
+  });
+
+  const handle = await wf.run({}, { idempotencyKey: idem });
+  expect(handle.id).toBe(runId);
+
+  const out = await handle.result({ timeoutMs: 6000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const count = Number((await redis.get(countKey)) ?? "0");
+  expect(count).toBe(1);
+
+  await worker.stop();
+  redis.close();
+});
+
+test("syncRegistry: duplicate custom cron ids in one workflow are rejected", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+
+  defineWorkflow(
+    {
+      name: "dup-custom-cron-id",
+      queue: "q_dup_cron_id",
+      triggers: {
+        cron: [
+          { id: "same", expression: "*/5 * * * * *", input: { n: 1 } },
+          { id: "same", expression: "*/7 * * * * *", input: { n: 2 } },
+        ],
+      },
+    },
+    async () => ({ ok: true }),
+  );
+
+  await expect(client.syncRegistry(getDefaultRegistry())).rejects.toThrow("Duplicate cron trigger id");
+
+  redis.close();
+});
+
+test("scheduled promoter: stale scheduled entry does not resurrect terminal run", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q_sched_guard";
+  const wf = defineWorkflow({ name: "sched-guard", queue }, async ({ step }) => {
+    await step.run({ name: "once" }, async () => true);
+    return { ok: true };
+  });
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    runtime: { leaseMs: 400, reaperIntervalMs: 50, blmoveTimeoutSec: 0.2 },
+  });
+
+  const handle = await wf.run({});
+  const out = await handle.result({ timeoutMs: 5000, pollMs: 50 });
+  expect(out).toEqual({ ok: true });
+
+  const firstState = await client.getRun(handle.id);
+  expect(firstState?.status).toBe("succeeded");
+  expect(firstState?.attempt).toBe(1);
+
+  await redis.zadd(`${prefix}:q:${queue}:scheduled`, Date.now() - 1, handle.id);
+  await new Promise((r) => setTimeout(r, 600));
+
+  const secondState = await client.getRun(handle.id);
+  expect(secondState?.status).toBe("succeeded");
+  expect(secondState?.attempt).toBe(1);
+
+  await worker.stop();
+  redis.close();
+});
+
+test(
+  "cron scheduler: transient enqueue failure does not drop trigger",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+
+    const queue = "q_cron_retry";
+    const workflowName = "cron-retry";
+    const counterKey = `${prefix}:t:cron-retry-count`;
+
+    defineWorkflow(
+      {
+        name: workflowName,
+        queue,
+        triggers: { cron: [{ expression: "*/1 * * * * *" }] },
+      },
+      async ({ step }) => {
+        await step.run({ name: "tick" }, async () => {
+          await redis.incr(counterKey);
+          return true;
+        });
+        return { ok: true };
+      },
+    );
+
+    let injected = false;
+    const originalRunByName: RedflowClient["runByName"] = RedflowClient.prototype.runByName;
+    const patchedRunByName = (async function (
+      this: RedflowClient,
+      name: string,
+      input: unknown,
+      options?: Parameters<RedflowClient["runByName"]>[2],
+    ): Promise<Awaited<ReturnType<RedflowClient["runByName"]>>> {
+      if (!injected && name === workflowName) {
+        injected = true;
+        throw new Error("injected cron enqueue failure");
+      }
+      return await originalRunByName.call(this, name, input, options);
+    }) as RedflowClient["runByName"];
+
+    RedflowClient.prototype.runByName = patchedRunByName;
+
+    let worker: Awaited<ReturnType<typeof startWorker>> | null = null;
+    try {
+      worker = await startWorker({
+        redis,
+        prefix,
+        queues: [queue],
+        concurrency: 1,
+        runtime: { leaseMs: 500 },
+      });
+
+      await waitFor(
+        async () => Number((await redis.get(counterKey)) ?? "0") >= 1,
+        { timeoutMs: 10_000, label: "cron tick after transient enqueue failure" },
+      );
+      expect(injected).toBe(true);
+    } finally {
+      if (worker) await worker.stop();
+      RedflowClient.prototype.runByName = originalRunByName;
+      redis.close();
+    }
+  },
+  { timeout: 20_000 },
+);
+
+test(
+  "cron scheduler: stale score does not enqueue a catch-up burst",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+    const client = createClient({ redis, prefix });
+    setDefaultClient(client);
+
+    const queue = "q_cron_stale";
+    const workflowName = "cron-stale";
+    const counterKey = `${prefix}:t:cronStaleCount`;
+    const cronLockKey = keys.lockCron(prefix);
+
+    defineWorkflow(
+      {
+        name: workflowName,
+        queue,
+        triggers: { cron: [{ expression: "*/1 * * * * *" }] },
+      },
+      async ({ step }) => {
+        await step.run({ name: "tick" }, async () => {
+          await redis.incr(counterKey);
+          return true;
+        });
+        return { ok: true };
+      },
+    );
+
+    await redis.set(cronLockKey, "manual-test-lock");
+
+    let worker: Awaited<ReturnType<typeof startWorker>> | null = null;
+    try {
+      worker = await startWorker({
+        redis,
+        prefix,
+        queues: [queue],
+        concurrency: 1,
+        runtime: { leaseMs: 500 },
+      });
+
+      const workflowKey = `${prefix}:workflow:${workflowName}`;
+      const cronIds = JSON.parse((await redis.hget(workflowKey, "cronIdsJson")) ?? "[]") as string[];
+      expect(cronIds.length).toBe(1);
+      const cronId = cronIds[0]!;
+
+      await redis.set(counterKey, "0");
+      await redis.zadd(`${prefix}:cron:next`, Date.now() - 5000, cronId);
+      await redis.del(cronLockKey);
+
+      await new Promise((r) => setTimeout(r, 1200));
+
+      const count = Number((await redis.get(counterKey)) ?? "0");
+      expect(count).toBeGreaterThan(0);
+      expect(count).toBeLessThanOrEqual(2);
+    } finally {
+      await redis.del(cronLockKey);
+      if (worker) await worker.stop();
+      redis.close();
+    }
+  },
+  { timeout: 20_000 },
+);
+
+test("workflow names ending with ':runs' do not collide with workflow run indexes", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q_keyspace";
+  const base = defineWorkflow({ name: "keyspace-base", queue }, async () => ({ ok: "base" }));
+  defineWorkflow({ name: "keyspace-base:runs", queue }, async () => ({ ok: "suffix" }));
+
+  expect(keys.workflow(prefix, "keyspace-base:runs")).not.toBe(keys.workflowRuns(prefix, "keyspace-base"));
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    runtime: { leaseMs: 500 },
+  });
+
+  const handle = await base.run({});
+  const out = await handle.result({ timeoutMs: 5000, pollMs: 50 });
+  expect(out).toEqual({ ok: "base" });
+
+  const suffixMeta = await client.getWorkflowMeta("keyspace-base:runs");
+  expect(suffixMeta?.name).toBe("keyspace-base:runs");
+
+  await worker.stop();
+  redis.close();
+});
+
+test("cancelRun race: near-finish cancellation settles as canceled", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q_cancel_late";
+  const wf = defineWorkflow({ name: "cancel-late", queue }, async ({ step }) => {
+    await step.run({ name: "short" }, async () => {
+      await new Promise((r) => setTimeout(r, 100));
+      return true;
+    });
+    return { ok: true };
+  });
+
+  const originalFinalizeRun: RedflowClient["finalizeRun"] = RedflowClient.prototype.finalizeRun;
+  RedflowClient.prototype.finalizeRun = (async function (
+    this: RedflowClient,
+    runId: string,
+    args: Parameters<RedflowClient["finalizeRun"]>[1],
+  ): Promise<void> {
+    if (args.status === "succeeded") {
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    return await originalFinalizeRun.call(this, runId, args);
+  }) as RedflowClient["finalizeRun"];
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    runtime: { leaseMs: 500, blmoveTimeoutSec: 0.2, reaperIntervalMs: 50 },
+  });
+
+  try {
+    const handle = await wf.run({});
+
+    await waitFor(
+      async () => {
+        const state = await client.getRun(handle.id);
+        return state?.status === "running";
+      },
+      { timeoutMs: 4000, label: "run becomes running" },
+    );
+
+    await new Promise((r) => setTimeout(r, 80));
+
+    const cancelPromise = client.cancelRun(handle.id, { reason: "race" });
+
+    const canceled = await cancelPromise;
+    expect(canceled).toBe(true);
+
+    await expect(handle.result({ timeoutMs: 8000, pollMs: 50 })).rejects.toBeInstanceOf(CanceledError);
+
+    const state = await client.getRun(handle.id);
+    expect(state?.status).toBe("canceled");
+    expect(state?.cancelReason).toBe("race");
+  } finally {
+    await worker.stop();
+    RedflowClient.prototype.finalizeRun = originalFinalizeRun;
+    redis.close();
+  }
+});
+
+test("cancelRun race: cancellation requested during finalize wins over success", async () => {
+  const prefix = testPrefix();
+  const redis = new RedisClient(redisServer.url);
+  const client = createClient({ redis, prefix });
+  setDefaultClient(client);
+
+  const queue = "q_cancel_finalize_race";
+  const wf = defineWorkflow({ name: "cancel-finalize-race", queue }, async () => {
+    return { ok: true };
+  });
+
+  const originalFinalizeRun: RedflowClient["finalizeRun"] = RedflowClient.prototype.finalizeRun;
+  let enteredFinalize = false;
+
+  RedflowClient.prototype.finalizeRun = (async function (
+    this: RedflowClient,
+    runId: string,
+    args: Parameters<RedflowClient["finalizeRun"]>[1],
+  ): Promise<void> {
+    if (args.status === "succeeded") {
+      enteredFinalize = true;
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    return await originalFinalizeRun.call(this, runId, args);
+  }) as RedflowClient["finalizeRun"];
+
+  const worker = await startWorker({
+    redis,
+    prefix,
+    queues: [queue],
+    runtime: { leaseMs: 500, blmoveTimeoutSec: 0.2, reaperIntervalMs: 50 },
+  });
+
+  try {
+    const handle = await wf.run({});
+
+    await waitFor(
+      async () => enteredFinalize,
+      { timeoutMs: 5000, label: "run enters finalize" },
+    );
+
+    const canceled = await client.cancelRun(handle.id, { reason: "race" });
+    expect(canceled).toBe(true);
+
+    await waitFor(
+      async () => {
+        const run = await client.getRun(handle.id);
+        return run?.status === "canceled";
+      },
+      { timeoutMs: 6000, label: "run canceled in finalize race" },
+    );
+
+    await expect(handle.result({ timeoutMs: 1000, pollMs: 50 })).rejects.toBeInstanceOf(CanceledError);
+
+    const state = await client.getRun(handle.id);
+    expect(state?.status).toBe("canceled");
+  } finally {
+    await worker.stop();
+    RedflowClient.prototype.finalizeRun = originalFinalizeRun;
+    redis.close();
+  }
+});
+
+test(
+  "worker.stop aborts an in-flight non-cooperative handler",
+  async () => {
+    const prefix = testPrefix();
+    const redis = new RedisClient(redisServer.url);
+    const client = createClient({ redis, prefix });
+    setDefaultClient(client);
+
+    const queue = "q_stop_abort";
+    const wf = defineWorkflow({ name: "stop-abort", queue }, async () => {
+      await new Promise<never>(() => {});
+    });
+
+    const worker = await startWorker({
+      redis,
+      prefix,
+      queues: [queue],
+      runtime: { leaseMs: 500, blmoveTimeoutSec: 0.2, reaperIntervalMs: 50 },
+    });
+
+    try {
+      const handle = await wf.run({});
+
+      await waitFor(
+        async () => {
+          const run = await client.getRun(handle.id);
+          return run?.status === "running";
+        },
+        { timeoutMs: 5000, label: "run becomes running" },
+      );
+
+      const startedAt = Date.now();
+      await worker.stop();
+      const stopElapsedMs = Date.now() - startedAt;
+      expect(stopElapsedMs).toBeLessThan(2500);
+
+      await waitFor(
+        async () => {
+          const run = await client.getRun(handle.id);
+          return run?.status === "canceled";
+        },
+        { timeoutMs: 4000, label: "run canceled by stop" },
+      );
+
+      const state = await client.getRun(handle.id);
+      expect(state?.status).toBe("canceled");
+    } finally {
+      redis.close();
+    }
+  },
+  { timeout: 20_000 },
+);