experimental-a2 0.2.0 → 0.4.0

package/dist/http.js

@@ -1,20 +1,75 @@
-import { t as A2Error } from "./errors-BJRMd-h6.js";
-import { r as STREAM_TIMINGS } from "./internal-D6wNxTck.js";
-import { a as eventToWire, n as errorStatus, r as errorToWire, t as errorFromWire } from "./wire-BVsgR8o9.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { _ as schedulerForServer, c as STREAM_TIMINGS, d as assertServerSchedulerBindings, o as RESERVED_PARTICIPANT_IDS, s as SOCKET_TIMINGS, u as assertSchedulerTargets } from "./internal-aEotMzu_.js";
+import { t as invocationDeadlineMs } from "./platform-B4TnJtWu.js";
+import { _ as socketFrameFor, f as presencePatchToWire, g as socketErrorAckFor, h as socketAckFor, i as errorToWire, m as presenceSnapshotToWire, n as errorFromWire, o as eventToWire, r as errorStatus, t as SOCKET_PING_FRAME } from "./wire-DCUZBUlT.js";
 //#region src/http.ts
 /**
-* experimental-a2/http — route-side transport helpers (specs/a2-api.md §9–10).
+* experimental-a2/http — route-side transport helpers (specs/a2-api.md §9–10, §13).
 *
 * `sseResponse` pipes a `session.stream()` iterable into a server-sent
-* events Response; `parsePushBody` validates the push envelope;
+* events Response; `schedulerHandler` mounts servers on their configured
+* scheduler callback; `parsePushBody` validates the push envelope;
 * `errorResponse`/`deserializeError` are the A2Error wire pair the push
-* route and the client's `push` share.
+* route and the client's `push` share; `sessionSocket` speaks the same
+* lanes — stream down, push and presence up — over one WebSocket.
 */
 const invalid = (message) => new A2Error("INVALID_PAYLOAD", `malformed push body: ${message}`);
 /**
-* Validate the push envelope — `{ sessionId, events }` — throwing
-* `INVALID_PAYLOAD` on a malformed body. Payload validation against the
-* machine's schemas happens in `append`, not here.
+* Create one scheduler callback route for servers sharing the same configured
+* scheduler. Configuration mistakes throw immediately while the route module
+* is evaluated, before a delivery can be acknowledged by the wrong adapter.
+*/
+function schedulerHandler(firstServer, ...servers) {
+	if (firstServer === void 0) throw new TypeError("schedulerHandler() requires at least one A2 server");
+	const scheduler = schedulerForServer(firstServer);
+	const targets = [firstServer, ...servers];
+	assertSchedulerTargets(targets, { allowStructural: false });
+	assertServerSchedulerBindings(scheduler, targets);
+	return scheduler.handler(...targets);
+}
+function parsePresenceSibling(value) {
+	if (value === void 0) return void 0;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw invalid("presence must be an object when present");
+	const { participant, values, seen, at } = value;
+	if (typeof participant !== "string" || participant.length === 0) throw invalid("presence.participant must be a non-empty string");
+	if (RESERVED_PARTICIPANT_IDS.has(participant)) throw invalid(`presence.participant must not be '${participant}'`);
+	if (values === null || typeof values !== "object" || Array.isArray(values)) throw invalid("presence.values must be an object");
+	if (seen !== void 0 && (typeof seen !== "number" || !Number.isFinite(seen) || seen < 0)) throw invalid("presence.seen must be a non-negative number when present");
+	if (at !== void 0 && (typeof at !== "number" || !Number.isFinite(at) || at < 0 || at > 864e13)) throw invalid("presence.at must be a non-negative epoch-milliseconds timestamp within the Date range when present");
+	const out = {
+		participant,
+		values
+	};
+	if (seen !== void 0) out.seen = seen;
+	if (at !== void 0) out.at = at;
+	Object.defineProperty(out, "~a2.pushed", { value: true });
+	return out;
+}
+/** The events half of the envelope — shared verbatim by the POST body
+* and the socket's `push` frames, so the provenance brand and the
+* INVALID_PAYLOAD shapes are one implementation. */
+function parsePushEvents(events) {
+	if (!Array.isArray(events) || events.length === 0) throw invalid("events must be a non-empty array");
+	return events.map((event, i) => {
+		if (event === null || typeof event !== "object") throw invalid(`events[${i}] must be an object`);
+		const { type, payload, id } = event;
+		if (typeof type !== "string" || type.length === 0) throw invalid(`events[${i}].type must be a non-empty string`);
+		if (id !== void 0 && typeof id !== "string") throw invalid(`events[${i}].id must be a string when present`);
+		const out = {
+			type,
+			payload
+		};
+		if (id !== void 0) out.id = id;
+		Object.defineProperty(out, "~a2.pushed", { value: true });
+		return out;
+	});
+}
+/**
+* Validate the push envelope — `{ sessionId, events, presence? }` —
+* throwing `INVALID_PAYLOAD` on a malformed body. Payload validation
+* against the machine's schemas happens in `append` and `setPresence`,
+* not here. Either plane may appear alone: a presence-only push has no
+* (or empty) `events`.
 */
 async function parsePushBody(req) {
 	let body;
@@ -24,43 +79,57 @@ async function parsePushBody(req) {
 		throw new A2Error("INVALID_PAYLOAD", "push body is not valid JSON", { cause });
 	}
 	if (body === null || typeof body !== "object") throw invalid("expected an object");
-	const { sessionId, events } = body;
+	const { sessionId, events, presence } = body;
 	if (typeof sessionId !== "string" || sessionId.length === 0) throw invalid("sessionId must be a non-empty string");
-	if (!Array.isArray(events) || events.length === 0) throw invalid("events must be a non-empty array");
-	return {
+	const parsedPresence = parsePresenceSibling(presence);
+	if (parsedPresence !== void 0 && (events === void 0 || Array.isArray(events) && events.length === 0)) return {
+		sessionId,
+		events: [],
+		presence: parsedPresence
+	};
+	const parsed = parsePushEvents(events);
+	return parsedPresence !== void 0 ? {
+		sessionId,
+		events: parsed,
+		presence: parsedPresence
+	} : {
 		sessionId,
-		events: events.map((event, i) => {
-			if (event === null || typeof event !== "object") throw invalid(`events[${i}] must be an object`);
-			const { type, payload, id } = event;
-			if (typeof type !== "string" || type.length === 0) throw invalid(`events[${i}].type must be a non-empty string`);
-			if (id !== void 0 && typeof id !== "string") throw invalid(`events[${i}].id must be a string when present`);
-			const out = {
-				type,
-				payload
-			};
-			if (id !== void 0) out.id = id;
-			Object.defineProperty(out, "~a2.pushed", { value: true });
-			return out;
-		})
+		events: parsed
 	};
 }
 /**
 * Pipe a live event iterable into an SSE `Response`. Each event is one
-* frame — `id:` carries the log index, `data:` the JSON event. A
+* frame — `id:` carries the event-log index, `data:` the JSON event. A
+* `stream({ presence: true })` iterable also yields presence items,
+* which ride as named frames old clients skip: `event:
+* presence-snapshot` first (the map, ISO dates), then `event: presence`
+* per patch — no `id:`, presence never advances the resume frontier. A
 * disconnecting client cancels the stream, which closes the underlying
 * subscription. Two kinds of comment frames ride along: a `: connected`
 * prelude that flushes headers immediately, and a `: ping` heartbeat
 * every 15 seconds so clients (and proxies) can tell a quiet stream
 * from a dead connection — the session client's stall watchdog counts
-* on it.
+* on it. When the platform exposes an invocation deadline, the response
+* closes cleanly one second before it so the client reconnects without
+* a platform-timeout failure.
 */
 function sseResponse(iterable) {
 	const iterator = iterable[Symbol.asyncIterator]();
 	const encoder = new TextEncoder();
 	let heartbeat;
-	const stopHeartbeat = () => {
+	let deadlineTimer;
+	let closed = false;
+	let iteratorReturned = false;
+	const stopTimers = () => {
 		if (heartbeat !== void 0) clearInterval(heartbeat);
+		if (deadlineTimer !== void 0) clearTimeout(deadlineTimer);
 		heartbeat = void 0;
+		deadlineTimer = void 0;
+	};
+	const returnIterator = async () => {
+		if (iteratorReturned) return;
+		iteratorReturned = true;
+		await iterator.return?.();
 	};
 	const stream = new ReadableStream({
 		start(controller) {
@@ -69,23 +138,49 @@ function sseResponse(iterable) {
 				try {
 					controller.enqueue(encoder.encode(": ping\n\n"));
 				} catch {
-					stopHeartbeat();
+					stopTimers();
 				}
 			}, STREAM_TIMINGS.sseHeartbeatMs);
 			heartbeat.unref?.();
+			const invocationDeadline = invocationDeadlineMs();
+			if (invocationDeadline !== null) {
+				const delay = Math.max(0, invocationDeadline - Date.now() - STREAM_TIMINGS.sseDeadlineGraceMs);
+				deadlineTimer = setTimeout(() => {
+					if (closed) return;
+					closed = true;
+					stopTimers();
+					returnIterator().catch(() => {});
+					try {
+						controller.close();
+					} catch {}
+				}, delay);
+				deadlineTimer.unref?.();
+			}
 		},
 		async pull(controller) {
-			const { value, done } = await iterator.next();
-			if (done) {
-				stopHeartbeat();
-				controller.close();
-				return;
+			try {
+				const { value, done } = await iterator.next();
+				if (closed) return;
+				if (done) {
+					closed = true;
+					stopTimers();
+					controller.close();
+					return;
+				}
+				controller.enqueue(encoder.encode(frameFor(value)));
+			} catch (error) {
+				if (closed) return;
+				closed = true;
+				stopTimers();
+				returnIterator().catch(() => {});
+				throw error;
 			}
-			controller.enqueue(encoder.encode(`id: ${value.index}\ndata: ${JSON.stringify(eventToWire(value))}\n\n`));
 		},
 		async cancel() {
-			stopHeartbeat();
-			await iterator.return?.();
+			if (closed) return;
+			closed = true;
+			stopTimers();
+			await returnIterator();
 		}
 	});
 	return new Response(stream, {
@@ -97,17 +192,23 @@ function sseResponse(iterable) {
 		}
 	});
 }
+function frameFor(item) {
+	if ("snapshot" in item) return `event: presence-snapshot\ndata: ${JSON.stringify(presenceSnapshotToWire(item))}\n\n`;
+	if ("participant" in item) return `event: presence\ndata: ${JSON.stringify(presencePatchToWire(item))}\n\n`;
+	return `id: ${item.index}\ndata: ${JSON.stringify(eventToWire(item))}\n\n`;
+}
 /**
 * Serialize an error into the documented wire shape,
 * `{ error: { code, message, details } }`, with the mapped status
-* (400 for caller bugs, 503 for LOG_UNAVAILABLE). Non-A2Errors become a
-* 503 LOG_UNAVAILABLE — from the client's perspective an unknown server
+* (400 for caller bugs, 503 for STORE_UNAVAILABLE). Non-A2Errors become a
+* 503 STORE_UNAVAILABLE — from the client's perspective an unknown server
 * failure is retryable-once, not a protocol contract.
 */
 function errorResponse(error) {
-	const a2error = error instanceof A2Error ? error : new A2Error("LOG_UNAVAILABLE", "internal error", { cause: error });
+	const a2error = asA2Error(error);
 	return Response.json(errorToWire(a2error), { status: errorStatus(a2error.code) });
 }
+const asA2Error = (error) => error instanceof A2Error ? error : new A2Error("STORE_UNAVAILABLE", "internal error", { cause: error });
 /**
 * The other half of the wire pair: rebuild an `A2Error` from a response
 * body, or null if the body isn't one. Client `push` uses it so both
@@ -116,5 +217,165 @@ function errorResponse(error) {
 function deserializeError(body) {
 	return errorFromWire(body);
 }
+const messageText = (data) => {
+	if (typeof data === "string") return data;
+	if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+	if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data);
+	if (Array.isArray(data) && data.every(ArrayBuffer.isView)) {
+		const decoder = new TextDecoder();
+		let text = "";
+		for (const part of data) text += decoder.decode(part, { stream: true });
+		return text + decoder.decode();
+	}
+	return null;
+};
+/**
+* How many unparseable or invalid frames a socket may send before it
+* is closed (1008): the budget absorbs isolated client bugs without
+* letting a broken peer spin the validation path forever. Push frames
+* with a usable `req` never count — their failures are answered with
+* error acks, exactly like the POST path's 4xx bodies.
+*/
+const MAX_MALFORMED_FRAMES = 5;
+/**
+* Speak the A2 socket protocol (specs/a2-api.md §13) against one
+* session: the live stream pumps down as `kind`-framed JSON with a
+* `ping` heartbeat on the SSE cadence; `push` frames come up through
+* the same validation seams as `parsePushBody` (same provenance brand,
+* same `validatePush` calls, once per plane) and are answered with an
+* ack; `presence` frames are fire-and-forget. Socket close or error
+* tears the pump down and releases the store subscription; the stream
+* ending closes the socket.
+*/
+function sessionSocket(session, socket, options) {
+	const target = session;
+	const startAfter = options?.startAfter ?? 0;
+	const iterator = (options?.presence === true ? target.stream({
+		startAfter,
+		presence: true
+	}) : target.stream({ startAfter }))[Symbol.asyncIterator]();
+	let torn = false;
+	let malformed = 0;
+	let heartbeat;
+	let deadline;
+	const teardown = () => {
+		if (torn) return;
+		torn = true;
+		if (heartbeat !== void 0) clearInterval(heartbeat);
+		if (deadline !== void 0) clearTimeout(deadline);
+		iterator.return?.()?.catch(() => {});
+	};
+	const shutdown = (code, reason) => {
+		if (torn) return;
+		teardown();
+		try {
+			socket.close(code, reason);
+		} catch {}
+	};
+	const send = (data) => {
+		if (torn) return;
+		if (typeof socket.bufferedAmount === "number" && socket.bufferedAmount > SOCKET_TIMINGS.disconnectWaterMarkBytes) {
+			shutdown(1008, "backpressure: peer not reading");
+			return;
+		}
+		try {
+			socket.send(data);
+		} catch {
+			teardown();
+		}
+	};
+	const malformedFrame = (reason) => {
+		malformed += 1;
+		if (malformed >= MAX_MALFORMED_FRAMES) shutdown(1008, `too many malformed frames (last: ${reason})`);
+	};
+	const handlePush = async (frame) => {
+		const req = frame["req"];
+		if (typeof req !== "number") {
+			malformedFrame("push frame without a numeric req");
+			return;
+		}
+		try {
+			const events = parsePushEvents(frame["events"]);
+			const appended = await target.append(...events);
+			send(socketAckFor(req, appended));
+		} catch (err) {
+			send(socketErrorAckFor(req, asA2Error(err)));
+		}
+	};
+	const handlePresence = async (frame) => {
+		if (typeof target.setPresence !== "function") {
+			malformedFrame("presence frame on a presence-less session");
+			return;
+		}
+		try {
+			const patch = parsePresenceSibling(frame);
+			if (patch) await target.setPresence(patch);
+		} catch {
+			malformedFrame("invalid presence frame");
+		}
+	};
+	let inFlight = 0;
+	const track = (work) => {
+		inFlight += 1;
+		work.finally(() => {
+			inFlight -= 1;
+		});
+	};
+	const handleMessage = (data) => {
+		if (torn) return;
+		const text = messageText(data);
+		if (text === null) {
+			malformedFrame("non-text frame");
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			malformedFrame("frame is not valid JSON");
+			return;
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			malformedFrame("frame is not an object");
+			return;
+		}
+		const frame = parsed;
+		if (frame["kind"] === "push") {
+			if (inFlight >= SOCKET_TIMINGS.maxInFlightMessages) {
+				const req = frame["req"];
+				if (typeof req === "number") send(socketErrorAckFor(req, new A2Error("STORE_UNAVAILABLE", "push shed: too many in flight on this socket")));
+				else malformedFrame("push frame without a numeric req");
+				return;
+			}
+			track(handlePush(frame));
+		} else if (frame["kind"] === "presence") {
+			if (inFlight >= SOCKET_TIMINGS.maxInFlightMessages) return;
+			track(handlePresence(frame));
+		}
+	};
+	socket.on("message", handleMessage);
+	socket.on("close", teardown);
+	socket.on("error", teardown);
+	heartbeat = setInterval(() => send(SOCKET_PING_FRAME), STREAM_TIMINGS.sseHeartbeatMs);
+	heartbeat.unref?.();
+	if (options?.deadline !== void 0) {
+		deadline = setTimeout(() => shutdown(1e3, "deadline"), Math.max(0, options.deadline - Date.now()));
+		deadline.unref?.();
+	}
+	const buffered = () => typeof socket.bufferedAmount === "number" ? socket.bufferedAmount : 0;
+	const pump = async () => {
+		for (;;) {
+			for (;;) {
+				if (torn || buffered() <= SOCKET_TIMINGS.highWaterMarkBytes) break;
+				await new Promise((resolve) => setTimeout(resolve, SOCKET_TIMINGS.resumePollMs));
+			}
+			if (torn) return;
+			const { value, done } = await iterator.next();
+			if (done || torn) return;
+			send(socketFrameFor(value));
+		}
+	};
+	pump().then(() => shutdown(1e3), () => shutdown(1011, "stream failed"));
+}
 //#endregion
-export { deserializeError, errorResponse, parsePushBody, sseResponse };
+export { deserializeError, errorResponse, parsePushBody, schedulerHandler, sessionSocket, sseResponse };

package/dist/{idempotent-replay-BMyHrP0L.js → idempotent-replay-DuqEkYA7.js}

@@ -1,8 +1,8 @@
-import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
 //#region src/idempotent-replay.ts
 const canonicalJson = (value) => JSON.stringify(value, (_key, candidate) => {
 	if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) return candidate;
-	return Object.fromEntries(Object.entries(candidate).toSorted(([left], [right]) => left.localeCompare(right)));
+	return Object.fromEntries(Object.entries(candidate).toSorted(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
 }) ?? "null";
 const idempotentReplay = (events, existing) => {
 	const byId = new Map(existing.map((event) => [event.id, event]));

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as EventDefs, c as Reducer, i as EventBatchFactory, l as ReducerBuilder, n as Contract, o as ReducerOptions, r as ContractEvent, s as contract, t as AppendInput, u as StandardSchemaV1 } from "./contract-C_3dIIEU.js";
-import { a as Event } from "./log-ldf5g8Cx.js";
-import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-Cso0qyHQ.js";
-import { n as A2ErrorCode, t as A2Error } from "./errors-xL_JTXsY.js";
-export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };
+import { a as EventDefs, c as PresencePatch, f as contract, h as StandardSchemaV1, i as EventBatchFactory, l as PresenceSnapshot, m as ReducerBuilder, n as Contract, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput, u as ReducerOptions } from "./contract-jIfaR085.js";
+import { a as Event } from "./store-C3sNAaBT.js";
+import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-BjYHTfh2.js";
+import { n as A2ErrorCode, t as A2Error } from "./errors-W6nwJ-fm.js";
+export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceSnapshot, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { t as contract } from "./contract-CG_adnu_.js";
-import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { t as contract } from "./contract-48bUMgcL.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
 export { A2Error, contract };

package/dist/{inspection-E7qbD0Xj.js → inspection-DaxB5jM2.js}

@@ -1,4 +1,5 @@
 //#region src/inspection.ts
+var InspectionUnsupportedError = class extends Error {};
 const serverInspection = /* @__PURE__ */ new WeakMap();
 /** Owned live-inspection cadence; mutable only for white-box tests. */
 const DEVTOOLS_TIMINGS = {
@@ -7,4 +8,4 @@ const DEVTOOLS_TIMINGS = {
 	heartbeatMs: 15e3
 };
 //#endregion
-export { serverInspection as n, DEVTOOLS_TIMINGS as t };
+export { InspectionUnsupportedError as n, serverInspection as r, DEVTOOLS_TIMINGS as t };

package/dist/internal-aEotMzu_.js

@@ -0,0 +1,209 @@
+//#region src/internal.ts
+/**
+* A null-prototype record for maps keyed by caller-controlled strings
+* (participant ids, presence field names). On a normal object,
+* assigning to '__proto__' rewrites the prototype instead of creating
+* an own property — the prototype-pollution class. Null-prototype
+* objects still satisfy Record types and JSON.stringify cleanly.
+*/
+function nullProtoRecord() {
+	return Object.create(null);
+}
+/**
+* ECMA-262's maximum Date value (±8.64e15 ms). A presence stamp past
+* it becomes an Invalid Date whose toISOString throws — one hostile
+* stamp would poison every subscriber's snapshot frame — so both
+* seams bound `at` to the representable range.
+*/
+const MAX_DATE_MS = 864e13;
+/**
+* Participant ids that collide with Object.prototype plumbing.
+* Null-prototype construction already defuses them, but they are
+* rejected at both seams (`parsePushBody`, `setPresence`) so a hostile
+* id never propagates into userland maps either.
+*/
+const RESERVED_PARTICIPANT_IDS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const serverInternals = /* @__PURE__ */ new WeakMap();
+/** Scheduler configuration captured only for servers made by `createServer`. */
+const serverSchedulerBindings = /* @__PURE__ */ new WeakMap();
+const objectLike = (value) => typeof value === "object" && value !== null || typeof value === "function";
+const TOOL_SCOPE_STORAGE = Symbol.for("experimental-a2.ai.tool-scope");
+function ambientToolScopeStorage() {
+	const value = Reflect.get(globalThis, TOOL_SCOPE_STORAGE);
+	if (!objectLike(value) || typeof Reflect.get(value, "getStore") !== "function" || typeof Reflect.get(value, "run") !== "function") return;
+	return value;
+}
+function installAmbientToolScopeStorage(create) {
+	const existing = ambientToolScopeStorage();
+	if (existing !== void 0) return existing;
+	const storage = create();
+	Reflect.set(globalThis, TOOL_SCOPE_STORAGE, storage);
+	return storage;
+}
+const SCHEDULER_SEND_FAILURE = Symbol.for("experimental-a2.scheduler.send-failure");
+const schedulerSendFailureMarker = (value) => {
+	if (!objectLike(value)) return void 0;
+	const marker = Reflect.get(value, SCHEDULER_SEND_FAILURE);
+	if (!objectLike(marker) || Reflect.get(marker, "version") !== 1 || !Array.isArray(Reflect.get(marker, "pending")) || !Array.isArray(Reflect.get(marker, "active"))) return;
+	return marker;
+};
+const schedulerFailureObject = (error) => {
+	if (objectLike(error) && (schedulerSendFailureMarker(error) !== void 0 || Object.isExtensible(error))) return error;
+	return new Error(String(error), { cause: error });
+};
+const schedulerSendFailureState = (error) => {
+	const existing = schedulerSendFailureMarker(error);
+	if (existing !== void 0) return existing;
+	const marker = {
+		version: 1,
+		pending: [],
+		active: []
+	};
+	Object.defineProperty(error, SCHEDULER_SEND_FAILURE, {
+		value: marker,
+		enumerable: false,
+		configurable: true,
+		writable: false
+	});
+	return marker;
+};
+const clearSchedulerSendFailureState = (error, marker) => {
+	if (marker.pending.length === 0 && marker.active.length === 0) Reflect.deleteProperty(error, SCHEDULER_SEND_FAILURE);
+};
+/**
+* Classify an adapter error before throwing it. Unclassified adapter failures
+* are retryable because the caller cannot know whether a remote send landed.
+*/
+function classifySchedulerSendFailure(error, disposition) {
+	const classified = schedulerFailureObject(error);
+	schedulerSendFailureState(classified).pending.push(disposition);
+	return classified;
+}
+/** Consume a pending adapter classification and count this rejected send. */
+function markSchedulerSendFailure(error) {
+	const marked = schedulerFailureObject(error);
+	const marker = schedulerSendFailureState(marked);
+	marker.active.push(marker.pending.pop() ?? "retryable");
+	return marked;
+}
+function consumeSchedulerSendFailure(error) {
+	if (!objectLike(error)) return void 0;
+	const marker = schedulerSendFailureMarker(error);
+	const disposition = marker?.active.pop();
+	if (marker !== void 0) clearSchedulerSendFailureState(error, marker);
+	return disposition;
+}
+const isDrainableServer = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	const contract = Reflect.get(value, "contract");
+	return contract !== null && typeof contract === "object" && typeof Reflect.get(contract, "name") === "string" && typeof Reflect.get(value, "drain") === "function";
+};
+/**
+* Validate the server list captured by a scheduler route at construction time.
+* Built-in adapters keep their low-level target seam structural for custom
+* integrations. The application-facing `schedulerHandler` uses strict mode
+* so only servers made by this A2 copy reach a configured adapter.
+*/
+function assertSchedulerTargets(servers, options) {
+	const contracts = /* @__PURE__ */ new Set();
+	for (const target of servers) {
+		if (!isDrainableServer(target)) throw new TypeError("a2 scheduler: expected a server from createServer()");
+		const name = target.contract.name;
+		if (contracts.has(name)) throw new TypeError(`a2 scheduler: duplicate server contract '${name}' in one handler`);
+		contracts.add(name);
+		if (!serverSchedulerBindings.get(target)) {
+			if (!options.allowStructural) throw new TypeError(`a2 scheduler: server for contract '${name}' was not created by createServer()`);
+			continue;
+		}
+	}
+}
+/** Require every real server to share one exact configured scheduler. */
+function assertServerSchedulerBindings(scheduler, servers) {
+	for (const server of servers) {
+		const binding = serverSchedulerBindings.get(server);
+		if (!binding?.scheduler) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`);
+		if (binding.scheduler !== scheduler) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' is configured with a different scheduler instance`);
+	}
+}
+/** Resolve the scheduler privately bound to a real A2 server. */
+function schedulerForServer(server) {
+	if (!isDrainableServer(server)) throw new TypeError("a2 scheduler: expected a server from createServer()");
+	const binding = serverSchedulerBindings.get(server);
+	if (!binding) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' was not created by createServer()`);
+	if (!binding.scheduler) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`);
+	return binding.scheduler;
+}
+/**
+* Drain timing knobs. Mutable only as a white-box test seam. Claim
+* heartbeats run on real timers, so tests shrink these to keep suites
+* fast. Production always uses the defaults.
+*/
+const DRAIN_TIMINGS = {
+	claimTtlMs: 5e3,
+	claimHeartbeatMs: 2e3,
+	renewRetryMs: 400,
+	watchdogGraceMs: 1e3,
+	schedulerArmTimeoutMs: 2e3
+};
+/**
+* Stream liveness knobs — the server-side SSE heartbeat and the
+* client-side stall watchdog. Paired by design: the client declares a
+* connection dead after roughly two missed heartbeats. Mutable only as
+* a white-box test seam; production always uses the defaults.
+*/
+/**
+* Poll cadence for the poll-based store streams (sqlite, postgres) —
+* owned, not configurable: adaptive polling removed the operator's
+* reason to tune it (the floor keeps active streams smooth; the
+* ceiling bounds idle cost). Mutable only as a white-box test seam so
+* suites don't wait out real idle gaps.
+*/
+const POLL_TIMINGS = {
+	activeFloorMs: 25,
+	idleCeilingMs: 250
+};
+/**
+* Safety-read cadence for the notify-driven redis live stream. A
+* parked feed re-reads the store at this interval even without a
+* pub/sub wake-up, so a lost notification (subscriber reconnect gap,
+* dropped PUBLISH) costs latency, never an event. Mutable only as a
+* white-box test seam.
+*/
+const NOTIFY_TIMINGS = { safetyReadMs: 1e4 };
+const STREAM_TIMINGS = {
+	sseHeartbeatMs: 15e3,
+	sseDeadlineGraceMs: 1e3,
+	stallTimeoutMs: 35e3,
+	reconnectBaseMs: 500,
+	reconnectMaxMs: 5e3
+};
+/**
+* WebSocket down-pump backpressure — `sessionSocket` parks its pull
+* loop while the socket reports more buffered bytes than the
+* high-water mark and re-checks on the poll cadence, so a slow reader
+* applies backpressure to the store subscription instead of buffering
+* without bound in the socket. Acks and heartbeats stay exempt: they
+* are small and correctness-relevant. Mutable only as a white-box test
+* seam.
+*/
+const SOCKET_TIMINGS = {
+	highWaterMarkBytes: 1048576,
+	resumePollMs: 25,
+	maxInFlightMessages: 32,
+	disconnectWaterMarkBytes: 8388608
+};
+/**
+* Client presence send cadence — a leading send immediately, then at
+* most one merged send per interval (~15Hz). Owned, not configurable
+* (decision #36's rule): coupling the cadence to the POST ack tied
+* remote cursor smoothness to RTT, and the ack serves no correctness
+* purpose on a fire-and-forget LWW plane. Mutable only as a white-box
+* test seam.
+*/
+const PRESENCE_TIMINGS = { sendIntervalMs: 66 };
+//#endregion
+export { schedulerForServer as _, PRESENCE_TIMINGS as a, STREAM_TIMINGS as c, assertServerSchedulerBindings as d, classifySchedulerSendFailure as f, nullProtoRecord as g, markSchedulerSendFailure as h, POLL_TIMINGS as i, ambientToolScopeStorage as l, installAmbientToolScopeStorage as m, MAX_DATE_MS as n, RESERVED_PARTICIPANT_IDS as o, consumeSchedulerSendFailure as p, NOTIFY_TIMINGS as r, SOCKET_TIMINGS as s, DRAIN_TIMINGS as t, assertSchedulerTargets as u, serverInternals as v, serverSchedulerBindings as y };

package/dist/otel.d.ts

@@ -1,4 +1,4 @@
-import { i as A2Telemetry } from "./telemetry-Cso0qyHQ.js";
+import { i as A2Telemetry } from "./telemetry-BjYHTfh2.js";
 import { Tracer } from "@opentelemetry/api";
 //#region src/otel.d.ts
 type OtelOptions = {