experimental-a2 0.2.0 → 0.4.0

package/dist/scheduler-qstash.js

@@ -0,0 +1,499 @@
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { f as classifySchedulerSendFailure, t as DRAIN_TIMINGS, u as assertSchedulerTargets, v as serverInternals } from "./internal-aEotMzu_.js";
+import { n as deliverSchedulerAppend } from "./server-CcNnFnoW.js";
+import { n as platformVercelOidcToken } from "./platform-B4TnJtWu.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";
+//#region src/scheduler-qstash.ts
+/**
+* experimental-a2/scheduler-qstash — HTTP scheduler over Upstash QStash.
+*
+* QStash publishes one signed HTTP delivery per scheduler task. Drain tasks
+* use an absolute, whole-second `notBefore` and a fixed-size deduplication id;
+* append tasks hash their stable task id with the callback URL.
+* Store-outage successors carry a signed private generation and back off to
+* one day without deriving their deduplication identity from the local clock.
+* `handler(...servers)` verifies the signature over the raw request body
+* before parsing it, then applies the same drain protocol as the Vercel
+* scheduler adapter.
+*
+* `@upstash/qstash` is an optional peer dependency, imported lazily. The
+* structural `transport` option keeps its types out of A2's public surface and
+* gives tests a provider-faithful injection seam.
+*/
+const qstashTransport = async (options, developmentMode) => {
+	const sdk = await import("@upstash/qstash").catch(() => {
+		throw classifySchedulerSendFailure(/* @__PURE__ */ new Error("experimental-a2/scheduler-qstash needs the '@upstash/qstash' package (optional peer dependency) — install it, or inject a transport"), "terminal");
+	});
+	const developmentOverride = developmentMode === void 0 ? {} : { devMode: developmentMode };
+	const client = options.client ?? new sdk.Client({
+		...options.token === void 0 ? {} : { token: options.token },
+		...developmentOverride
+	});
+	const receiver = new sdk.Receiver({
+		...options.currentSigningKey === void 0 ? {} : { currentSigningKey: options.currentSigningKey },
+		...options.nextSigningKey === void 0 ? {} : { nextSigningKey: options.nextSigningKey },
+		...developmentOverride
+	});
+	return {
+		publish: (request) => {
+			const clientRequest = {
+				url: request.url,
+				body: request.body,
+				...request.headers === void 0 ? {} : { headers: { ...request.headers } },
+				...request.redact === void 0 ? {} : { redact: { header: [...request.redact.header] } },
+				deduplicationId: request.deduplicationId,
+				...request.retries === void 0 ? {} : { retries: request.retries },
+				...request.notBefore === void 0 ? {} : { notBefore: request.notBefore }
+			};
+			return client.publishJSON(clientRequest);
+		},
+		verify: (request) => receiver.verify(request)
+	};
+};
+const digestId = async (parts) => {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(parts)));
+	return `a2_${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+};
+const recordOf = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+const TRUSTED_SOURCE_HEADER = "x-vercel-trusted-oidc-idp-token";
+const TRUSTED_SOURCE_DELIVERY_MARGIN_MS = 6e4;
+const RESERVED_CALLBACK_HEADERS = /* @__PURE__ */ new Set([
+	"connection",
+	"content-length",
+	"host",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade",
+	"x-vercel-oidc-token",
+	TRUSTED_SOURCE_HEADER
+]);
+const callbackHeaders = (value) => {
+	if (value === void 0) return void 0;
+	let entries;
+	try {
+		entries = Object.entries(value);
+	} catch {
+		throw new TypeError("qstash() headers must be an HTTP header record");
+	}
+	const normalized = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [name, headerValue] of entries) {
+		if (typeof headerValue !== "string") throw new TypeError("qstash() header values must be strings");
+		let entry;
+		try {
+			entry = [...new Headers([[name, headerValue]]).entries()][0];
+		} catch {
+			throw new TypeError("qstash() headers must contain valid HTTP header names and values");
+		}
+		if (entry === void 0) throw new TypeError("qstash() headers must contain valid HTTP header names and values");
+		const [normalizedName, normalizedValue] = entry;
+		if (seen.has(normalizedName)) throw new TypeError(`qstash() headers contain duplicate name '${normalizedName}'`);
+		if (normalizedName.startsWith("upstash-") || normalizedName.startsWith("content-type") || RESERVED_CALLBACK_HEADERS.has(normalizedName)) throw new TypeError(`qstash() headers cannot set reserved header '${normalizedName}'`);
+		seen.add(normalizedName);
+		normalized.push([normalizedName, normalizedValue]);
+	}
+	return normalized.length === 0 ? void 0 : Object.freeze(Object.fromEntries(normalized));
+};
+const publishHeaders = (configured, generated) => {
+	if (configured === void 0 && generated === void 0) return void 0;
+	const headers = new Headers();
+	const redacted = /* @__PURE__ */ new Set();
+	for (const [name, value] of Object.entries(configured ?? {})) {
+		headers.set(name, value);
+		redacted.add(name);
+	}
+	for (const [name, value] of Object.entries(generated?.headers ?? {})) {
+		headers.set(name, value);
+		redacted.add(name);
+	}
+	for (const name of generated?.redact?.header ?? []) {
+		const normalized = [...new Headers([[name, "redacted"]]).keys()][0];
+		if (normalized === void 0) throw new TypeError("qstash generated an invalid redaction header");
+		redacted.add(normalized);
+	}
+	const headerEntries = [...headers.entries()];
+	return {
+		...headerEntries.length === 0 ? {} : { headers: Object.fromEntries(headerEntries) },
+		...redacted.size === 0 ? {} : { redact: { header: [...redacted].toSorted() } }
+	};
+};
+const jwtExpirationMs = (token) => {
+	const parts = token.split(".");
+	const payloadPart = parts.length === 3 ? parts[1] : void 0;
+	if (payloadPart === void 0 || payloadPart.length === 0 || !/^[A-Za-z0-9_-]+$/.test(payloadPart) || payloadPart.length % 4 === 1) return null;
+	try {
+		const decode = globalThis.atob;
+		if (typeof decode !== "function") return null;
+		const binary = decode(payloadPart.replaceAll("-", "+").replaceAll("_", "/").padEnd(payloadPart.length + (4 - payloadPart.length % 4) % 4, "="));
+		const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+		const expiration = recordOf(JSON.parse(new TextDecoder().decode(bytes)))?.["exp"];
+		if (typeof expiration !== "number" || !Number.isSafeInteger(expiration) || expiration <= 0 || expiration > Number.MAX_SAFE_INTEGER / 1e3) return null;
+		return expiration * 1e3;
+	} catch {
+		return null;
+	}
+};
+const previewTrustedSource = (firstDeliveryAt) => {
+	const token = platformVercelOidcToken();
+	if (token === null) return void 0;
+	const expiration = jwtExpirationMs(token);
+	if (expiration === null || firstDeliveryAt + TRUSTED_SOURCE_DELIVERY_MARGIN_MS > expiration) return;
+	return {
+		headers: { [TRUSTED_SOURCE_HEADER]: token },
+		redact: { header: [TRUSTED_SOURCE_HEADER] }
+	};
+};
+const RETRYABLE_HTTP_CLIENT_STATUSES = /* @__PURE__ */ new Set([
+	408,
+	409,
+	425,
+	429
+]);
+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 classifyQStashPublishFailure = (error) => {
+	const status = httpStatusOf(error);
+	const terminal = status !== void 0 && status >= 400 && status < 500 && !RETRYABLE_HTTP_CLIENT_STATUSES.has(status);
+	return classifySchedulerSendFailure(error, terminal ? "terminal" : "retryable");
+};
+const parseTask = (body) => {
+	let value;
+	try {
+		value = JSON.parse(body);
+	} catch {
+		return null;
+	}
+	const task = normalizeSchedulerTask(value);
+	const record = recordOf(value);
+	if (!task || !record) return null;
+	const encodedOutage = record["_a2QStash"];
+	if (encodedOutage === void 0) return { task };
+	const outage = recordOf(encodedOutage);
+	const generation = outage?.["generation"];
+	if (!outage || outage["version"] !== 1 || typeof generation !== "number" || !Number.isSafeInteger(generation) || generation < 0 || generation >= Number.MAX_SAFE_INTEGER) return null;
+	const rootDueAt = outage["rootDueAt"];
+	if (task.kind === "drain") {
+		if (typeof rootDueAt !== "number" || !Number.isInteger(rootDueAt) || rootDueAt % 1e3 !== 0) return null;
+	} else if (rootDueAt !== void 0) return null;
+	return {
+		task,
+		outage: {
+			version: 1,
+			generation,
+			...rootDueAt === void 0 ? {} : { rootDueAt }
+		}
+	};
+};
+const DEFAULT_MAX_BODY_BYTES = 1048576;
+const STORE_OUTAGE_BASE_DELAY_MS = 3e4;
+const STORE_OUTAGE_MAX_DELAY_MS = 864e5;
+const readBoundedBody = async (request, maxBytes) => {
+	const declared = request.headers.get("content-length");
+	if (declared !== null && /^\d+$/.test(declared) && Number(declared) > maxBytes) return null;
+	if (request.body === null) return "";
+	const reader = request.body.getReader();
+	const chunks = [];
+	let length = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			length += value.byteLength;
+			if (length > maxBytes) {
+				await reader.cancel().catch(() => {});
+				return null;
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const bytes = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(bytes);
+};
+const storeUnavailable = (error) => error instanceof A2Error && error.code === "STORE_UNAVAILABLE";
+const response = {
+	ok: () => new Response("ok"),
+	unauthorized: () => new Response("unauthorized", { status: 401 }),
+	malformed: () => new Response("invalid a2 scheduler message", {
+		status: 489,
+		headers: { "Upstash-NonRetryable-Error": "true" }
+	}),
+	tooLarge: () => new Response("a2 scheduler message is too large", {
+		status: 489,
+		headers: { "Upstash-NonRetryable-Error": "true" }
+	})
+};
+const CALLBACK_PATH = "/api/a2/scheduler";
+const DEFAULT_DEVELOPMENT_PORT = 3e3;
+const developmentCallbackUrl = (portValue) => {
+	const port = portValue === void 0 || portValue === "" ? DEFAULT_DEVELOPMENT_PORT : Number(portValue);
+	if (!Number.isSafeInteger(port) || port < 1 || port > 65535 || portValue !== void 0 && portValue !== "" && !/^\d+$/.test(portValue)) throw new TypeError("qstash() could not infer url: PORT must be an integer from 1 to 65535 for local development");
+	return `http://localhost:${String(port)}${CALLBACK_PATH}`;
+};
+const inferCallbackUrl = () => {
+	const env = typeof process === "undefined" ? void 0 : process.env;
+	const vercelEnv = env?.["VERCEL_ENV"];
+	const variable = env?.["VERCEL"] !== "1" ? null : vercelEnv === "production" ? "VERCEL_PROJECT_PRODUCTION_URL" : vercelEnv === "preview" ? "VERCEL_BRANCH_URL" : null;
+	if (variable !== null) {
+		const host = env?.[variable];
+		if (!host) throw new TypeError(`qstash() could not infer url: ${variable} is missing`);
+		let origin;
+		try {
+			origin = new URL(`https://${host}`);
+		} catch {
+			throw new TypeError(`qstash() could not infer url: ${variable} must be a hostname`);
+		}
+		if (origin.host !== host || origin.pathname !== "/" || origin.search !== "" || origin.hash !== "" || origin.username !== "" || origin.password !== "" || origin.port !== "") throw new TypeError(`qstash() could not infer url: ${variable} must be a hostname`);
+		return {
+			callbackUrl: new URL(CALLBACK_PATH, origin).toString(),
+			developmentMode: false,
+			...vercelEnv === "preview" ? { inferredVercelPreview: true } : {}
+		};
+	}
+	if (env === void 0) throw new TypeError("qstash() needs url when the runtime cannot identify local development");
+	if (env["NODE_ENV"] === "production") throw new TypeError("qstash() needs url in production outside a Vercel production or preview deployment");
+	return {
+		callbackUrl: developmentCallbackUrl(env["PORT"]),
+		developmentMode: true
+	};
+};
+function qstash(options = {}) {
+	const env = typeof process === "undefined" ? void 0 : process.env;
+	const { callbackUrl, developmentMode, inferredVercelPreview } = options.url === void 0 ? inferCallbackUrl() : {
+		callbackUrl: options.url,
+		...env?.["NODE_ENV"] === "production" ? { developmentMode: false } : {}
+	};
+	let parsedUrl;
+	try {
+		parsedUrl = new URL(callbackUrl);
+	} catch {
+		throw new TypeError("qstash() needs an absolute callback url");
+	}
+	if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") throw new TypeError("qstash() callback url must use http or https");
+	if (options.client !== void 0 && options.transport !== void 0) throw new TypeError("qstash() cannot combine client and transport");
+	if (options.client !== void 0 && options.token !== void 0) throw new TypeError("qstash() cannot combine client and token");
+	const url = parsedUrl.toString();
+	const configuredHeaders = callbackHeaders(options.headers);
+	const { retries } = options;
+	if (retries !== void 0 && (!Number.isSafeInteger(retries) || retries < 0)) throw new TypeError("qstash() retries must be a non-negative integer");
+	const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+	if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1) throw new TypeError("qstash() maxBodyBytes must be a positive integer");
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const transport = retryableLazy(() => options.transport ? Promise.resolve(options.transport) : qstashTransport(options, developmentMode)).get;
+	const storeOutageDeduplicationId = (task, outage) => {
+		if (task.kind === "append") return digestId([
+			"a2:scheduler-qstash:store-outage:append:v1",
+			url,
+			task.contract,
+			task.sessionId,
+			task.id,
+			outage.generation
+		]);
+		const { rootDueAt } = outage;
+		if (rootDueAt === void 0) throw new TypeError("qstash store-outage drain needs a root dueAt");
+		return digestId([
+			"a2:scheduler-qstash:store-outage:drain:v1",
+			url,
+			task.contract,
+			task.sessionId,
+			rootDueAt,
+			outage.generation
+		]);
+	};
+	const sendTask = async (task, outage) => {
+		const nowMs = clock.now().getTime();
+		const requestedDueAt = task.dueAt;
+		if (!Number.isFinite(requestedDueAt)) throw classifySchedulerSendFailure(/* @__PURE__ */ new TypeError("qstash scheduler dueAt must be a finite number"), "terminal");
+		const dueAt = requestedDueAt <= nowMs ? Math.floor(nowMs / 1e3) * 1e3 : Math.ceil(requestedDueAt / 1e3) * 1e3;
+		const normalizedTask = task.kind === "append" ? {
+			version: 1,
+			kind: "append",
+			id: task.id,
+			contract: task.contract,
+			sessionId: task.sessionId,
+			dueAt,
+			events: task.events
+		} : {
+			version: 1,
+			kind: "drain",
+			contract: task.contract,
+			sessionId: task.sessionId,
+			dueAt
+		};
+		const message = {
+			...normalizedTask,
+			...outage === void 0 ? {} : { _a2QStash: outage }
+		};
+		const sizeCheckedMessage = outage === void 0 ? {
+			...normalizedTask,
+			_a2QStash: normalizedTask.kind === "append" ? {
+				version: 1,
+				generation: Number.MAX_SAFE_INTEGER
+			} : {
+				version: 1,
+				generation: Number.MAX_SAFE_INTEGER,
+				rootDueAt: dueAt
+			}
+		} : message;
+		let bodyBytes;
+		try {
+			bodyBytes = new TextEncoder().encode(JSON.stringify(sizeCheckedMessage)).byteLength;
+		} catch (error) {
+			throw classifySchedulerSendFailure(error, "terminal");
+		}
+		if (bodyBytes > maxBodyBytes) throw classifySchedulerSendFailure(/* @__PURE__ */ new RangeError("qstash scheduler message exceeds maxBodyBytes"), "terminal");
+		const deduplicationId = outage !== void 0 ? await storeOutageDeduplicationId(task, outage) : task.kind === "append" ? await digestId([
+			"a2:scheduler-qstash:append:v1",
+			url,
+			task.id
+		]) : await digestId([
+			"a2:scheduler-qstash:v1",
+			url,
+			task.contract,
+			task.sessionId,
+			dueAt
+		]);
+		const trustedSource = inferredVercelPreview === true ? previewTrustedSource(Math.max(nowMs, dueAt)) : void 0;
+		const deliveryHeaders = publishHeaders(configuredHeaders, trustedSource);
+		const t = await transport();
+		try {
+			await t.publish({
+				url,
+				body: message,
+				...deliveryHeaders,
+				...dueAt <= nowMs ? {} : { notBefore: dueAt / 1e3 },
+				deduplicationId,
+				...retries === void 0 ? {} : { retries }
+			});
+		} catch (error) {
+			throw classifyQStashPublishFailure(error);
+		}
+	};
+	const sendStoreOutageSuccessor = async (task, outage) => {
+		const generation = (outage?.generation ?? -1) + 1;
+		const delayMs = Math.min(STORE_OUTAGE_MAX_DELAY_MS, STORE_OUTAGE_BASE_DELAY_MS * 4 ** Math.min(generation, 6));
+		const nowMs = clock.now().getTime();
+		const dueAt = Math.ceil((nowMs + delayMs) / 1e3) * 1e3;
+		const nextOutage = task.kind === "append" ? {
+			version: 1,
+			generation
+		} : {
+			version: 1,
+			generation,
+			rootDueAt: outage?.rootDueAt ?? task.dueAt
+		};
+		await sendTask({
+			...task,
+			dueAt
+		}, nextOutage);
+	};
+	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) => {
+				const signature = req.headers.get("upstash-signature");
+				if (!signature) return response.unauthorized();
+				const body = await readBoundedBody(req, maxBodyBytes);
+				if (body === null) return response.tooLarge();
+				const upstashRegion = req.headers.get("upstash-region");
+				const t = await transport();
+				try {
+					if (!await t.verify({
+						signature,
+						body,
+						url,
+						...upstashRegion === null ? {} : { upstashRegion }
+					})) return response.unauthorized();
+				} catch {
+					return response.unauthorized();
+				}
+				const parsed = parseTask(body);
+				if (!parsed) return response.malformed();
+				const { task, outage } = parsed;
+				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") {
+					try {
+						await deliverSchedulerAppend(server, task);
+					} catch (error) {
+						if (!storeUnavailable(error)) throw error;
+						await sendStoreOutageSuccessor(task, outage);
+					}
+					return response.ok();
+				}
+				const nextDueAt = successorDueAt(task);
+				let result;
+				try {
+					result = internals ? await internals.schedulerDrain(task.sessionId, { watchdogDueAt: nextDueAt }) : {
+						...await server.drain(task.sessionId),
+						outcome: "unknown"
+					};
+				} catch (error) {
+					if (!storeUnavailable(error)) throw error;
+					await sendStoreOutageSuccessor(task, outage);
+					return response.ok();
+				}
+				if (result.settled) return response.ok();
+				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 response.ok();
+				}
+				await sendTask({
+					version: 1,
+					kind: "drain",
+					contract: task.contract,
+					sessionId: task.sessionId,
+					dueAt: nextDueAt
+				});
+				return response.ok();
+			};
+		}
+	};
+}
+//#endregion
+export { qstash };

package/dist/scheduler-task-BpzhPnRS.js

@@ -0,0 +1,54 @@
+//#region src/scheduler-task.ts
+const recordOf = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+const validName = (value) => typeof value === "string" && value.length > 0;
+const validDueAt = (value) => typeof value === "number" && Number.isInteger(value) && value % 1e3 === 0;
+const baseTask = (record) => Object.hasOwn(record, "contract") && Object.hasOwn(record, "sessionId") && validName(record["contract"]) && validName(record["sessionId"]) ? {
+	contract: record["contract"],
+	sessionId: record["sessionId"]
+} : null;
+/**
+* Validate one delivered task.
+* Adapters call this only after their transport authentication has succeeded.
+*/
+function normalizeSchedulerTask(value) {
+	const record = recordOf(value);
+	if (!record) return null;
+	const base = baseTask(record);
+	if (!base) return null;
+	if (record["version"] !== 1) return null;
+	if (record["kind"] === "drain") {
+		const dueAt = record["dueAt"];
+		if (!validDueAt(dueAt)) return null;
+		return {
+			version: 1,
+			kind: "drain",
+			...base,
+			dueAt
+		};
+	}
+	if (record["kind"] !== "append") return null;
+	const { dueAt, events, id } = record;
+	if (!validName(id) || !validDueAt(dueAt)) return null;
+	if (!Array.isArray(events) || events.length === 0) return null;
+	const parsedEvents = [];
+	for (const event of events) {
+		const item = recordOf(event);
+		if (!item || typeof item["id"] !== "string" || typeof item["type"] !== "string" || !Object.hasOwn(item, "payload")) return null;
+		parsedEvents.push({
+			id: item["id"],
+			type: item["type"],
+			payload: item["payload"]
+		});
+	}
+	if (new Set(parsedEvents.map((event) => event.id)).size !== parsedEvents.length) return null;
+	return {
+		version: 1,
+		kind: "append",
+		id,
+		...base,
+		dueAt,
+		events: parsedEvents
+	};
+}
+//#endregion
+export { normalizeSchedulerTask as t };

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-C3sNAaBT.js";
+import { D as SchedulerTask, t as A2Scheduler } from "./server-YtPq7hjw.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,44 @@ 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 };