experimental-a2 0.17.0 → 0.18.1

package/dist/scheduler-vercel.js

@@ -1,5 +1,5 @@
-import { _ as serverInternals, d as assertSchedulerTargets, f as classifySchedulerSendFailure, t as DRAIN_TIMINGS } from "./internal-CbVvEwad.js";
-import { n as deliverSchedulerAppend, r as deliverSchedulerClear } from "./server-Rj64fNvX.js";
+import { d as assertSchedulerTargets, f as classifySchedulerSendFailure, t as DRAIN_TIMINGS, v as serverInternals } from "./internal-CscSY7K_.js";
+import { n as deliverSchedulerAppend, r as deliverSchedulerClear } from "./server-D-Y4pqwu.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
 import { n as SYSTEM_CLOCK } from "./store-N8PXxDAS.js";
 import { t as normalizeSchedulerTask } from "./scheduler-task-X1SToDjP.js";
@@ -21,20 +21,19 @@ import { createHash } from "node:crypto";
 *   the configured deployment scope for sending and receiving.
 * - `handler(...servers)` is the delivery route: look up the server for
 *   the contract named in the message and drain it. Settled drains ack;
-*   contention arms a later watchdog before acking; handler failure keeps
-*   the current message and redelivers with backoff.
+*   contention and handler failure arm a later watchdog before acking.
 *
 * `@vercel/queue` is an optional peer dependency, imported lazily. The
 * `transport` option is the injection seam — tests run a real little
 * in-memory queue through the same interface.
 */
 /**
-* The "not settled yet" signal for a stalled handler — an expected state,
-* not a transport failure. The default transport classifies it in
-* `@vercel/queue`'s `retry` option and reschedules the delivery quietly
+* The "not settled yet" signal for a drain whose outcome is unknown — an
+* expected state, not a transport failure. The default transport classifies
+* it in `@vercel/queue`'s `retry` option and reschedules the delivery quietly
 * (`{ afterSeconds }` → visibility change → 200 response, no error log)
-* instead of letting it surface as a thrown 500. Busy deliveries use a
-* fresh watchdog instead. Custom transports should treat this class the
+* instead of letting it surface as a thrown 500. Busy and stalled deliveries
+* use a fresh watchdog instead. Custom transports should treat this class the
 * same way when their protocol has a polite reschedule.
 */
 var DrainUnsettled = class extends Error {};
@@ -186,7 +185,7 @@ function vercelQueues(options = {}) {
 						outcome: "unknown"
 					};
 					if (result.settled) return;
-					if (result.outcome === "busy") {
+					if (result.outcome === "busy" || result.outcome === "stalled") {
 						if (result.schedulerArm) await result.schedulerArm;
 						else await sendTask({
 							version: 1,

package/dist/scheduler-vercel.js.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler-vercel.js","names":[],"sources":["../src/scheduler-vercel.ts"],"sourcesContent":["/**\n * experimental-a2/scheduler-vercel — queue-backed scheduler over Vercel Queues.\n *\n * `vercelQueues()` returns an `A2Scheduler` (a2-implementation.md §9):\n *\n * - drain tasks round the requested watchdog time up to a one-second slot.\n *   One message per `(topic, contract, session, dueAt)` coalesces appends,\n *   claim renewals and racing callbacks. `DuplicateMessageError` is\n *   success because that due-time slot is already durable.\n * - append tasks hash their stable task id with the topic for provider\n *   deduplication. Their six-day maximum delay leaves a full day for\n *   delivery and retries inside the provider's seven-day retention.\n *   Clear tasks follow the same identity and delay rules. All tasks use\n *   the configured deployment scope for sending and receiving.\n * - `handler(...servers)` is the delivery route: look up the server for\n *   the contract named in the message and drain it. Settled drains ack;\n *   contention arms a later watchdog before acking; handler failure keeps\n *   the current message and redelivers with backoff.\n *\n * `@vercel/queue` is an optional peer dependency, imported lazily. The\n * `transport` option is the injection seam — tests run a real little\n * in-memory queue through the same interface.\n */\n\nimport { createHash } from 'node:crypto'\nimport { SYSTEM_CLOCK, type Clock } from './store.ts'\nimport {\n  assertSchedulerTargets,\n  classifySchedulerSendFailure,\n  DRAIN_TIMINGS,\n  serverInternals,\n} from './internal.ts'\nimport { retryableLazy } from './retryable-lazy.ts'\nimport {\n  normalizeSchedulerTask,\n  type SchedulerDrainTask,\n  type SchedulerTask,\n} from './scheduler-task.ts'\nimport {\n  deliverSchedulerAppend,\n  deliverSchedulerClear,\n  type A2Scheduler,\n  type DrainableServer,\n} from './server.ts'\n\n/**\n * The \"not settled yet\" signal for a stalled handler — an expected state,\n * not a transport failure. The default transport classifies it in\n * `@vercel/queue`'s `retry` option and reschedules the delivery quietly\n * (`{ afterSeconds }` → visibility change → 200 response, no error log)\n * instead of letting it surface as a thrown 500. Busy deliveries use a\n * fresh watchdog instead. Custom transports should treat this class the\n * same way when their protocol has a polite reschedule.\n */\nexport class DrainUnsettled extends Error {}\n\nexport type QueueDeliveryMetadata = {\n  messageId: string\n  deliveryCount: number\n}\n\n/** What this module needs from a Vercel Queues-compatible transport. */\nexport type QueueTransport = {\n  send(\n    topic: string,\n    message: SchedulerTask,\n    options?: {\n      delaySeconds?: number\n      idempotencyKey?: string\n      retentionSeconds?: number\n    },\n  ): Promise<unknown>\n  /**\n   * Wrap the delivery handler into a route. The handler throws\n   * `DrainUnsettled` when the session needs redelivery — transports\n   * with a polite reschedule (visibility change) should use it there\n   * instead of surfacing an error; anything else thrown is a genuine\n   * failure and should stay loud.\n   */\n  handleCallback(\n    handler: (\n      message: unknown,\n      metadata: QueueDeliveryMetadata,\n    ) => Promise<void>,\n  ): (req: Request) => Promise<Response>\n  /** Is this send error the idempotency-key collision? (= success) */\n  isDuplicate(error: unknown): boolean\n}\n\nexport type VercelQueuesOptions = {\n  /** Queue topic matching `[A-Za-z0-9_-]+`. Default `'a2'`. */\n  topic?: string\n  /** Queue SDK deployment scope for all tasks. Default: VERCEL_DEPLOYMENT_ID; null opts out. */\n  deploymentId?: string | null\n  /** Injectable transport (tests). Default: `@vercel/queue`. */\n  transport?: QueueTransport\n  /** Injectable clock for due-time calculations (tests). */\n  clock?: Clock\n}\n\n/** Vercel Queues rejects shorter visibility changes. */\nconst MIN_VISIBILITY_SECONDS = 30\n\n/** Vercel Queues' maximum message retention and delivery delay. */\nconst MAX_RETENTION_SECONDS = 7 * 24 * 60 * 60\n\n/** Leave the final retention day for delivery and retries. */\nconst MAX_DELAY_SECONDS = 6 * 24 * 60 * 60\n\nconst TOPIC_PATTERN = /^[A-Za-z0-9_-]+$/\nconst RETRYABLE_HTTP_CLIENT_STATUSES = new Set([408, 409, 425, 429])\n/** The SDK's send path maps these statuses to name-only error instances. */\nconst TERMINAL_VERCEL_SEND_ERROR_NAMES = new Set([\n  'BadRequestError',\n  'UnauthorizedError',\n  'ForbiddenError',\n])\n\nconst recordOf = (value: unknown): Record<string, unknown> | null =>\n  value !== null && typeof value === 'object' && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : null\n\nconst httpStatusOf = (error: unknown): number | undefined => {\n  try {\n    const record = recordOf(error)\n    if (!record) return undefined\n    const response = recordOf(record['response'])\n    const statuses = [\n      record['status'],\n      record['statusCode'],\n      response?.['status'],\n    ].filter(\n      (value): value is number =>\n        typeof value === 'number' &&\n        Number.isInteger(value) &&\n        value >= 100 &&\n        value <= 599,\n    )\n    const [status] = statuses\n    if (status === undefined) return undefined\n    return statuses.every((candidate) => candidate === status)\n      ? status\n      : undefined\n  } catch {\n    return undefined\n  }\n}\n\nconst errorNameOf = (error: unknown): string | undefined => {\n  try {\n    const name = recordOf(error)?.['name']\n    return typeof name === 'string' ? name : undefined\n  } catch {\n    return undefined\n  }\n}\n\nconst classifyVercelSendFailure = (error: unknown): unknown => {\n  const status = httpStatusOf(error)\n  const terminal =\n    status === undefined\n      ? TERMINAL_VERCEL_SEND_ERROR_NAMES.has(errorNameOf(error) ?? '')\n      : status >= 400 &&\n        status < 500 &&\n        !RETRYABLE_HTTP_CLIENT_STATUSES.has(status)\n  return classifySchedulerSendFailure(\n    error,\n    terminal ? 'terminal' : 'retryable',\n  )\n}\n\nconst digestId = (parts: readonly string[]): string =>\n  `a2_${createHash('sha256').update(JSON.stringify(parts)).digest('hex')}`\n\n/** Base of the unsettled redelivery backoff, doubled per delivery. */\nconst UNSETTLED_BACKOFF_BASE_SECONDS = 5\n\n/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */\nconst unsettledBackoffSeconds = (deliveryCount: number): number =>\n  Math.min(\n    Math.max(\n      UNSETTLED_BACKOFF_BASE_SECONDS * 2 ** Math.max(deliveryCount - 1, 0),\n      MIN_VISIBILITY_SECONDS,\n    ),\n    60,\n  )\n\nconst vercelQueueTransport = async (\n  clientOptions: Pick<VercelQueuesOptions, 'deploymentId'>,\n): Promise<QueueTransport> => {\n  const queue = await import('@vercel/queue').catch(() => {\n    throw classifySchedulerSendFailure(\n      new Error(\n        \"experimental-a2/scheduler-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport\",\n      ),\n      'terminal',\n    )\n  })\n  const client = new queue.QueueClient(clientOptions)\n  return {\n    send: (topic, message, options) => client.send(topic, message, options),\n    handleCallback: (handler) =>\n      client.handleCallback(handler, {\n        // A hard-killed callback normally has a fresh claim watchdog. If\n        // its successor send also failed, make the old unacked delivery's\n        // fallback as prompt as Vercel Queues permits.\n        visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,\n        // Not-settled-yet is an expected state: reschedule the (still\n        // unacked) delivery via a visibility change — 200, no error\n        // log. Everything else returns undefined → the SDK's default\n        // throw path, which is loud on purpose.\n        retry: (error, metadata) =>\n          error instanceof DrainUnsettled\n            ? {\n                afterSeconds: unsettledBackoffSeconds(metadata.deliveryCount),\n              }\n            : undefined,\n      }) as (req: Request) => Promise<Response>,\n    isDuplicate: (error) => error instanceof queue.DuplicateMessageError,\n  }\n}\n\nexport function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {\n  const topic = options.topic ?? 'a2'\n  if (typeof topic !== 'string' || !TOPIC_PATTERN.test(topic)) {\n    throw new TypeError('vercelQueues() topic must match [A-Za-z0-9_-]+')\n  }\n  const clock = options.clock ?? SYSTEM_CLOCK\n  const clientOptions =\n    options.deploymentId === undefined\n      ? {}\n      : { deploymentId: options.deploymentId }\n\n  // Lazy: constructing the scheduler value does no I/O and works without\n  // the peer dep until the first task or delivery.\n  const transport = retryableLazy(() =>\n    options.transport\n      ? Promise.resolve(options.transport)\n      : vercelQueueTransport(clientOptions),\n  ).get\n\n  const sendTask = async (task: SchedulerTask): Promise<void> => {\n    const nowMs = clock.now().getTime()\n    const requestedDueAt = task.dueAt\n    if (!Number.isFinite(requestedDueAt)) {\n      throw classifySchedulerSendFailure(\n        new TypeError('vercel scheduler dueAt must be a finite number'),\n        'terminal',\n      )\n    }\n    const dueAt =\n      requestedDueAt <= nowMs\n        ? Math.floor(nowMs / 1_000) * 1_000\n        : Math.ceil(requestedDueAt / 1_000) * 1_000\n    const deliveryTargetAt = task.kind === 'drain' ? dueAt : requestedDueAt\n    const deliveryDelaySeconds = Math.max(\n      0,\n      Math.ceil((deliveryTargetAt - nowMs) / 1_000),\n    )\n    if (deliveryDelaySeconds > MAX_DELAY_SECONDS) {\n      throw classifySchedulerSendFailure(\n        new RangeError(\n          'vercelQueues() tasks cannot be delayed more than 6 days',\n        ),\n        'terminal',\n      )\n    }\n    const message: SchedulerTask = { ...task, dueAt }\n    const idempotencyKey =\n      task.kind === 'drain'\n        ? digestId([\n            'a2:scheduler-vercel:drain:v1',\n            topic,\n            task.contract,\n            task.sessionId,\n            String(dueAt),\n          ])\n        : task.kind === 'append'\n          ? digestId(['a2:scheduler-vercel:append:v1', topic, task.id])\n          : digestId(['a2:scheduler-vercel:clear:v1', topic, task.id])\n    const t = await transport()\n    try {\n      await t.send(topic, message, {\n        delaySeconds: deliveryDelaySeconds,\n        idempotencyKey,\n        retentionSeconds: MAX_RETENTION_SECONDS,\n      })\n    } catch (err) {\n      if (t.isDuplicate(err)) return\n      throw classifyVercelSendFailure(err)\n    }\n  }\n\n  const successorDueAt = (message: SchedulerDrainTask): number => {\n    const minimumDueAt =\n      clock.now().getTime() +\n      DRAIN_TIMINGS.claimTtlMs +\n      DRAIN_TIMINGS.watchdogGraceMs\n    const beats = Math.max(\n      1,\n      Math.ceil(\n        (minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs,\n      ),\n    )\n    return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs\n  }\n\n  return {\n    async schedule(task) {\n      await sendTask(task)\n    },\n\n    handler(...servers: DrainableServer[]) {\n      assertSchedulerTargets(servers)\n      const byContract = new Map<string, DrainableServer>()\n      for (const server of servers) {\n        byContract.set(server.contract.name, server)\n      }\n      return async (req: Request): Promise<Response> => {\n        const t = await transport()\n        return t.handleCallback(async (delivered) => {\n          const task = normalizeSchedulerTask(delivered)\n          if (!task) {\n            throw new TypeError('a2 scheduler received an invalid task')\n          }\n          const server = byContract.get(task.contract)\n          if (!server) {\n            // A message for a contract this route doesn't serve is a\n            // wiring bug — throw so it redelivers and stays visible in\n            // queue observability instead of vanishing on an ack.\n            throw new Error(\n              `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,\n            )\n          }\n          const internals = serverInternals.get(server)\n          if (task.kind === 'append') {\n            await deliverSchedulerAppend(server, task)\n            return\n          }\n          if (task.kind === 'clear') {\n            await deliverSchedulerClear(server, task)\n            return\n          }\n\n          const nextDueAt = successorDueAt(task)\n          const result = internals\n            ? await internals.schedulerDrain(task.sessionId, {\n                watchdogDueAt: nextDueAt,\n              })\n            : {\n                ...(await server.drain(task.sessionId)),\n                outcome: 'unknown' as const,\n              }\n          if (result.settled) return\n\n          if (result.outcome === 'busy') {\n            // The live owner normally arms its own claim windows.\n            // Ensure a later slot here as well before relinquishing this\n            // durable delivery. If the queue is down, the throw leaves the\n            // current message unacked for visibility-timeout redelivery.\n            if (result.schedulerArm) await result.schedulerArm\n            else {\n              await sendTask({\n                version: 1,\n                kind: 'drain',\n                contract: task.contract,\n                sessionId: task.sessionId,\n                dueAt: nextDueAt,\n              })\n            }\n            return\n          }\n\n          // Handler failure keeps the current durable message and uses the\n          // transport retry path. Dead-lettered sessions count as settled\n          // above, so retries stop there.\n          throw new DrainUnsettled(\n            `a2 scheduler: session '${task.sessionId}' of '${task.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`,\n          )\n        })(req)\n      }\n    },\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"scheduler-vercel.js","names":[],"sources":["../src/scheduler-vercel.ts"],"sourcesContent":["/**\n * experimental-a2/scheduler-vercel — queue-backed scheduler over Vercel Queues.\n *\n * `vercelQueues()` returns an `A2Scheduler` (a2-implementation.md §9):\n *\n * - drain tasks round the requested watchdog time up to a one-second slot.\n *   One message per `(topic, contract, session, dueAt)` coalesces appends,\n *   claim renewals and racing callbacks. `DuplicateMessageError` is\n *   success because that due-time slot is already durable.\n * - append tasks hash their stable task id with the topic for provider\n *   deduplication. Their six-day maximum delay leaves a full day for\n *   delivery and retries inside the provider's seven-day retention.\n *   Clear tasks follow the same identity and delay rules. All tasks use\n *   the configured deployment scope for sending and receiving.\n * - `handler(...servers)` is the delivery route: look up the server for\n *   the contract named in the message and drain it. Settled drains ack;\n *   contention and handler failure arm a later watchdog before acking.\n *\n * `@vercel/queue` is an optional peer dependency, imported lazily. The\n * `transport` option is the injection seam — tests run a real little\n * in-memory queue through the same interface.\n */\n\nimport { createHash } from 'node:crypto'\nimport { SYSTEM_CLOCK, type Clock } from './store.ts'\nimport {\n  assertSchedulerTargets,\n  classifySchedulerSendFailure,\n  DRAIN_TIMINGS,\n  serverInternals,\n} from './internal.ts'\nimport { retryableLazy } from './retryable-lazy.ts'\nimport {\n  normalizeSchedulerTask,\n  type SchedulerDrainTask,\n  type SchedulerTask,\n} from './scheduler-task.ts'\nimport {\n  deliverSchedulerAppend,\n  deliverSchedulerClear,\n  type A2Scheduler,\n  type DrainableServer,\n} from './server.ts'\n\n/**\n * The \"not settled yet\" signal for a drain whose outcome is unknown — an\n * expected state, not a transport failure. The default transport classifies\n * it in `@vercel/queue`'s `retry` option and reschedules the delivery quietly\n * (`{ afterSeconds }` → visibility change → 200 response, no error log)\n * instead of letting it surface as a thrown 500. Busy and stalled deliveries\n * use a fresh watchdog instead. Custom transports should treat this class the\n * same way when their protocol has a polite reschedule.\n */\nexport class DrainUnsettled extends Error {}\n\nexport type QueueDeliveryMetadata = {\n  messageId: string\n  deliveryCount: number\n}\n\n/** What this module needs from a Vercel Queues-compatible transport. */\nexport type QueueTransport = {\n  send(\n    topic: string,\n    message: SchedulerTask,\n    options?: {\n      delaySeconds?: number\n      idempotencyKey?: string\n      retentionSeconds?: number\n    },\n  ): Promise<unknown>\n  /**\n   * Wrap the delivery handler into a route. The handler throws\n   * `DrainUnsettled` when the session needs redelivery — transports\n   * with a polite reschedule (visibility change) should use it there\n   * instead of surfacing an error; anything else thrown is a genuine\n   * failure and should stay loud.\n   */\n  handleCallback(\n    handler: (\n      message: unknown,\n      metadata: QueueDeliveryMetadata,\n    ) => Promise<void>,\n  ): (req: Request) => Promise<Response>\n  /** Is this send error the idempotency-key collision? (= success) */\n  isDuplicate(error: unknown): boolean\n}\n\nexport type VercelQueuesOptions = {\n  /** Queue topic matching `[A-Za-z0-9_-]+`. Default `'a2'`. */\n  topic?: string\n  /** Queue SDK deployment scope for all tasks. Default: VERCEL_DEPLOYMENT_ID; null opts out. */\n  deploymentId?: string | null\n  /** Injectable transport (tests). Default: `@vercel/queue`. */\n  transport?: QueueTransport\n  /** Injectable clock for due-time calculations (tests). */\n  clock?: Clock\n}\n\n/** Vercel Queues rejects shorter visibility changes. */\nconst MIN_VISIBILITY_SECONDS = 30\n\n/** Vercel Queues' maximum message retention and delivery delay. */\nconst MAX_RETENTION_SECONDS = 7 * 24 * 60 * 60\n\n/** Leave the final retention day for delivery and retries. */\nconst MAX_DELAY_SECONDS = 6 * 24 * 60 * 60\n\nconst TOPIC_PATTERN = /^[A-Za-z0-9_-]+$/\nconst RETRYABLE_HTTP_CLIENT_STATUSES = new Set([408, 409, 425, 429])\n/** The SDK's send path maps these statuses to name-only error instances. */\nconst TERMINAL_VERCEL_SEND_ERROR_NAMES = new Set([\n  'BadRequestError',\n  'UnauthorizedError',\n  'ForbiddenError',\n])\n\nconst recordOf = (value: unknown): Record<string, unknown> | null =>\n  value !== null && typeof value === 'object' && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : null\n\nconst httpStatusOf = (error: unknown): number | undefined => {\n  try {\n    const record = recordOf(error)\n    if (!record) return undefined\n    const response = recordOf(record['response'])\n    const statuses = [\n      record['status'],\n      record['statusCode'],\n      response?.['status'],\n    ].filter(\n      (value): value is number =>\n        typeof value === 'number' &&\n        Number.isInteger(value) &&\n        value >= 100 &&\n        value <= 599,\n    )\n    const [status] = statuses\n    if (status === undefined) return undefined\n    return statuses.every((candidate) => candidate === status)\n      ? status\n      : undefined\n  } catch {\n    return undefined\n  }\n}\n\nconst errorNameOf = (error: unknown): string | undefined => {\n  try {\n    const name = recordOf(error)?.['name']\n    return typeof name === 'string' ? name : undefined\n  } catch {\n    return undefined\n  }\n}\n\nconst classifyVercelSendFailure = (error: unknown): unknown => {\n  const status = httpStatusOf(error)\n  const terminal =\n    status === undefined\n      ? TERMINAL_VERCEL_SEND_ERROR_NAMES.has(errorNameOf(error) ?? '')\n      : status >= 400 &&\n        status < 500 &&\n        !RETRYABLE_HTTP_CLIENT_STATUSES.has(status)\n  return classifySchedulerSendFailure(\n    error,\n    terminal ? 'terminal' : 'retryable',\n  )\n}\n\nconst digestId = (parts: readonly string[]): string =>\n  `a2_${createHash('sha256').update(JSON.stringify(parts)).digest('hex')}`\n\n/** Base of the unsettled redelivery backoff, doubled per delivery. */\nconst UNSETTLED_BACKOFF_BASE_SECONDS = 5\n\n/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */\nconst unsettledBackoffSeconds = (deliveryCount: number): number =>\n  Math.min(\n    Math.max(\n      UNSETTLED_BACKOFF_BASE_SECONDS * 2 ** Math.max(deliveryCount - 1, 0),\n      MIN_VISIBILITY_SECONDS,\n    ),\n    60,\n  )\n\nconst vercelQueueTransport = async (\n  clientOptions: Pick<VercelQueuesOptions, 'deploymentId'>,\n): Promise<QueueTransport> => {\n  const queue = await import('@vercel/queue').catch(() => {\n    throw classifySchedulerSendFailure(\n      new Error(\n        \"experimental-a2/scheduler-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport\",\n      ),\n      'terminal',\n    )\n  })\n  const client = new queue.QueueClient(clientOptions)\n  return {\n    send: (topic, message, options) => client.send(topic, message, options),\n    handleCallback: (handler) =>\n      client.handleCallback(handler, {\n        // A hard-killed callback normally has a fresh claim watchdog. If\n        // its successor send also failed, make the old unacked delivery's\n        // fallback as prompt as Vercel Queues permits.\n        visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,\n        // Not-settled-yet is an expected state: reschedule the (still\n        // unacked) delivery via a visibility change — 200, no error\n        // log. Everything else returns undefined → the SDK's default\n        // throw path, which is loud on purpose.\n        retry: (error, metadata) =>\n          error instanceof DrainUnsettled\n            ? {\n                afterSeconds: unsettledBackoffSeconds(metadata.deliveryCount),\n              }\n            : undefined,\n      }) as (req: Request) => Promise<Response>,\n    isDuplicate: (error) => error instanceof queue.DuplicateMessageError,\n  }\n}\n\nexport function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {\n  const topic = options.topic ?? 'a2'\n  if (typeof topic !== 'string' || !TOPIC_PATTERN.test(topic)) {\n    throw new TypeError('vercelQueues() topic must match [A-Za-z0-9_-]+')\n  }\n  const clock = options.clock ?? SYSTEM_CLOCK\n  const clientOptions =\n    options.deploymentId === undefined\n      ? {}\n      : { deploymentId: options.deploymentId }\n\n  // Lazy: constructing the scheduler value does no I/O and works without\n  // the peer dep until the first task or delivery.\n  const transport = retryableLazy(() =>\n    options.transport\n      ? Promise.resolve(options.transport)\n      : vercelQueueTransport(clientOptions),\n  ).get\n\n  const sendTask = async (task: SchedulerTask): Promise<void> => {\n    const nowMs = clock.now().getTime()\n    const requestedDueAt = task.dueAt\n    if (!Number.isFinite(requestedDueAt)) {\n      throw classifySchedulerSendFailure(\n        new TypeError('vercel scheduler dueAt must be a finite number'),\n        'terminal',\n      )\n    }\n    const dueAt =\n      requestedDueAt <= nowMs\n        ? Math.floor(nowMs / 1_000) * 1_000\n        : Math.ceil(requestedDueAt / 1_000) * 1_000\n    const deliveryTargetAt = task.kind === 'drain' ? dueAt : requestedDueAt\n    const deliveryDelaySeconds = Math.max(\n      0,\n      Math.ceil((deliveryTargetAt - nowMs) / 1_000),\n    )\n    if (deliveryDelaySeconds > MAX_DELAY_SECONDS) {\n      throw classifySchedulerSendFailure(\n        new RangeError(\n          'vercelQueues() tasks cannot be delayed more than 6 days',\n        ),\n        'terminal',\n      )\n    }\n    const message: SchedulerTask = { ...task, dueAt }\n    const idempotencyKey =\n      task.kind === 'drain'\n        ? digestId([\n            'a2:scheduler-vercel:drain:v1',\n            topic,\n            task.contract,\n            task.sessionId,\n            String(dueAt),\n          ])\n        : task.kind === 'append'\n          ? digestId(['a2:scheduler-vercel:append:v1', topic, task.id])\n          : digestId(['a2:scheduler-vercel:clear:v1', topic, task.id])\n    const t = await transport()\n    try {\n      await t.send(topic, message, {\n        delaySeconds: deliveryDelaySeconds,\n        idempotencyKey,\n        retentionSeconds: MAX_RETENTION_SECONDS,\n      })\n    } catch (err) {\n      if (t.isDuplicate(err)) return\n      throw classifyVercelSendFailure(err)\n    }\n  }\n\n  const successorDueAt = (message: SchedulerDrainTask): number => {\n    const minimumDueAt =\n      clock.now().getTime() +\n      DRAIN_TIMINGS.claimTtlMs +\n      DRAIN_TIMINGS.watchdogGraceMs\n    const beats = Math.max(\n      1,\n      Math.ceil(\n        (minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs,\n      ),\n    )\n    return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs\n  }\n\n  return {\n    async schedule(task) {\n      await sendTask(task)\n    },\n\n    handler(...servers: DrainableServer[]) {\n      assertSchedulerTargets(servers)\n      const byContract = new Map<string, DrainableServer>()\n      for (const server of servers) {\n        byContract.set(server.contract.name, server)\n      }\n      return async (req: Request): Promise<Response> => {\n        const t = await transport()\n        return t.handleCallback(async (delivered) => {\n          const task = normalizeSchedulerTask(delivered)\n          if (!task) {\n            throw new TypeError('a2 scheduler received an invalid task')\n          }\n          const server = byContract.get(task.contract)\n          if (!server) {\n            // A message for a contract this route doesn't serve is a\n            // wiring bug — throw so it redelivers and stays visible in\n            // queue observability instead of vanishing on an ack.\n            throw new Error(\n              `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,\n            )\n          }\n          const internals = serverInternals.get(server)\n          if (task.kind === 'append') {\n            await deliverSchedulerAppend(server, task)\n            return\n          }\n          if (task.kind === 'clear') {\n            await deliverSchedulerClear(server, task)\n            return\n          }\n\n          const nextDueAt = successorDueAt(task)\n          const result = internals\n            ? await internals.schedulerDrain(task.sessionId, {\n                watchdogDueAt: nextDueAt,\n              })\n            : {\n                ...(await server.drain(task.sessionId)),\n                outcome: 'unknown' as const,\n              }\n          if (result.settled) return\n\n          if (result.outcome === 'busy' || result.outcome === 'stalled') {\n            // The live owner arms its own claim windows, and the store holds\n            // a failed event until its retry time. Ensure a later slot here\n            // as well before relinquishing this durable delivery. If the queue is down, the\n            // throw leaves the current message unacked for visibility-timeout\n            // redelivery.\n            if (result.schedulerArm) await result.schedulerArm\n            else {\n              await sendTask({\n                version: 1,\n                kind: 'drain',\n                contract: task.contract,\n                sessionId: task.sessionId,\n                dueAt: nextDueAt,\n              })\n            }\n            return\n          }\n\n          // A drain whose outcome is unknown keeps the current durable message\n          // and uses the transport retry path.\n          throw new DrainUnsettled(\n            `a2 scheduler: session '${task.sessionId}' of '${task.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`,\n          )\n        })(req)\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/{server-Rj64fNvX.js → server-D-Y4pqwu.js}

@@ -1,50 +1,13 @@
 import { a as NonRetriableError, i as A2Error, n as isSessionCleared, o as asStoreUnavailable, r as sessionClearedError } from "./session-clear-DGI4jTQ5.js";
 import { n as foldEvent, s as validateSync, t as cloneInitial } from "./reducer-BAXc8JyF.js";
 import { n as encodeState, t as decodeState } from "./reducer-runtime-DQwz_J59.js";
-import { _ as serverInternals, c as STATE_CACHE, g as nullProtoRecord, h as markSchedulerSendFailure, i as POLL_TIMINGS, l as STREAM_TIMINGS, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, t as DRAIN_TIMINGS, v as stateTailReaders } from "./internal-CbVvEwad.js";
-import { i as streamActivities, r as createStreamActivity, t as defaultSleep } from "./store-polling-4_y8lETm.js";
+import { _ as nullProtoRecord, c as STATE_CACHE, g as markSchedulerSendFailure, i as POLL_TIMINGS, l as STREAM_TIMINGS, m as failedPreviousAttempt, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, t as DRAIN_TIMINGS, v as serverInternals, y as stateTailReaders } from "./internal-CscSY7K_.js";
+import { t as boundedCache } from "./bounded-cache-CPHWF-8h.js";
+import { i as streamActivities, r as createStreamActivity, t as defaultSleep } from "./store-polling-7WJV0YWP.js";
 import { i as takeBuffered, n as isSerializedEvent, r as parseSerializedEvent, t as bufferedEvents } from "./stream-buffer-Cx7AAPGq.js";
 import { r as platformWaitUntil, t as invocationDeadlineMs } from "./platform-B4TnJtWu.js";
-import { A as stateSnapshotToWire, C as serializedEventToWireJson, D as socketFrameFor, E as socketEventsFor, O as socketSubscribedFor, S as presenceSnapshotToWire, T as socketErrorAckFor, b as presencePatchToWire, d as heldEventBatch, i as compactEventJson, j as wireVersion, k as socketUnsubscribedFor, m as isStreamEvent, n as SOCKET_PING_FRAME, o as errorStatus, r as asA2Error, s as errorToWire, t as EVENT_WRITE_CHARS, u as eventToWire, w as socketAckFor } from "./wire-DjfHOvdW.js";
+import { A as stateSnapshotToWire, C as serializedEventToWireJson, D as socketFrameFor, E as socketEventsFor, O as socketSubscribedFor, S as presenceSnapshotToWire, T as socketErrorAckFor, b as presencePatchToWire, d as heldEventBatch, i as compactEventJson, j as wireVersion, k as socketUnsubscribedFor, m as isStreamEvent, n as SOCKET_PING_FRAME, o as errorStatus, r as asA2Error, s as errorToWire, t as EVENT_WRITE_CHARS, u as eventToWire, w as socketAckFor } from "./wire-BKxH1vbP.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
-//#region src/bounded-cache.ts
-function boundedCache({ maxEntries, maxBytes }) {
-	const entries = /* @__PURE__ */ new Map();
-	let total = 0;
-	const remove = (key) => {
-		const entry = entries.get(key);
-		if (!entry) return;
-		entries.delete(key);
-		total -= entry.bytes;
-	};
-	return {
-		get(key) {
-			const entry = entries.get(key);
-			if (!entry) return void 0;
-			entries.delete(key);
-			entries.set(key, entry);
-			return entry.value;
-		},
-		set(key, value, bytes) {
-			remove(key);
-			if (bytes > maxBytes / 4) return;
-			entries.set(key, {
-				value,
-				bytes
-			});
-			total += bytes;
-			for (const oldest of entries.keys()) {
-				if (entries.size <= maxEntries && total <= maxBytes) break;
-				remove(oldest);
-			}
-		},
-		delete: remove,
-		deleteWhere(match) {
-			for (const key of entries.keys()) if (match(key)) remove(key);
-		}
-	};
-}
-//#endregion
 //#region src/push-envelope.ts
 /**
 * The push envelope's trust boundary for `{ sessionId, events, presence? }`,
@@ -1142,6 +1105,8 @@ function handler(entry) {
 	return typeof entry === "function" ? { handler: entry } : entry;
 }
 const MAX_FAILURES = 10;
+/** How long an event waits after its `failureCount`th failed attempt. */
+const failureRetryDelayMs = (failureCount) => Math.min(DRAIN_TIMINGS.failureRetryBaseMs * 2 ** Math.max(failureCount - 1, 0), DRAIN_TIMINGS.failureRetryMaxMs);
 /** Abort a lost attempt's handler and release its drain slot. */
 function endSuperseded(entry, message) {
 	entry.supersede.abort(new A2Error("SUPERSEDED_ATTEMPT", message));
@@ -1202,9 +1167,11 @@ function pruneAbortHub(hub) {
 	for (const [index, event] of hub.seen) if (index <= minimum || !types.has(event.type)) hub.seen.delete(index);
 }
 /**
-* Deadlines tighten the claim/watchdog window; they never decide whether a
-* handler starts. A platform timeout therefore follows the same path as any
-* other process death: the in-flight event remains pending and is retried.
+* Deadlines tighten the claim/watchdog window, and a passed deadline ends
+* claiming: a claim then could not run, only lapse and be claimed again until
+* the platform ends the process. A platform timeout otherwise follows the
+* same path as any other process death: the in-flight event remains pending
+* and a fresh invocation retries it.
 */
 function nextClaimWindow() {
 	const nowMs = Date.now();
@@ -1217,7 +1184,8 @@ function nextClaimWindow() {
 		ttlMs,
 		expiresAtMs,
 		watchdogAtMs: expiresAtMs + DRAIN_TIMINGS.watchdogGraceMs,
-		deadlineCapped
+		deadlineCapped,
+		pastDeadline: deadlineMs !== null && deadlineTtlMs <= 0
 	};
 }
 function schedulerSlot(dueAt) {
@@ -1235,6 +1203,19 @@ function currentSchedulerSlot(now) {
 */
 const NS = "";
 const devDefaultStore = retryableLazy(() => import("./store-sqlite.js").then((m) => m.sqlite()));
+/** Waits for a scheduler arm for at most `schedulerArmTimeoutMs`. */
+async function joinSchedulerArm(arm) {
+	let timeout = null;
+	try {
+		await Promise.race([arm, new Promise((_, reject) => {
+			timeout = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`a2 scheduler arm timed out after ${DRAIN_TIMINGS.schedulerArmTimeoutMs}ms`));
+			}, DRAIN_TIMINGS.schedulerArmTimeoutMs);
+		})]);
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
 function environment() {
 	const env = typeof process === "undefined" ? void 0 : process.env?.["NODE_ENV"];
 	if (env === "test") return "test";
@@ -1483,21 +1464,12 @@ function createServer(options) {
 		const dispatchArm = shouldHealSession && mode === "dispatch" ? startSchedulerArm(sessionId, currentSchedulerSlot(Date.now())) : null;
 		if (shouldHealSession && mode === "inline") onAppended(appended, initialWatchdogAt);
 		if (dispatchArm) await dispatchArm;
-		if (initialArm) {
-			let timeout = null;
-			try {
-				await Promise.race([initialArm, new Promise((_, reject) => {
-					timeout = setTimeout(() => {
-						reject(/* @__PURE__ */ new Error(`a2 scheduler arm timed out after ${DRAIN_TIMINGS.schedulerArmTimeoutMs}ms`));
-					}, DRAIN_TIMINGS.schedulerArmTimeoutMs);
-				})]);
-			} catch (err) {
-				span.setAttribute("a2.append.armed", false);
-				span.recordError(err);
-				if (requireDurableInitialArm) throw err;
-			} finally {
-				if (timeout) clearTimeout(timeout);
-			}
+		if (initialArm) try {
+			await joinSchedulerArm(initialArm);
+		} catch (err) {
+			span.setAttribute("a2.append.armed", false);
+			span.recordError(err);
+			if (requireDurableInitialArm) throw err;
 		}
 		return appended;
 	});
@@ -2342,6 +2314,64 @@ function createServer(options) {
 			index: result.index
 		};
 	};
+	const redrivingStore = async (method) => {
+		const store = await resolveStore();
+		if (!store.deadLetters || !store.redrive) throw new TypeError(`session.${method} requires a store that supports redriving dead letters`);
+		return store;
+	};
+	const listDeadLetters = async (sessionId) => {
+		const store = await redrivingStore("deadLetters");
+		let rows;
+		try {
+			rows = await store.deadLetters(nsId(sessionId));
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+		return rows.flatMap((row) => row.failedAt === null ? [] : [{
+			...toPublic(row),
+			lane: row.lane,
+			attemptCount: row.attemptCount,
+			failureCount: row.failureCount,
+			lastError: row.lastError,
+			failedAt: row.failedAt
+		}]);
+	};
+	const redriveEvent = async (sessionId, index, redriveOptions) => {
+		assertRedriveIndex(index);
+		const action = redriveOptions?.action;
+		if (action !== "retry" && action !== "skip") throw new TypeError("redrive requires action 'retry' or 'skip'");
+		return telemetry.span("a2.redrive", {
+			"a2.contract": name,
+			"a2.session_id": sessionId,
+			"a2.redrive.index": index,
+			"a2.redrive.action": action
+		}, async (span) => {
+			const store = await redrivingStore("redrive");
+			let result;
+			try {
+				result = await store.redrive({
+					sessionId: nsId(sessionId),
+					index,
+					action
+				});
+			} catch (err) {
+				throw asStoreUnavailable(err);
+			}
+			span.setAttribute("a2.redrive.redriven", result.redriven);
+			if (result.hasPending) {
+				const watchdogAt = scheduler ? schedulerSlot(nextClaimWindow().watchdogAtMs) : void 0;
+				const arm = watchdogAt === void 0 ? null : startSchedulerArm(sessionId, watchdogAt);
+				scheduleDrain(sessionId, watchdogAt);
+				if (arm) try {
+					await joinSchedulerArm(arm);
+				} catch (err) {
+					span.setAttribute("a2.redrive.armed", false);
+					span.recordError(err);
+				}
+			}
+			return { redriven: result.redriven };
+		});
+	};
 	const makeSession = (id, append, trigger, attempt) => ({
 		id,
 		append,
@@ -2389,7 +2419,7 @@ function createServer(options) {
 				attempt
 			}, generatedIds);
 		};
-		return {
+		const ctx = {
 			event: toPublic(trigger),
 			attempt,
 			session: makeSession(publicSessionId, append, trigger, {
@@ -2402,6 +2432,8 @@ function createServer(options) {
 			}),
 			signal
 		};
+		if (attempt > 1 && trigger.lastFailedAttempt === attempt - 1) failedPreviousAttempt.add(ctx);
+		return ctx;
 	};
 	const abortHubs = /* @__PURE__ */ new Map();
 	const createAbortHub = (store, ns, startAfter) => {
@@ -2612,6 +2644,19 @@ function createServer(options) {
 			renewal = tracked;
 			return tracked;
 		};
+		/** Records an event the store dead-lettered on takeover; it never runs. */
+		const reportExhausted = (event) => telemetry.span("a2.event", {
+			"a2.contract": name,
+			"a2.session_id": sessionId,
+			"a2.event.type": event.type,
+			"a2.event.index": event.index,
+			"a2.event.id": event.id,
+			"a2.event.attempt": event.attemptCount,
+			"a2.event.handled": handlers.has(event.type),
+			...event.lane === null ? {} : { "a2.event.lane": event.lane }
+		}, async (eventSpan) => {
+			eventSpan.setAttribute("a2.event.outcome", "dead_lettered");
+		});
 		const runEvent = async (event, supersedeSignal, endAttempt) => {
 			const registration = handlers.get(event.type);
 			return telemetry.span("a2.event", {
@@ -2661,7 +2706,8 @@ function createServer(options) {
 							index: event.index,
 							attempt: event.attemptCount,
 							error: describeError(err),
-							maxFailures: err instanceof NonRetriableError ? 1 : MAX_FAILURES
+							maxFailures: err instanceof NonRetriableError ? 1 : MAX_FAILURES,
+							retryAfterMs: failureRetryDelayMs(event.failureCount + 1)
 						});
 						commitSpan.setAttribute("a2.commit.outcome", result.outcome);
 						return result;
@@ -2753,6 +2799,10 @@ function createServer(options) {
 				let claim;
 				if (shouldClaim) {
 					const window = nextClaimWindow();
+					if (window.pastDeadline) {
+						outcome = "busy";
+						break;
+					}
 					claim = await telemetry.span("a2.claim", {
 						"a2.contract": name,
 						"a2.session_id": sessionId
@@ -2761,6 +2811,7 @@ function createServer(options) {
 							sessionId: ns,
 							holder,
 							ttlMs: window.ttlMs,
+							maxFailures: MAX_FAILURES,
 							...window.deadlineCapped ? { expiresAtMs: window.expiresAtMs } : {},
 							...excluded.size === 0 ? {} : { excludeIndexes: [...excluded] }
 						});
@@ -2769,9 +2820,11 @@ function createServer(options) {
 						return result;
 					});
 					if (claim.outcome === "claimed") {
-						requestWatchdog(window.watchdogAtMs);
+						const runnable = claim.events.filter((event) => event.failedAt === null);
+						for (const event of claim.events) if (event.failedAt !== null) await reportExhausted(event);
+						if (runnable.length > 0) requestWatchdog(window.watchdogAtMs);
 						if (window.deadlineCapped) stopRenewing = true;
-						for (const event of claim.events) start(event, window.expiresAtMs);
+						for (const event of runnable) start(event, window.expiresAtMs);
 						shouldClaim = false;
 					}
 				}
@@ -2833,7 +2886,10 @@ function createServer(options) {
 		const appendInline = async (...events) => appendExternal(id, "inline", events);
 		const appendDispatch = async (...events) => appendExternal(id, "dispatch", events);
 		const append = Object.assign(appendInline, { dispatch: appendDispatch });
-		return makeSession(id, append, null);
+		return Object.assign(makeSession(id, append, null), {
+			deadLetters: () => listDeadLetters(id),
+			redrive: (index, redriveOptions) => redriveEvent(id, index, redriveOptions)
+		});
 	};
 	const historyPage = async (sessionId, bounds) => {
 		assertSessionId(sessionId);
@@ -2898,6 +2954,9 @@ function assertStreamIndex(value) {
 function assertStateIndex(value) {
 	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("state.through must be a non-negative safe integer");
 }
+function assertRedriveIndex(value) {
+	if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("redrive requires a positive safe-integer index");
+}
 function assertClearIndex(value) {
 	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("ifLastIndex must be a non-negative safe integer");
 }
@@ -2988,6 +3047,6 @@ const measuredBytes = (reducer, state, index, snapshots) => JSON.stringify(snaps
 }))?.length ?? 0;
 const stateCacheKey = (sessionId, reducerName) => `${sessionId}\u0000${reducerName}`;
 //#endregion
-export { CONSOLE_TELEMETRY as a, parsePresenceSibling as c, handler as i, boundedCache as l, deliverSchedulerAppend as n, setServerFetchHooks as o, deliverSchedulerClear as r, sseResponse as s, createServer as t };
+export { CONSOLE_TELEMETRY as a, parsePresenceSibling as c, handler as i, deliverSchedulerAppend as n, setServerFetchHooks as o, deliverSchedulerClear as r, sseResponse as s, createServer as t };
 
-//# sourceMappingURL=server-Rj64fNvX.js.map
+//# sourceMappingURL=server-D-Y4pqwu.js.map