@getstrata/core 2.1.0 → 2.2.1

package/dist/entries/queue/queueMetrics.js

@@ -1,6 +1,6 @@
 // @bun
 // ../../src/core/queue/queueMetrics.ts
-var {RedisClient: RedisClient2 } = globalThis.Bun;
+var {RedisClient: RedisClient3 } = globalThis.Bun;
 
 // ../../src/core/queue/failedJobRepository.ts
 import { BaseRepository } from "@getstrata/core/database/baseRepository";
@@ -10,7 +10,7 @@ import { defineTable } from "@getstrata/core/database/table";
 var failedJobTable = defineTable({
   name: "failed_job",
   primaryKey: "id",
-  columns: ["id", "job_name", "payload", "exception", "failed_at"],
+  columns: ["id", "job_name", "job_id", "payload", "exception", "failed_at"],
   defaultOrderBy: { column: "failed_at", direction: "DESC" }
 });
 
@@ -31,6 +31,7 @@ class FailedJobService {
   async recordFailure(input) {
     return await this.repository.create({
       job_name: input.jobName,
+      job_id: input.jobId ?? null,
       payload: input.payload,
       exception: input.exception,
       failed_at: new Date
@@ -42,8 +43,11 @@ class FailedJobService {
       orderBy: { column: "failed_at", direction: "DESC" }
     });
   }
-  async retry(id) {
+  async retry(id, enqueue) {
+    if (typeof enqueue !== "function")
+      throw new Error("Failed-job retry requires an admission callback.");
     const failedJob = await this.repository.findByIdOrThrow(id, (jobId) => new Error(`Failed job ${jobId} not found.`));
+    await enqueue(failedJob);
     await this.repository.deleteById(id);
     return failedJob;
   }
@@ -103,6 +107,9 @@ function readSharedJobRegistry() {
 }
 var jobRegistry = readSharedJobRegistry();
 
+// ../../src/core/queue/jobRunner.ts
+import { setTimeout as delay } from "timers/promises";
+
 // ../../src/core/queue/queueConfig.ts
 function resolveQueueConfig() {
   const driver = process.env.QUEUE_DRIVER;
@@ -125,22 +132,82 @@ var queueConfig = {
     return resolveQueueConfig().backoffMs;
   }
 };
+function resolveRedisQueueTransport() {
+  const transport = process.env.QUEUE_REDIS_TRANSPORT ?? "lists";
+  if (transport !== "lists" && transport !== "streams")
+    throw new Error('QUEUE_REDIS_TRANSPORT must be "lists" or "streams".');
+  return transport;
+}
+function readQueueVisibilityMs() {
+  const value = Number(process.env.QUEUE_VISIBILITY_MS ?? "60000");
+  if (!Number.isSafeInteger(value) || value < 30)
+    throw new Error("QUEUE_VISIBILITY_MS must be an integer of at least 30 milliseconds.");
+  return value;
+}
 
 // ../../src/core/queue/jobRunner.ts
+function parseQueueJobEnvelope(rawPayload) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawPayload);
+  } catch {
+    console.error("[QueueWorker] Ignoring malformed queue payload");
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") {
+    console.error("[QueueWorker] Ignoring non-object queue payload");
+    return null;
+  }
+  const envelope = parsed;
+  if (typeof envelope.name !== "string" || envelope.name.length === 0) {
+    console.error("[QueueWorker] Ignoring queue payload without job name");
+    return null;
+  }
+  if (!jobRegistry.create(envelope.name)) {
+    console.error(`[QueueWorker] Ignoring unknown job name: ${envelope.name}`);
+    return null;
+  }
+  if (envelope.payload !== undefined && (typeof envelope.payload !== "object" || envelope.payload === null)) {
+    console.error("[QueueWorker] Ignoring queue payload with invalid payload object");
+    return null;
+  }
+  if (envelope.jobId !== undefined && (typeof envelope.jobId !== "string" || !envelope.jobId.length))
+    return null;
+  if (envelope.attempts !== undefined && (!Number.isSafeInteger(envelope.attempts) || envelope.attempts < 0))
+    return null;
+  if (envelope.deadlineAtMs !== undefined && (!Number.isSafeInteger(envelope.deadlineAtMs) || envelope.deadlineAtMs <= 0))
+    return null;
+  if (envelope.cancellable !== undefined && (typeof envelope.cancellable !== "boolean" || envelope.cancellable && !envelope.jobId))
+    return null;
+  return {
+    ...envelope.cancellable ? { cancellable: true } : {},
+    ...envelope.deadlineAtMs === undefined ? {} : { deadlineAtMs: envelope.deadlineAtMs },
+    jobId: envelope.jobId,
+    name: envelope.name,
+    payload: envelope.payload ?? {},
+    attempts: typeof envelope.attempts === "number" ? envelope.attempts : 0
+  };
+}
 async function runQueueJob(envelope, failedJobs, options = {}) {
+  options.context?.signal.throwIfAborted();
   const job = jobRegistry.create(envelope.name);
   if (!job) {
     throw new Error(`Unknown job "${envelope.name}".`);
   }
   const attempts = envelope.attempts ?? 0;
   try {
-    await job.handle(envelope.payload);
+    await job.handle(envelope.payload, options.context);
   } catch (error) {
+    options.context?.signal.throwIfAborted();
     const nextAttempt = attempts + 1;
     const maxAttempts = job.maxAttempts ?? queueConfig.maxAttempts;
     if (nextAttempt < maxAttempts) {
       const backoffMs = job.backoffMs ?? queueConfig.backoffMs;
-      await new Promise((resolve) => setTimeout(resolve, backoffMs * nextAttempt));
+      if (options.deferRetry) {
+        await options.deferRetry({ ...envelope, attempts: nextAttempt }, backoffMs * nextAttempt);
+        return;
+      }
+      await delay(backoffMs * nextAttempt, undefined, { signal: options.context?.signal });
       await runQueueJob({
         ...envelope,
         attempts: nextAttempt
@@ -149,6 +216,7 @@ async function runQueueJob(envelope, failedJobs, options = {}) {
     }
     await failedJobs.recordFailure({
       jobName: envelope.name,
+      jobId: options.context?.jobId ?? envelope.jobId,
       payload: envelope.payload,
       exception: error instanceof Error ? error.stack ?? error.message : String(error)
     });
@@ -158,7 +226,7 @@ async function runQueueJob(envelope, failedJobs, options = {}) {
 }
 
 // ../../src/core/queue/redisQueue.ts
-var {RedisClient } = globalThis.Bun;
+var {RedisClient: RedisClient2 } = globalThis.Bun;
 
 // ../../src/core/runtime/appEnv.ts
 var NON_PRODUCTION_APP_ENVS = new Set(["local", "development", "dev", "test", "testing", "ci"]);
@@ -246,7 +314,7 @@ function sdkClientClassName() {
   return fromName ? `${fromName}Client` : "AppClient";
 }
 
-// ../../src/core/queue/redisQueue.ts
+// ../../src/core/queue/redisQueueKeys.ts
 function queueListKey() {
   return namespacedRedisKey("queue:default");
 }
@@ -259,31 +327,10 @@ function queueLowKey() {
 var QUEUE_LIST_KEY = queueListKey();
 var QUEUE_HIGH_KEY = queueHighKey();
 var QUEUE_LOW_KEY = queueLowKey();
-var QUEUE_KEYS = [QUEUE_HIGH_KEY, QUEUE_LIST_KEY, QUEUE_LOW_KEY];
-var DEFAULT_VISIBILITY_MS = 60000;
-function queueProcessingKey(queueKey) {
-  return `${queueKey}:processing`;
-}
-function queueProcessingLeaseKey(queueKey) {
-  return `${queueKey}:processing:leases`;
-}
-function readVisibilityMs() {
-  const parsed = Number(process.env.QUEUE_VISIBILITY_MS ?? String(DEFAULT_VISIBILITY_MS));
-  if (!Number.isSafeInteger(parsed) || parsed < 30) {
-    throw new Error("QUEUE_VISIBILITY_MS must be an integer of at least 30 milliseconds.");
-  }
-  return parsed;
-}
-function reservationExpired(lease, now, visibilityMs) {
-  if (lease === null || lease.length === 0) {
-    return true;
-  }
-  const reservedAt = Number(lease);
-  if (!Number.isFinite(reservedAt)) {
-    return true;
-  }
-  return now - reservedAt >= visibilityMs;
+function defaultQueueKeys() {
+  return [queueHighKey(), queueListKey(), queueLowKey()];
 }
+var QUEUE_KEYS = defaultQueueKeys();
 function queueKeyForPriority(priority = "default") {
   switch (priority) {
     case "high":
@@ -294,36 +341,603 @@ function queueKeyForPriority(priority = "default") {
       return queueListKey();
   }
 }
-function parseQueueJobEnvelope(rawPayload) {
-  let parsed;
+
+// ../../src/core/queue/redisStreams.ts
+var {RedisClient } = globalThis.Bun;
+var STREAM_GROUP = "strata-workers-v1";
+function streamQueueKey(queueKey) {
+  return `${queueKey}:stream`;
+}
+function streamDeadLetterKey(queueKey) {
+  return `${streamQueueKey(queueKey)}:invalid`;
+}
+function streamRetryKey(queueKey) {
+  return `${streamQueueKey(queueKey)}:retries`;
+}
+function streamControlKey(key, jobId) {
+  const prefix = `${streamQueueKey(key)}/`;
+  if (!jobId.startsWith(prefix) || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(jobId.slice(prefix.length)))
+    throw new Error("Invalid cancellable Streams job ID");
+  return `${streamQueueKey(key)}:control:${jobId.slice(prefix.length)}`;
+}
+var ENQUEUE_CONTROLLED = `
+local kind = redis.call('TYPE', KEYS[1]).ok
+if kind ~= 'none' and kind ~= 'stream' then return redis.error_reply('Invalid stream admission key type') end
+if redis.call('EXISTS', KEYS[2]) ~= 0 then return redis.error_reply('Streams control identity already exists') end
+redis.call('XADD', KEYS[1], '*', 'payload', ARGV[1])
+redis.call('HSET', KEYS[2], 'state', 'active')
+return 1
+`;
+var CANCEL_STREAM = `
+local state = redis.call('HGET', KEYS[1], 'state')
+if not state then return 0 end
+local kind = redis.call('TYPE', KEYS[2]).ok
+if kind ~= 'none' and kind ~= 'zset' then return redis.error_reply('Invalid stream retry key type') end
+local payload = redis.call('HGET', KEYS[1], 'retryPayload')
+if payload and redis.call('ZSCORE', KEYS[2], payload) then redis.call('ZADD', KEYS[2], 0, payload) end
+redis.call('HSET', KEYS[1], 'state', 'cancelled')
+return 1
+`;
+async function cancelStreamJob(client, key, jobId) {
+  return Number(await client.send("EVAL", [
+    CANCEL_STREAM,
+    "2",
+    streamControlKey(key, jobId),
+    streamRetryKey(key)
+  ])) === 1;
+}
+async function readStreamCancellation(client, controlKey) {
+  const state = await client.send("HGET", [controlKey, "state"]);
+  if (state !== "active" && state !== "cancelled")
+    throw new Error("Missing or invalid Streams control state");
+  return state === "cancelled";
+}
+var MAX_TIMER_MS = 2147483647;
+async function readStreamTime(client) {
+  const value = await client.send("TIME", []);
+  if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== "string" || typeof value[1] !== "string" || !/^\d+$/.test(value[0]) || !/^\d+$/.test(value[1]))
+    throw new Error("Invalid Redis TIME response");
+  const seconds = Number(value[0]);
+  const micros = Number(value[1]);
+  const now = seconds * 1000 + Math.floor(micros / 1000);
+  if (!Number.isSafeInteger(seconds) || seconds < 0 || !Number.isSafeInteger(micros) || micros < 0 || micros >= 1e6 || !Number.isSafeInteger(now))
+    throw new Error("Invalid Redis TIME response");
+  return now;
+}
+function watchStreamDeadline(client, deadlineAtMs, remainingMs, expire, fail) {
+  let stopped = false;
+  let timer;
+  const schedule = (remaining) => {
+    timer = setTimeout(() => {
+      (async () => {
+        try {
+          const remaining = deadlineAtMs - await readStreamTime(client);
+          if (stopped)
+            return;
+          if (remaining <= 0)
+            expire();
+          else
+            schedule(remaining);
+        } catch (error) {
+          if (!stopped)
+            fail(error);
+        }
+      })();
+    }, Math.max(1, Math.min(MAX_TIMER_MS, remaining)));
+  };
+  schedule(remainingMs);
+  return () => {
+    stopped = true;
+    clearTimeout(timer);
+  };
+}
+var SCHEDULE_RETRY = `
+local pending = redis.call('XPENDING', KEYS[1], ARGV[1], ARGV[2], ARGV[2], 1)
+if #pending == 0 or pending[1][2] ~= ARGV[3] or tonumber(pending[1][3]) >= tonumber(ARGV[4]) then return 0 end
+local kind = redis.call('TYPE', KEYS[2]).ok
+if kind ~= 'none' and kind ~= 'zset' then return redis.error_reply('Invalid stream retry key type') end
+if ARGV[8] == '1' then
+  local state = redis.call('HGET', KEYS[3], 'state')
+  if state == 'cancelled' then return redis.error_reply('Streams job cancelled') end
+  if state ~= 'active' then return redis.error_reply('Missing or invalid Streams control state') end
+end
+local now = redis.call('TIME')
+local due = tonumber(now[1])*1000 + math.floor(tonumber(now[2])/1000) + tonumber(ARGV[5])
+if ARGV[7] ~= '' then due = math.min(due, tonumber(ARGV[7])) end
+redis.call('ZADD', KEYS[2], due, ARGV[6])
+if ARGV[8] == '1' then redis.call('HSET', KEYS[3], 'retryPayload', ARGV[6]) end
+redis.call('XACK', KEYS[1], ARGV[1], ARGV[2])
+redis.call('XDEL', KEYS[1], ARGV[2])
+if #redis.call('XPENDING', KEYS[1], ARGV[1], '-', '+', 1, ARGV[3]) == 0 then redis.call('XGROUP', 'DELCONSUMER', KEYS[1], ARGV[1], ARGV[3]) end
+return 1
+`;
+var PROMOTE_RETRIES = `
+local kinds = {'stream','zset'}
+for i=1,2 do
+  local kind = redis.call('TYPE', KEYS[i]).ok
+  if kind ~= 'none' and kind ~= kinds[i] then return redis.error_reply('Invalid stream retry promotion key type') end
+end
+local now = redis.call('TIME')
+local due = tonumber(now[1])*1000 + math.floor(tonumber(now[2])/1000)
+local entries = redis.call('ZRANGE', KEYS[2], '-inf', due, 'BYSCORE', 'LIMIT', 0, 100)
+for _, payload in ipairs(entries) do
+  redis.call('XADD', KEYS[1], '*', 'payload', payload)
+  redis.call('ZREM', KEYS[2], payload)
+end
+return #entries
+`;
+async function scheduleStreamRetry(client, key, reservation, envelope, delayMs) {
+  if (!Number.isSafeInteger(delayMs) || delayMs < 0 || delayMs > Number.MAX_SAFE_INTEGER / 2)
+    throw new Error("Invalid Streams retry delay");
+  const scheduled = await client.send("EVAL", [
+    SCHEDULE_RETRY,
+    "3",
+    streamQueueKey(key),
+    streamRetryKey(key),
+    envelope.cancellable ? streamControlKey(key, envelope.jobId ?? "") : streamQueueKey(key),
+    STREAM_GROUP,
+    reservation.id,
+    reservation.owner,
+    String(readQueueVisibilityMs()),
+    String(delayMs),
+    JSON.stringify(envelope),
+    envelope.deadlineAtMs === undefined ? "" : String(envelope.deadlineAtMs),
+    envelope.cancellable ? "1" : "0"
+  ]);
+  if (Number(scheduled) !== 1)
+    throw new Error("Queue lease lost while scheduling retry");
+}
+async function promoteStreamRetries(client, key) {
+  return Number(await client.send("EVAL", [PROMOTE_RETRIES, "2", streamQueueKey(key), streamRetryKey(key)]));
+}
+async function readStreamQueueDepth(client, key) {
+  return Number(await client.send("EVAL", [
+    "return redis.call('XLEN', KEYS[1]) + redis.call('ZCARD', KEYS[2])",
+    "2",
+    streamQueueKey(key),
+    streamRetryKey(key)
+  ]));
+}
+var ASSERT_DRAINED = `
+if redis.call('LLEN', KEYS[1]) > 0 or redis.call('LLEN', KEYS[2]) > 0 or redis.call('HLEN', KEYS[3]) > 0 then
+  return redis.error_reply('Legacy queue state requires maintenance conversion before Streams activation')
+end
+return 1
+`;
+async function assertLegacyDrained(client, key) {
+  await client.send("EVAL", [
+    ASSERT_DRAINED,
+    "3",
+    key,
+    `${key}:processing`,
+    `${key}:processing:leases`
+  ]);
+}
+var UPDATE_STREAM = `
+local pending = redis.call('XPENDING', KEYS[1], ARGV[1], ARGV[2], ARGV[2], 1)
+if #pending == 0 or pending[1][2] ~= ARGV[3] or tonumber(pending[1][3]) >= tonumber(ARGV[4]) then return 0 end
+if ARGV[7] == '1' then
+  local kind = redis.call('TYPE', KEYS[3]).ok
+  if kind ~= 'none' and kind ~= 'hash' then return redis.error_reply('Invalid stream control key type') end
+end
+if ARGV[5] == 'renew' then
+  local claimed = redis.call('XCLAIM', KEYS[1], ARGV[1], ARGV[3], 0, ARGV[2], 'JUSTID')
+  return #claimed
+end
+if ARGV[5] == 'quarantine' then
+  local kind = redis.call('TYPE', KEYS[2]).ok
+  if kind ~= 'none' and kind ~= 'stream' then return redis.error_reply('Invalid stream quarantine key type') end
+  redis.call('XADD', KEYS[2], '*', 'sourceId', ARGV[2], 'payload', ARGV[6])
+end
+local acknowledged = redis.call('XACK', KEYS[1], ARGV[1], ARGV[2])
+if acknowledged == 1 then
+  redis.call('XDEL', KEYS[1], ARGV[2])
+  if ARGV[7] == '1' then redis.call('DEL', KEYS[3]) end
+end
+if #redis.call('XPENDING', KEYS[1], ARGV[1], '-', '+', 1, ARGV[3]) == 0 then redis.call('XGROUP', 'DELCONSUMER', KEYS[1], ARGV[1], ARGV[3]) end
+return acknowledged
+`;
+var CLAIM_STREAM = `
+local window = redis.call('XPENDING', KEYS[1], ARGV[1], ARGV[4], '+', 10)
+local claimed = redis.call('XAUTOCLAIM', KEYS[1], ARGV[1], ARGV[2], ARGV[3], ARGV[4], 'COUNT', 1)
+for _, entry in ipairs(window) do
+  if entry[2] ~= ARGV[2] and #redis.call('XPENDING', KEYS[1], ARGV[1], '-', '+', 1, entry[2]) == 0 then redis.call('XGROUP', 'DELCONSUMER', KEYS[1], ARGV[1], entry[2]) end
+end
+if #redis.call('XPENDING', KEYS[1], ARGV[1], '-', '+', 1, ARGV[2]) == 0 then redis.call('XGROUP', 'DELCONSUMER', KEYS[1], ARGV[1], ARGV[2]) end
+return claimed
+`;
+var READ_STREAM = `
+local entries = redis.call('XREADGROUP', 'GROUP', ARGV[1], ARGV[2], 'COUNT', 1, 'STREAMS', KEYS[1], '>')
+if not entries and #redis.call('XPENDING', KEYS[1], ARGV[1], '-', '+', 1, ARGV[2]) == 0 then redis.call('XGROUP', 'DELCONSUMER', KEYS[1], ARGV[1], ARGV[2]) end
+return entries
+`;
+async function ensureStreamGroup(client, key) {
+  await assertLegacyDrained(client, key);
   try {
-    parsed = JSON.parse(rawPayload);
-  } catch {
-    console.error("[QueueWorker] Ignoring malformed queue payload");
-    return null;
+    await client.send("XGROUP", ["CREATE", streamQueueKey(key), STREAM_GROUP, "0", "MKSTREAM"]);
+  } catch (error) {
+    if (!(error instanceof Error) || !error.message.includes("BUSYGROUP"))
+      throw error;
   }
-  if (!parsed || typeof parsed !== "object") {
-    console.error("[QueueWorker] Ignoring non-object queue payload");
-    return null;
+}
+function readStreamEntry(value, owner) {
+  if (!Array.isArray(value) || typeof value[0] !== "string" || !Array.isArray(value[1]))
+    throw new Error("Invalid Redis stream entry response");
+  const fields = value[1];
+  let payload;
+  for (let index = 0;index < fields.length; index += 2) {
+    if (fields[index] === "payload" && typeof fields[index + 1] === "string")
+      payload = fields[index + 1];
   }
-  const envelope = parsed;
-  if (typeof envelope.name !== "string" || envelope.name.length === 0) {
-    console.error("[QueueWorker] Ignoring queue payload without job name");
-    return null;
+  return { id: value[0], owner, payload: payload ?? "" };
+}
+async function updateStreamReservation(client, key, reservation, action, controlKey) {
+  return Number(await client.send("EVAL", [
+    UPDATE_STREAM,
+    "3",
+    streamQueueKey(key),
+    streamDeadLetterKey(key),
+    controlKey ?? streamQueueKey(key),
+    STREAM_GROUP,
+    reservation.id,
+    reservation.owner,
+    String(readQueueVisibilityMs()),
+    action,
+    reservation.payload,
+    controlKey ? "1" : "0"
+  ])) === 1;
+}
+async function reserveStreamJob(client, key, owner, cursor = "0-0") {
+  const claimed = await client.send("EVAL", [
+    CLAIM_STREAM,
+    "1",
+    streamQueueKey(key),
+    STREAM_GROUP,
+    owner,
+    String(readQueueVisibilityMs()),
+    cursor
+  ]);
+  if (!Array.isArray(claimed) || typeof claimed[0] !== "string" || !Array.isArray(claimed[1]))
+    throw new Error("Invalid Redis XAUTOCLAIM response");
+  const nextCursor = claimed[0];
+  if (claimed[1].length > 0)
+    return { reservation: readStreamEntry(claimed[1][0], owner), cursor: nextCursor };
+  const fresh = await client.send("EVAL", [
+    READ_STREAM,
+    "1",
+    streamQueueKey(key),
+    STREAM_GROUP,
+    owner
+  ]);
+  if (fresh === null)
+    return { reservation: null, cursor: nextCursor };
+  if (!Array.isArray(fresh) || !Array.isArray(fresh[0]) || !Array.isArray(fresh[0][1]))
+    throw new Error("Invalid Redis XREADGROUP response");
+  return { reservation: readStreamEntry(fresh[0][1][0], owner), cursor: nextCursor };
+}
+
+class RedisStreamsQueue {
+  client;
+  constructor(redisUrl) {
+    this.client = new RedisClient(redisUrl);
   }
-  if (!jobRegistry.create(envelope.name)) {
-    console.error(`[QueueWorker] Ignoring unknown job name: ${envelope.name}`);
-    return null;
+  close() {
+    this.client.close();
   }
-  if (envelope.payload !== undefined && (typeof envelope.payload !== "object" || envelope.payload === null)) {
-    console.error("[QueueWorker] Ignoring queue payload with invalid payload object");
-    return null;
+  async dispatch(job, payload) {
+    await this.enqueue(job, payload);
+  }
+  async enqueue(job, payload, options = {}) {
+    return this.admit(job, payload, options);
+  }
+  async replay(job, payload, jobId) {
+    const prefix = defaultQueueKeys().find((key) => jobId.startsWith(`${streamQueueKey(key)}/`));
+    if (!prefix || !/^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9]+-[0-9]+)$/.test(jobId.slice(streamQueueKey(prefix).length + 1)))
+      throw new Error("Replay identity does not belong to this Streams namespace");
+    await this.admit(job, payload, {}, jobId);
+  }
+  async admit(job, payload, options, replayId) {
+    if (options.cancellable !== undefined && typeof options.cancellable !== "boolean")
+      throw new Error("cancellable must be a boolean");
+    if (options.timeoutMs !== undefined && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > MAX_TIMER_MS))
+      throw new Error("Streams timeoutMs must be an integer between 1 and 2147483647");
+    const name = jobRegistry.resolveName(job);
+    if (!name)
+      throw new Error("Job is not registered with the queue worker registry.");
+    const key = queueKeyForPriority(job.priority);
+    await assertLegacyDrained(this.client, key);
+    const jobId = replayId ?? `${streamQueueKey(key)}/${crypto.randomUUID()}`;
+    const deadlineAtMs = options.timeoutMs === undefined ? undefined : await readStreamTime(this.client) + options.timeoutMs;
+    const envelope = JSON.stringify({
+      name,
+      payload,
+      attempts: 0,
+      jobId,
+      deadlineAtMs,
+      ...options.cancellable ? { cancellable: true } : {}
+    });
+    if (options.cancellable)
+      await this.client.send("EVAL", [
+        ENQUEUE_CONTROLLED,
+        "2",
+        streamQueueKey(key),
+        streamControlKey(key, jobId),
+        envelope
+      ]);
+    else
+      await this.client.send("XADD", [streamQueueKey(key), "*", "payload", envelope]);
+    return jobId;
+  }
+  async cancel(jobId) {
+    const key = defaultQueueKeys().find((key) => jobId.startsWith(`${streamQueueKey(key)}/`));
+    if (!key)
+      throw new Error("Invalid cancellable Streams job ID");
+    return cancelStreamJob(this.client, key, jobId);
+  }
+}
+
+class RedisStreamsWorker {
+  failedJobs;
+  timeoutSeconds;
+  queueKeys;
+  client;
+  owner = crypto.randomUUID();
+  cursors = new Map;
+  processing = false;
+  initialized = false;
+  running = false;
+  stopping = false;
+  active;
+  constructor(redisUrl, failedJobs, timeoutSeconds = 5, queueKeys = defaultQueueKeys()) {
+    this.failedJobs = failedJobs;
+    this.timeoutSeconds = timeoutSeconds;
+    this.queueKeys = queueKeys;
+    readQueueVisibilityMs();
+    this.client = new RedisClient(redisUrl);
+  }
+  requestStop() {
+    this.stopping = true;
+  }
+  isRunning() {
+    return this.running;
+  }
+  close() {
+    this.stopping = true;
+    this.active?.abort(new Error("Queue worker closed"));
+    this.client.close();
+  }
+  async initialize() {
+    if (this.initialized)
+      return;
+    for (const key of this.queueKeys)
+      await ensureStreamGroup(this.client, key);
+    this.initialized = true;
+  }
+  async reserve(key) {
+    await promoteStreamRetries(this.client, key);
+    const result = await reserveStreamJob(this.client, key, this.owner, this.cursors.get(key));
+    this.cursors.set(key, result.cursor);
+    return result.reservation;
+  }
+  async processNext() {
+    if (this.processing)
+      throw new Error("Queue worker already processing a job.");
+    this.processing = true;
+    try {
+      return await this.processOne();
+    } finally {
+      this.processing = false;
+    }
+  }
+  async processOne() {
+    if (this.stopping)
+      return false;
+    await this.initialize();
+    const deadline = performance.now() + this.timeoutSeconds * 1000;
+    do {
+      for (const key of this.queueKeys) {
+        if (this.stopping)
+          return false;
+        const reservation = await this.reserve(key);
+        if (!reservation)
+          continue;
+        await this.handle(key, reservation);
+        return true;
+      }
+      if (performance.now() >= deadline || this.stopping)
+        return false;
+      await Bun.sleep(Math.min(100, Math.max(1, deadline - performance.now())));
+    } while (!this.stopping);
+    return false;
+  }
+  async handle(key, reservation) {
+    const envelope = parseQueueJobEnvelope(reservation.payload);
+    if (!envelope) {
+      await updateStreamReservation(this.client, key, reservation, "quarantine");
+      return;
+    }
+    envelope.jobId ??= `${streamQueueKey(key)}/${reservation.id}`;
+    let controlKey;
+    if (envelope.cancellable) {
+      try {
+        controlKey = streamControlKey(key, envelope.jobId);
+      } catch {
+        await updateStreamReservation(this.client, key, reservation, "quarantine");
+        return;
+      }
+    }
+    const cancellationError = new Error("Streams job cancelled");
+    if (controlKey && await readStreamCancellation(this.client, controlKey)) {
+      await this.failedJobs.recordFailure({
+        jobName: envelope.name,
+        jobId: envelope.jobId,
+        payload: envelope.payload,
+        exception: cancellationError.message
+      });
+      await updateStreamReservation(this.client, key, reservation, "ack", controlKey);
+      return;
+    }
+    const remainingMs = envelope.deadlineAtMs === undefined ? undefined : envelope.deadlineAtMs - await readStreamTime(this.client);
+    const deadlineError = new Error("Streams job deadline exceeded");
+    if (remainingMs !== undefined && remainingMs <= 0) {
+      await this.failedJobs.recordFailure({
+        jobName: envelope.name,
+        jobId: envelope.jobId,
+        payload: envelope.payload,
+        exception: deadlineError.message
+      });
+      await updateStreamReservation(this.client, key, reservation, "ack", controlKey);
+      return;
+    }
+    const controller = new AbortController;
+    this.active = controller;
+    let acknowledge = false;
+    let released = false;
+    let ownershipLost = false;
+    let renewal;
+    let deadlineExpired = false;
+    let cancellationRequested = false;
+    let failureRecorded = false;
+    const loseOwnership = (error) => {
+      ownershipLost = true;
+      controller.abort(error);
+    };
+    const stopDeadlineWatch = remainingMs === undefined || envelope.deadlineAtMs === undefined ? undefined : watchStreamDeadline(this.client, envelope.deadlineAtMs, remainingMs, () => {
+      deadlineExpired = true;
+      controller.abort(deadlineError);
+    }, loseOwnership);
+    const heartbeat = setInterval(() => {
+      if (renewal || ownershipLost || released)
+        return;
+      renewal = (async () => {
+        try {
+          if (!await updateStreamReservation(this.client, key, reservation, "renew", controlKey))
+            loseOwnership(new Error("Queue lease lost"));
+          else if (controlKey && await readStreamCancellation(this.client, controlKey)) {
+            cancellationRequested = true;
+            controller.abort(cancellationError);
+          }
+        } catch (error) {
+          loseOwnership(error);
+          console.error("[StreamsWorker] Lease renewal failed:", error);
+        }
+      })().finally(() => {
+        renewal = undefined;
+      });
+    }, Math.max(1, Math.floor(readQueueVisibilityMs() / 3)));
+    try {
+      await runQueueJob(envelope, this.failedJobs, {
+        context: {
+          jobId: envelope.jobId,
+          signal: controller.signal,
+          deadlineAtMs: envelope.deadlineAtMs
+        },
+        deferRetry: async (next, delayMs) => {
+          controller.signal.throwIfAborted();
+          await scheduleStreamRetry(this.client, key, reservation, next, delayMs);
+          released = true;
+        },
+        onFailureRecorded: () => {
+          acknowledge = true;
+          failureRecorded = true;
+        }
+      });
+      acknowledge = true;
+    } catch (error) {
+      console.error("[StreamsWorker] Job failed:", error);
+    } finally {
+      stopDeadlineWatch?.();
+      clearInterval(heartbeat);
+      await renewal;
+      this.active = undefined;
+    }
+    if (!ownershipLost && !released && controlKey && (cancellationRequested || await readStreamCancellation(this.client, controlKey))) {
+      if (!failureRecorded)
+        await this.failedJobs.recordFailure({
+          jobName: envelope.name,
+          jobId: envelope.jobId,
+          payload: envelope.payload,
+          exception: cancellationError.message
+        });
+      failureRecorded = true;
+      acknowledge = true;
+    }
+    if (!ownershipLost && !released && envelope.deadlineAtMs !== undefined && (deadlineExpired || envelope.deadlineAtMs <= await readStreamTime(this.client))) {
+      if (!failureRecorded)
+        await this.failedJobs.recordFailure({
+          jobName: envelope.name,
+          jobId: envelope.jobId,
+          payload: envelope.payload,
+          exception: deadlineError.message
+        });
+      acknowledge = true;
+    }
+    if (acknowledge && !ownershipLost && !released)
+      await updateStreamReservation(this.client, key, reservation, "ack", controlKey);
+  }
+  async run() {
+    this.running = true;
+    try {
+      while (!this.stopping)
+        await this.processNext();
+    } finally {
+      this.running = false;
+    }
   }
-  return {
-    name: envelope.name,
-    payload: envelope.payload ?? {},
-    attempts: typeof envelope.attempts === "number" ? envelope.attempts : 0
-  };
+}
+var CONVERT_LIST = `
+local kinds = {'list','list','hash','stream'}
+for i=1,4 do
+  local kind = redis.call('TYPE', KEYS[i]).ok
+  if kind ~= 'none' and kind ~= kinds[i] then return redis.error_reply('Invalid queue conversion key type') end
+end
+if redis.call('LLEN', KEYS[2]) > 0 or redis.call('HLEN', KEYS[3]) > 0 then return redis.error_reply('Drain or recover processing reservations before queue conversion') end
+local converted = 0
+for i=1,tonumber(ARGV[1]) do
+  local payload = redis.call('LINDEX', KEYS[1], -1)
+  if not payload then break end
+  redis.call('XADD', KEYS[4], '*', 'payload', payload)
+  redis.call('RPOP', KEYS[1])
+  converted = converted + 1
+end
+return converted
+`;
+async function migrateLegacyQueueToStreams(client, options) {
+  if (options.maintenance !== true)
+    throw new Error("Queue conversion requires maintenance mode: stop all producers and workers first.");
+  const batchSize = options.batchSize ?? 100;
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1 || batchSize > 1000)
+    throw new Error("Queue conversion batchSize must be between 1 and 1000.");
+  let converted = 0;
+  for (const key of options.queueKeys ?? defaultQueueKeys())
+    converted += Number(await client.send("EVAL", [
+      CONVERT_LIST,
+      "4",
+      key,
+      `${key}:processing`,
+      `${key}:processing:leases`,
+      streamQueueKey(key),
+      String(batchSize)
+    ]));
+  return converted;
+}
+
+// ../../src/core/queue/redisQueue.ts
+function queueProcessingKey(queueKey) {
+  return `${queueKey}:processing`;
+}
+function queueProcessingLeaseKey(queueKey) {
+  return `${queueKey}:processing:leases`;
+}
+function reservationExpired(lease, now, visibilityMs) {
+  if (lease === null || lease.length === 0) {
+    return true;
+  }
+  const reservedAt = Number(lease);
+  if (!Number.isFinite(reservedAt)) {
+    return true;
+  }
+  return now - reservedAt >= visibilityMs;
 }
 var SCRIPT_HEADER = `
 local function checkType(key, expected)
@@ -412,7 +1026,7 @@ async function reserveQueueJob(client, queueKey, owner) {
     queueProcessingLeaseKey(queueKey),
     crypto.randomUUID(),
     owner,
-    String(readVisibilityMs())
+    String(readQueueVisibilityMs())
   ]);
   if (typeof raw !== "string")
     return null;
@@ -430,7 +1044,7 @@ async function updateQueueReservation(client, queueKey, reservation, action) {
     reservation.owner,
     reservation.record,
     action,
-    String(readVisibilityMs()),
+    String(readQueueVisibilityMs()),
     reservation.payload
   ])) === 1;
 }
@@ -443,7 +1057,7 @@ async function reclaimExpiredQueueReservations(client, queueKeys = QUEUE_KEYS) {
       key,
       queueProcessingKey(key),
       queueProcessingLeaseKey(key),
-      String(readVisibilityMs())
+      String(readQueueVisibilityMs())
     ]));
   }
   return reclaimed;
@@ -452,7 +1066,10 @@ async function reclaimExpiredQueueReservations(client, queueKeys = QUEUE_KEYS) {
 class RedisQueue {
   client;
   constructor(redisUrl) {
-    this.client = new RedisClient(redisUrl);
+    this.client = new RedisClient2(redisUrl);
+  }
+  close() {
+    this.client.close();
   }
   async dispatch(job, payload) {
     const name = jobRegistry.resolveName(job);
@@ -481,7 +1098,7 @@ class QueueWorker {
     this.failedJobs = failedJobs;
     this.timeoutSeconds = timeoutSeconds;
     this.queueKeys = queueKeys;
-    this.client = new RedisClient(redisUrl);
+    this.client = new RedisClient2(redisUrl);
   }
   requestStop() {
     this.stopping = true;
@@ -536,7 +1153,7 @@ class QueueWorker {
       })().finally(() => {
         renewal = undefined;
       });
-    }, Math.max(1, Math.floor(readVisibilityMs() / 3)));
+    }, Math.max(1, Math.floor(readQueueVisibilityMs() / 3)));
     try {
       await runQueueJob(envelope, this.failedJobs, {
         onFailureRecorded: () => {
@@ -570,11 +1187,11 @@ class QueueWorker {
   }
 }
 async function countPendingQueueJobs(redisUrl) {
-  const client = new RedisClient(redisUrl);
+  const client = new RedisClient2(redisUrl);
   try {
     let total = 0;
-    for (const queueKey of QUEUE_KEYS) {
-      total += await client.llen(queueKey);
+    for (const queueKey of resolveRedisQueueTransport() === "streams" ? defaultQueueKeys() : QUEUE_KEYS) {
+      total += resolveRedisQueueTransport() === "streams" ? await readStreamQueueDepth(client, queueKey) : await client.llen(queueKey);
     }
     return total;
   } finally {
@@ -582,15 +1199,75 @@ async function countPendingQueueJobs(redisUrl) {
   }
 }
 
+// ../../src/core/queue/index.ts
+class Job {
+  static jobName;
+  maxAttempts;
+  backoffMs;
+  priority;
+  constructor() {
+    const jobName = this.constructor.jobName;
+    if (jobName) {
+      jobRegistry.track(jobName, this);
+    }
+  }
+}
+
+class SyncQueue {
+  async dispatch(job, payload) {
+    await job.handle(payload);
+  }
+}
+
+class AsyncQueue {
+  active = new Set;
+  closing;
+  closed = false;
+  assertOpen() {
+    if (this.closed)
+      throw new Error("Async queue is closed.");
+  }
+  enqueue(task, onError) {
+    this.assertOpen();
+    const running = new Promise((resolve) => {
+      setTimeout(() => {
+        Promise.resolve().then(task).catch(onError).finally(resolve);
+      }, 0);
+    });
+    this.active.add(running);
+    running.then(() => {
+      this.active.delete(running);
+    });
+  }
+  async dispatch(job, payload) {
+    this.enqueue(() => job.handle(payload), (error) => {
+      console.error("[AsyncQueue] Job failed:", error);
+    });
+  }
+  close() {
+    this.closing ??= (async () => {
+      while (this.active.size)
+        await Promise.all([...this.active]);
+      this.closed = true;
+    })();
+    return this.closing;
+  }
+}
+function createQueue(driver) {
+  return driver === "async" ? new AsyncQueue : new SyncQueue;
+}
+
 // ../../src/core/queue/resilientQueue.ts
-class ResilientQueue {
+class ResilientQueue extends AsyncQueue {
   failedJobs;
   asyncDispatch;
   constructor(failedJobs, asyncDispatch = false) {
+    super();
     this.failedJobs = failedJobs;
     this.asyncDispatch = asyncDispatch;
   }
   async dispatch(job, payload) {
+    this.assertOpen();
     const name = jobRegistry.resolveName(job);
     if (!name) {
       throw new Error("Job is not registered with the queue worker registry.");
@@ -601,11 +1278,9 @@ class ResilientQueue {
       attempts: 0
     };
     if (this.asyncDispatch) {
-      setTimeout(() => {
-        runQueueJob(envelope, this.failedJobs).catch((error) => {
-          console.error("[ResilientQueue] Job failed:", error);
-        });
-      }, 0);
+      this.enqueue(() => runQueueJob(envelope, this.failedJobs), (error) => {
+        console.error("[ResilientQueue] Job failed:", error);
+      });
       return;
     }
     await runQueueJob(envelope, this.failedJobs);
@@ -626,12 +1301,12 @@ function createProductionQueue(driver, options = {}) {
     if (!options.redisUrl) {
       throw new Error('QUEUE_DRIVER="redis" requires REDIS_URL to be set.');
     }
-    return new RedisQueue(options.redisUrl);
+    return resolveRedisQueueTransport() === "streams" ? new RedisStreamsQueue(options.redisUrl) : new RedisQueue(options.redisUrl);
   }
   return new ResilientQueue(failedJobs, driver === "async");
 }
 function createQueueWorker(redisUrl, failedJobs = createFailedJobService()) {
-  return new QueueWorker(redisUrl, failedJobs);
+  return resolveRedisQueueTransport() === "streams" ? new RedisStreamsWorker(redisUrl, failedJobs) : new QueueWorker(redisUrl, failedJobs);
 }
 
 // ../../src/core/queue/createAppQueue.ts
@@ -646,12 +1321,20 @@ function createAppQueue(driver, redisUrl, failedJobs = createFailedJobService(),
 
 // ../../src/core/queue/queueMetrics.ts
 async function readRedisQueueDepth(redisUrl) {
-  const client = new RedisClient2(redisUrl);
-  const [high, defaultQueue, low] = await Promise.all([
-    client.llen(QUEUE_HIGH_KEY),
-    client.llen(QUEUE_LIST_KEY),
-    client.llen(QUEUE_LOW_KEY)
-  ]);
+  const client = new RedisClient3(redisUrl);
+  let high;
+  let defaultQueue;
+  let low;
+  try {
+    const readDepth = async (key) => resolveRedisQueueTransport() === "streams" ? readStreamQueueDepth(client, key) : client.llen(key);
+    [high, defaultQueue, low] = await Promise.all([
+      readDepth(defaultQueueKeys()[0]),
+      readDepth(defaultQueueKeys()[1]),
+      readDepth(defaultQueueKeys()[2])
+    ]);
+  } finally {
+    client.close();
+  }
   return {
     high: Number(high ?? 0),
     default: Number(defaultQueue ?? 0),