experimental-a2 0.3.0 → 0.5.0

package/dist/{recovery-vercel.d.ts → scheduler-vercel.d.ts}

@@ -1,6 +1,6 @@
-import { i as Clock } from "./log-ldf5g8Cx.js";
-import { A2Recovery } from "./server.js";
-//#region src/recovery-vercel.d.ts
+import { i as Clock } from "./store-DysUkTH3.js";
+import { D as SchedulerTask, t as A2Scheduler } from "./server-DUF9pjsx.js";
+//#region src/scheduler-vercel.d.ts
 /**
  * The "not settled yet" signal for a stalled handler — an expected state,
  * not a transport failure. The default transport classifies it in
@@ -10,51 +10,45 @@ import { A2Recovery } from "./server.js";
  * fresh watchdog instead. Custom transports should treat this class the
  * same way when their protocol has a polite reschedule.
  */
-declare class RecoveryUnsettled extends Error {}
-/** The message a2 puts on the queue. Application state lives in the log. */
-type RecoveryMessage = {
-  contract: string;
-  sessionId: string;
-  /** Whole-second epoch time this watchdog was scheduled to become visible. */
-  dueAt?: number;
-};
+declare class DrainUnsettled extends Error {}
 type QueueDeliveryMetadata = {
   messageId: string;
   deliveryCount: number;
 };
-/**
- * What this module needs from a queue — `@vercel/queue`'s `send` and
- * `handleCallback` match it structurally.
- */
+/** What this module needs from a Vercel Queues-compatible transport. */
 type QueueTransport = {
-  send(topic: string, message: RecoveryMessage, options?: {
+  send(topic: string, message: SchedulerTask, options?: {
     delaySeconds?: number;
     idempotencyKey?: string;
+    retentionSeconds?: number;
+  }, routing?: {
+    deployment: "deployment" | "deploymentless";
   }): Promise<unknown>;
   /**
    * Wrap the delivery handler into a route. The handler throws
-   * `RecoveryUnsettled` when the session needs redelivery — transports
+   * `DrainUnsettled` when the session needs redelivery — transports
    * with a polite reschedule (visibility change) should use it there
    * instead of surfacing an error; anything else thrown is a genuine
    * failure and should stay loud.
    */
-  handleCallback(handler: (message: RecoveryMessage, metadata: QueueDeliveryMetadata) => Promise<void>): (req: Request) => Promise<Response>;
+  handleCallback(handler: (message: unknown, metadata: QueueDeliveryMetadata) => Promise<void>): (req: Request) => Promise<Response>;
   /** Is this send error the idempotency-key collision? (= success) */
   isDuplicate(error: unknown): boolean;
 };
 type VercelQueuesOptions = {
-  /** Queue topic. One topic serves every contract. Default `'a2'`. */
+  /** Queue topic matching `[A-Za-z0-9_-]+`. Default `'a2'`. */
   topic?: string;
   /**
-   * Fallback delay when an arm does not supply an absolute due time.
-   * Core A2 arms claim windows explicitly. Default 5.
+   * Deployment affinity for scheduled append tasks. Recovery drain tasks
+   * always target the publishing deployment. Default `'deployment'`.
    */
-  delaySeconds?: number;
+  scheduledAppends?: "deployment" | "deploymentless";
   /** Injectable transport (tests). Default: `@vercel/queue`. */
   transport?: QueueTransport;
   /** Injectable clock for due-time calculations (tests). */
   clock?: Clock;
 };
-declare function vercelQueues(options?: VercelQueuesOptions): A2Recovery;
+declare function vercelQueues(options?: VercelQueuesOptions): A2Scheduler;
 //#endregion
-export { QueueDeliveryMetadata, QueueTransport, RecoveryMessage, RecoveryUnsettled, VercelQueuesOptions, vercelQueues };
+export { DrainUnsettled, QueueDeliveryMetadata, QueueTransport, VercelQueuesOptions, vercelQueues };
+//# sourceMappingURL=scheduler-vercel.d.ts.map

package/dist/scheduler-vercel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-vercel.d.ts","names":[],"sources":["../src/scheduler-vercel.ts"],"mappings":";;;;;;;;;;;;cAqDa,uBAAuB;KAExB;EACV;EACA;;;KAYU;EACV,KACE,eACA,SAAS,eACT;IACE;IACA;IACA;KAGF;IACE;MAED;;;;;;;;EAQH,eACE,UACE,kBACA,UAAU,0BACP,iBACH,KAAK,YAAY,QAAQ;;EAE7B,YAAY;;KAGF;;EAEV;;;;;EAKA;;EAEA,YAAY;;EAEZ,QAAQ;;iBA+JM,aAAa,UAAS,sBAA2B"}

package/dist/scheduler-vercel.js

@@ -0,0 +1,228 @@
+import { f as classifySchedulerSendFailure, t as DRAIN_TIMINGS, u as assertSchedulerTargets, v as serverInternals } from "./internal-DstsI6Re.js";
+import { n as deliverSchedulerAppend } from "./server-C72KOw51.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-BpzhPnRS.js";
+import { createHash } from "node:crypto";
+//#region src/scheduler-vercel.ts
+/**
+* experimental-a2/scheduler-vercel — queue-backed scheduler over Vercel Queues.
+*
+* `vercelQueues()` returns an `A2Scheduler` (a2-implementation.md §9):
+*
+* - drain tasks round the requested watchdog time up to a one-second slot.
+*   One message per `(topic, contract, session, dueAt)` coalesces appends,
+*   claim renewals and racing callbacks. `DuplicateMessageError` is
+*   success because that due-time slot is already durable.
+* - append tasks hash their stable task id with the topic for provider
+*   deduplication. Their six-day maximum delay leaves a full day for
+*   delivery and retries inside the provider's seven-day retention.
+*   They target the publishing deployment unless explicitly configured
+*   as deploymentless. Drain tasks always remain deployment-scoped.
+* - `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.
+*
+* `@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
+* (`{ 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
+* same way when their protocol has a polite reschedule.
+*/
+var DrainUnsettled = class extends Error {};
+/** Vercel Queues rejects shorter visibility changes. */
+const MIN_VISIBILITY_SECONDS = 30;
+/** Vercel Queues' maximum message retention and delivery delay. */
+const MAX_RETENTION_SECONDS = 604800;
+/** Leave the final retention day for delivery and retries. */
+const MAX_DELAY_SECONDS = 518400;
+const TOPIC_PATTERN = /^[A-Za-z0-9_-]+$/;
+const RETRYABLE_HTTP_CLIENT_STATUSES = /* @__PURE__ */ new Set([
+	408,
+	409,
+	425,
+	429
+]);
+/** The SDK's send path maps these statuses to name-only error instances. */
+const TERMINAL_VERCEL_SEND_ERROR_NAMES = /* @__PURE__ */ new Set([
+	"BadRequestError",
+	"UnauthorizedError",
+	"ForbiddenError"
+]);
+const recordOf = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+const httpStatusOf = (error) => {
+	try {
+		const record = recordOf(error);
+		if (!record) return void 0;
+		const response = recordOf(record["response"]);
+		const statuses = [
+			record["status"],
+			record["statusCode"],
+			response?.["status"]
+		].filter((value) => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599);
+		const [status] = statuses;
+		if (status === void 0) return void 0;
+		return statuses.every((candidate) => candidate === status) ? status : void 0;
+	} catch {
+		return;
+	}
+};
+const errorNameOf = (error) => {
+	try {
+		const name = recordOf(error)?.["name"];
+		return typeof name === "string" ? name : void 0;
+	} catch {
+		return;
+	}
+};
+const classifyVercelSendFailure = (error) => {
+	const status = httpStatusOf(error);
+	const terminal = status === void 0 ? TERMINAL_VERCEL_SEND_ERROR_NAMES.has(errorNameOf(error) ?? "") : status >= 400 && status < 500 && !RETRYABLE_HTTP_CLIENT_STATUSES.has(status);
+	return classifySchedulerSendFailure(error, terminal ? "terminal" : "retryable");
+};
+const digestId = (parts) => `a2_${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+/** Base of the unsettled redelivery backoff, doubled per delivery. */
+const UNSETTLED_BACKOFF_BASE_SECONDS = 5;
+/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */
+const unsettledBackoffSeconds = (deliveryCount) => Math.min(Math.max(UNSETTLED_BACKOFF_BASE_SECONDS * 2 ** Math.max(deliveryCount - 1, 0), MIN_VISIBILITY_SECONDS), 60);
+const vercelQueueTransport = async () => {
+	const queue = await import("@vercel/queue").catch(() => {
+		throw classifySchedulerSendFailure(/* @__PURE__ */ new Error("experimental-a2/scheduler-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport"), "terminal");
+	});
+	const deploymentClient = new queue.QueueClient();
+	const deploymentlessClient = new queue.QueueClient({ deploymentId: null });
+	return {
+		send: (topic, message, options, routing) => {
+			const deployment = routing?.deployment ?? "deployment";
+			const body = {
+				...message,
+				_a2Vercel: {
+					version: 1,
+					deployment
+				}
+			};
+			return (deployment === "deploymentless" ? deploymentlessClient : deploymentClient).send(topic, body, options);
+		},
+		handleCallback: (handler) => {
+			const callbackOptions = {
+				visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,
+				retry: (error, metadata) => error instanceof DrainUnsettled ? { afterSeconds: unsettledBackoffSeconds(metadata.deliveryCount) } : void 0
+			};
+			const deploymentHandler = deploymentClient.handleCallback(handler, callbackOptions);
+			const deploymentlessHandler = deploymentlessClient.handleCallback(handler, callbackOptions);
+			return async (req) => {
+				let delivered;
+				try {
+					delivered = await req.clone().json();
+				} catch {
+					return deploymentlessHandler(req);
+				}
+				const metadata = recordOf(recordOf(delivered)?.["_a2Vercel"]);
+				return (metadata?.["version"] === 1 ? metadata["deployment"] : void 0) === "deployment" ? deploymentHandler(req) : deploymentlessHandler(req);
+			};
+		},
+		isDuplicate: (error) => error instanceof queue.DuplicateMessageError
+	};
+};
+function vercelQueues(options = {}) {
+	const topic = options.topic ?? "a2";
+	if (typeof topic !== "string" || !TOPIC_PATTERN.test(topic)) throw new TypeError("vercelQueues() topic must match [A-Za-z0-9_-]+");
+	const scheduledAppends = options.scheduledAppends ?? "deployment";
+	if (scheduledAppends !== "deployment" && scheduledAppends !== "deploymentless") throw new TypeError("vercelQueues() scheduledAppends must be 'deployment' or 'deploymentless'");
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const transport = retryableLazy(() => options.transport ? Promise.resolve(options.transport) : vercelQueueTransport()).get;
+	const sendTask = async (task) => {
+		const nowMs = clock.now().getTime();
+		const requestedDueAt = task.dueAt;
+		if (!Number.isFinite(requestedDueAt)) throw classifySchedulerSendFailure(/* @__PURE__ */ new TypeError("vercel scheduler dueAt must be a finite number"), "terminal");
+		const dueAt = requestedDueAt <= nowMs ? Math.floor(nowMs / 1e3) * 1e3 : Math.ceil(requestedDueAt / 1e3) * 1e3;
+		const deliveryTargetAt = task.kind === "append" ? requestedDueAt : dueAt;
+		const deliveryDelaySeconds = Math.max(0, Math.ceil((deliveryTargetAt - nowMs) / 1e3));
+		if (deliveryDelaySeconds > MAX_DELAY_SECONDS) throw classifySchedulerSendFailure(/* @__PURE__ */ new RangeError("vercelQueues() tasks cannot be delayed more than 6 days"), "terminal");
+		const deployment = task.kind === "append" ? scheduledAppends : "deployment";
+		const message = {
+			...task,
+			dueAt
+		};
+		const idempotencyKey = task.kind === "drain" ? digestId([
+			"a2:scheduler-vercel:drain:v1",
+			topic,
+			task.contract,
+			task.sessionId,
+			String(dueAt)
+		]) : digestId([
+			"a2:scheduler-vercel:append:v1",
+			topic,
+			task.id
+		]);
+		const t = await transport();
+		try {
+			await t.send(topic, message, {
+				delaySeconds: deliveryDelaySeconds,
+				idempotencyKey,
+				retentionSeconds: MAX_RETENTION_SECONDS
+			}, { deployment });
+		} catch (err) {
+			if (t.isDuplicate(err)) return;
+			throw classifyVercelSendFailure(err);
+		}
+	};
+	const successorDueAt = (message) => {
+		const minimumDueAt = clock.now().getTime() + DRAIN_TIMINGS.claimTtlMs + DRAIN_TIMINGS.watchdogGraceMs;
+		const beats = Math.max(1, Math.ceil((minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs));
+		return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs;
+	};
+	return {
+		async schedule(task) {
+			await sendTask(task);
+		},
+		handler(...servers) {
+			assertSchedulerTargets(servers, { allowStructural: true });
+			const byContract = /* @__PURE__ */ new Map();
+			for (const server of servers) byContract.set(server.contract.name, server);
+			return async (req) => {
+				return (await transport()).handleCallback(async (delivered) => {
+					const task = normalizeSchedulerTask(delivered);
+					if (!task) throw new TypeError("a2 scheduler received an invalid task");
+					const server = byContract.get(task.contract);
+					if (!server) throw new Error(`a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`);
+					const internals = serverInternals.get(server);
+					if (task.kind === "append") {
+						await deliverSchedulerAppend(server, task);
+						return;
+					}
+					const nextDueAt = successorDueAt(task);
+					const result = internals ? await internals.schedulerDrain(task.sessionId, { watchdogDueAt: nextDueAt }) : {
+						...await server.drain(task.sessionId),
+						outcome: "unknown"
+					};
+					if (result.settled) return;
+					if (result.outcome === "busy") {
+						if (result.schedulerArm) await result.schedulerArm;
+						else await sendTask({
+							version: 1,
+							kind: "drain",
+							contract: task.contract,
+							sessionId: task.sessionId,
+							dueAt: nextDueAt
+						});
+						return;
+					}
+					throw new DrainUnsettled(`a2 scheduler: session '${task.sessionId}' of '${task.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`);
+				})(req);
+			};
+		}
+	};
+}
+//#endregion
+export { DrainUnsettled, vercelQueues };
+
+//# sourceMappingURL=scheduler-vercel.js.map

package/dist/scheduler-vercel.js.map

@@ -0,0 +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 *   They target the publishing deployment unless explicitly configured\n *   as deploymentless. Drain tasks always remain deployment-scoped.\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  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\ntype VercelQueueMessage = SchedulerTask & {\n  /** Provider-private state used to address callback lease operations. */\n  _a2Vercel?: {\n    version: 1\n    deployment: 'deployment' | 'deploymentless'\n  }\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    /** Resolved A2 affinity. Custom transports own its provider mapping. */\n    routing?: {\n      deployment: 'deployment' | 'deploymentless'\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  /**\n   * Deployment affinity for scheduled append tasks. Recovery drain tasks\n   * always target the publishing deployment. Default `'deployment'`.\n   */\n  scheduledAppends?: 'deployment' | 'deploymentless'\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 (): 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 deploymentClient = new queue.QueueClient()\n  const deploymentlessClient = new queue.QueueClient({ deploymentId: null })\n  return {\n    send: (topic, message, options, routing) => {\n      const deployment = routing?.deployment ?? 'deployment'\n      const body: VercelQueueMessage = {\n        ...message,\n        _a2Vercel: { version: 1, deployment },\n      }\n      return (\n        deployment === 'deploymentless'\n          ? deploymentlessClient\n          : deploymentClient\n      ).send(topic, body, options)\n    },\n    handleCallback: (handler) => {\n      const callbackOptions = {\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: unknown, metadata: QueueDeliveryMetadata) =>\n          error instanceof DrainUnsettled\n            ? {\n                afterSeconds: unsettledBackoffSeconds(metadata.deliveryCount),\n              }\n            : undefined,\n      }\n      const deploymentHandler = deploymentClient.handleCallback(\n        handler,\n        callbackOptions,\n      ) as (req: Request) => Promise<Response>\n      const deploymentlessHandler = deploymentlessClient.handleCallback(\n        handler,\n        callbackOptions,\n      ) as (req: Request) => Promise<Response>\n      return async (req: Request): Promise<Response> => {\n        let delivered: unknown\n        try {\n          delivered = await req.clone().json()\n        } catch {\n          return deploymentlessHandler(req)\n        }\n        const metadata = recordOf(recordOf(delivered)?.['_a2Vercel'])\n        const routing =\n          metadata?.['version'] === 1 ? metadata['deployment'] : undefined\n        return routing === 'deployment'\n          ? deploymentHandler(req)\n          : deploymentlessHandler(req)\n      }\n    },\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 scheduledAppends = options.scheduledAppends ?? 'deployment'\n  if (\n    scheduledAppends !== 'deployment' &&\n    scheduledAppends !== 'deploymentless'\n  ) {\n    throw new TypeError(\n      \"vercelQueues() scheduledAppends must be 'deployment' or 'deploymentless'\",\n    )\n  }\n  const clock = options.clock ?? SYSTEM_CLOCK\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(),\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 === 'append' ? requestedDueAt : dueAt\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 deployment = task.kind === 'append' ? scheduledAppends : 'deployment'\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        : digestId(['a2:scheduler-vercel:append:v1', topic, task.id])\n    const t = await transport()\n    try {\n      await t.send(\n        topic,\n        message,\n        {\n          delaySeconds: deliveryDelaySeconds,\n          idempotencyKey,\n          retentionSeconds: MAX_RETENTION_SECONDS,\n        },\n        { deployment },\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, { allowStructural: true })\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 schedulerHandler(...)`,\n            )\n          }\n          const internals = serverInternals.get(server)\n          if (task.kind === 'append') {\n            await deliverSchedulerAppend(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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"}