@acid-cat/core-ts 0.10.0 → 0.10.2

package/README.md

@@ -78,6 +78,7 @@ export const aircon = defineApp<{ unit: Unit }>({ targets, capabilities: [powerS
 ## Write the catalog
 
 ```ts
+import { writeFile } from "node:fs/promises";
 import { renderCatalog } from "@acid-cat/core-ts";
 
 const toJsonSchema = (schema) => z.toJSONSchema(schema, { target: "draft-2020-12" });
@@ -248,7 +249,7 @@ for await (const occurrence of await status.subscribe({})) {
 }
 ```
 
-- The promise of `subscribe` resolves when the subscription has started. Before that, it rejects with a `CallFailureError`: `unknown-capability` for an event that the session does not serve, `invalid-input` for an input that does not agree with the schema, and `cancelled` when the session closes or the signal aborts.
+- The promise of `subscribe` resolves when the subscription has started. Before that, it rejects with a `CallFailureError`: `unknown-capability` for an event that the session does not serve, `invalid-input` for an input that does not agree with the schema or a `maxAgeMs` that is not an integer of 0 or more, and `cancelled` when the session closes or the signal aborts.
 - The result is an async iterator of occurrences: `eventId`, `name`, `timestamp`, `data`, and `cursor` and `truncated` if they are present. `return()` cancels the subscription, also while a `next()` waits: that `next()` resolves with `done: true`. `await using` also cancels it at the end of the block.
 - The options are `signal`, `cursor` and `maxAgeMs`.
 - When the session closes, each subscription is complete. With `internal`, `next()` rejects with a `CallFailureError`, then resolves with `done: true`.
@@ -274,7 +275,7 @@ const handler = httpHandler(aircon, {
 
 ### Command line
 
-The command line has one command for each capability in the view of the `cli` target. Each top-level property of the input is a flag with the same name, for example `--celsius 22` or `--celsius=22`. A boolean property is a switch, for example `--on`. A property with an array of strings, numbers or values of a string enum is a repeated flag: each occurrence gives one item, in the order of the flags. A repeated flag that occurs once can also give the whole array as JSON text. Other properties take JSON text. For example, with the command line of the air conditioner, [`examples/aircon/core-ts/cli.ts`](../../examples/aircon/core-ts/cli.ts):
+The command line has one command for each capability in the view of the `cli` target. The words of the id give the path of the command. A shared prefix only contains other commands: if the path of a capability is the start of the path of another capability, for example `aircon.status` and `aircon.status.get`, `runCli` rejects and `cliMain` stops the program with an error when it starts. Each top-level property of the input is a flag with the same name, for example `--celsius 22` or `--celsius=22`. A boolean property is a switch, for example `--on`. A property with an array of strings, numbers or values of a string enum is a repeated flag: each occurrence gives one item, in the order of the flags. A repeated flag that occurs once can also give the whole array as JSON text. Other properties take JSON text. For example, with the command line of the air conditioner, [`examples/aircon/core-ts/cli.ts`](../../examples/aircon/core-ts/cli.ts):
 
 ```sh
 node cli.ts aircon temperature set --celsius 22

package/dist/app.js

@@ -1,6 +1,6 @@
 import { canonicalText } from "@acid-cat/catalog";
 import { isJsonObject, objectInput } from "@acid-cat/spec-ts";
-//#region src/app.ts
+// src/app.ts
 /**
 * Capabilities and applications in plain TypeScript. An application writes its own catalog.
 * See spec/catalog.md.
@@ -127,5 +127,4 @@ function write(app, toJsonSchema) {
 }
 /** The catalog of an application, as text in canonical form. */
 const renderCatalog = (app, options) => canonicalText(catalogOf(app, options));
-//#endregion
 export { capabilitiesFor, catalogOf, defineApp, defineCapability, defineEvent, eventsFor, renderCatalog };

package/dist/cli.js

@@ -1,6 +1,6 @@
 import { createSession } from "./session.js";
 import { CLI_EXIT_CODES, CLI_RESUME_FLAGS, CLI_WATCH_EXIT_CODES, CallFailureError, bundle, cliEventUsage, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
-//#region src/cli.ts
+// src/cli.ts
 /**
 * The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
 */
@@ -42,6 +42,10 @@ async function runCli(app, options, args, io) {
 		path: commandPath(id)
 	}));
 	for (const { path } of commands) if (path[0] !== void 0 && GENERIC_COMMANDS.includes(path[0])) throw new Error(`The command ${path.join(" ")} has the same name as a command of the command line.`);
+	for (const { path } of commands) {
+		const longer = commands.find((other) => other.path.length > path.length && path.every((word, index) => other.path[index] === word));
+		if (longer !== void 0) throw new Error(`The command ${path.join(" ")} is also the start of the command ${longer.path.join(" ")}. A shared prefix only contains other commands.`);
+	}
 	for (const [id, event] of Object.entries(session.view.events ?? {})) {
 		const properties = event.input === void 0 ? void 0 : bundle(event.input, types).properties;
 		const taken = CLI_RESUME_FLAGS.find((flag) => isJsonObject(properties) && flag in properties);
@@ -293,5 +297,4 @@ function usage(name, path, description, schema) {
 		description
 	].join("\n");
 }
-//#endregion
 export { main, runCli };

package/dist/clock.js

@@ -1,4 +1,4 @@
-//#region src/clock.ts
+// src/clock.ts
 /** The clock of the system: `Date.now` and `setTimeout`. */
 const systemClock = {
 	now: () => Date.now(),
@@ -22,5 +22,4 @@ function sleep(clock, ms, signal) {
 		signal.addEventListener("abort", stop, { once: true });
 	});
 }
-//#endregion
 export { sleep, systemClock };

package/dist/context.js

@@ -1,4 +1,4 @@
-//#region src/context.ts
+// src/context.ts
 /**
 * The context of one request, and the function that releases it if the handler made it. A response with a stream, such
 * as the stream of a subscription, releases the context when the stream ends.
@@ -24,5 +24,4 @@ async function release(value) {
 }
 /** Tell if a value is a function. A function can take any arguments, and its result is not known. */
 const isFunction = (value) => typeof value === "function";
-//#endregion
 export { openContext };

package/dist/http.js

@@ -1,8 +1,8 @@
-import { createSession } from "./session.js";
 import { openContext } from "./context.js";
+import { createSession } from "./session.js";
 import { idlePuller, textStream } from "./stream.js";
 import { CallFailureError, KEEPALIVE_MS, SSE_MEDIA_TYPE, callFailure, httpEventMessage, httpStatus, isCallFailure, readBounded, screenRequest } from "@acid-cat/spec-ts";
-//#region src/http.ts
+// src/http.ts
 /**
 * The HTTP binding (spec/bindings/http.md): JSON through HTTP.
 */
@@ -42,13 +42,15 @@ function httpHandler(app, options) {
 			if (request.method === "GET" && path === "/catalog" && options.serveCatalog !== false) return json(200, session.view);
 			const route = request.method === "POST" ? postRoute(path) : void 0;
 			if (route === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
+			const id = decodedId(route.id);
+			if (id === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
 			let input;
 			try {
 				input = body.text === "" ? {} : JSON.parse(body.text);
 			} catch {
-				return json(422, callFailure("invalid-input", "The request body is not JSON."));
+				const failure = notJson(session, route.kind, id, request.signal);
+				return json(httpStatus(failure), failureBody(failure));
 			}
-			const id = decodeURIComponent(route.id);
 			if (route.kind === "capability") {
 				const outcome = await session.invoke(id, input, { signal: request.signal });
 				return json(httpStatus(outcome), isCallFailure(outcome) ? failureBody(outcome) : outcome);
@@ -75,17 +77,38 @@ function postRoute(path) {
 		id: path.slice(8)
 	};
 }
+/** The id of a route with its escapes decoded, or `undefined` if an escape is malformed, as in `%E0`. */
+function decodedId(encoded) {
+	try {
+		return decodeURIComponent(encoded);
+	} catch {
+		return;
+	}
+}
+/**
+* The call failure of a request whose body is not JSON. The kinds before `invalid-input` apply first
+* (spec/invocation.md#call-failures, spec/events.md#subscribing): `cancelled`, `unknown-capability`, then `unavailable`
+* for a capability.
+*/
+function notJson(session, kind, id, signal) {
+	if (session.signal.aborted || signal.aborted) return callFailure("cancelled", "The call was cancelled.");
+	if (kind === "event") {
+		if (!session.eventHandles.has(id)) return callFailure("unknown-capability", `There is no event ${id}.`);
+	} else {
+		const handle = session.handles.get(id);
+		if (handle === void 0) return callFailure("unknown-capability", `There is no capability ${id}.`);
+		const availability = handle.availability.getSnapshot();
+		if (!availability.available) return callFailure("unavailable", availability.reason);
+	}
+	return callFailure("invalid-input", "The request body is not JSON.");
+}
 /**
 * Subscribe to an event (spec/bindings/http.md#events). A call failure before the first occurrence is a JSON answer.
 * After that, the answer is a stream of server-sent events, which closes the session when it ends.
 */
 async function subscribe(session, id, input, url, request, stream) {
 	const maxAge = url.searchParams.get("maxAgeMs");
-	const maxAgeMs = maxAge === null ? void 0 : Number(maxAge);
-	if (maxAgeMs !== void 0 && (maxAge?.trim() === "" || !Number.isInteger(maxAgeMs) || maxAgeMs < 0)) return {
-		response: json(422, callFailure("invalid-input", "maxAgeMs must be a whole number of milliseconds.")),
-		streaming: false
-	};
+	const maxAgeMs = maxAge === null ? void 0 : /^[0-9]+$/.test(maxAge) ? Number(maxAge) : NaN;
 	const cursor = request.headers.get("Last-Event-ID") ?? void 0;
 	const subscribed = await session.subscribe(id, input, {
 		signal: request.signal,
@@ -151,5 +174,4 @@ function rejection(reason) {
 		headers
 	});
 }
-//#endregion
 export { httpHandler };

package/dist/index.js

@@ -1,8 +1,8 @@
 import { capabilitiesFor, catalogOf, defineApp, defineCapability, defineEvent, eventsFor, renderCatalog } from "./app.js";
-import { DEFAULT_BUFFER_LIMIT } from "./subscription.js";
 import { createSession } from "./session.js";
-import { systemClock } from "./clock.js";
+import { DEFAULT_BUFFER_LIMIT } from "./subscription.js";
 import { mcpHandler } from "./mcp.js";
+import { systemClock } from "./clock.js";
 import { main as main$1, runMcpStdio } from "./mcp-stdio.js";
 import { httpHandler } from "./http.js";
 import { main, runCli } from "./cli.js";

package/dist/mcp-events.d.ts

@@ -51,6 +51,9 @@ export declare const invalidParams: (message: string) => {
 /**
  * Read the subscription parameters (spec/bindings/mcp.md#events): the id, the input, the cursor and `maxAgeMs`. An
  * absent cursor and a `null` cursor are the same. The input is `{}` when `arguments` is absent.
+ *
+ * This function does not check `maxAgeMs`: an unknown id comes before an invalid `maxAgeMs` (spec/events.md#subscribing),
+ * so the session checks it after the id. A `maxAgeMs` that is not a number is `NaN`, which the session rejects.
  */
 export declare function subscriptionParams(params: JsonObject): {
     readonly error: JsonRpcError;

package/dist/mcp-events.js

@@ -1,6 +1,6 @@
 import { idlePuller } from "./stream.js";
 import { CallFailureError, MCP_EVENTS_EXTENSION, MCP_EVENT_ERRORS, MCP_SUBSCRIPTION_ID, bundle, mcpEventEntry, mcpEventParams, mcpSubscribeError } from "@acid-cat/spec-ts";
-//#region src/mcp-events.ts
+// src/mcp-events.ts
 /**
 * Events through MCP (spec/bindings/mcp.md#events): the MCP events extension. This module serves push delivery, and
 * declares the parts that poll and webhook delivery share. The HTTP and the stdio transports share these functions.
@@ -36,16 +36,18 @@ const invalidParams = (message) => ({ error: {
 /**
 * Read the subscription parameters (spec/bindings/mcp.md#events): the id, the input, the cursor and `maxAgeMs`. An
 * absent cursor and a `null` cursor are the same. The input is `{}` when `arguments` is absent.
+*
+* This function does not check `maxAgeMs`: an unknown id comes before an invalid `maxAgeMs` (spec/events.md#subscribing),
+* so the session checks it after the id. A `maxAgeMs` that is not a number is `NaN`, which the session rejects.
 */
 function subscriptionParams(params) {
 	const { name, arguments: input, cursor, maxAgeMs } = params;
 	if (cursor !== void 0 && cursor !== null && typeof cursor !== "string") return invalidParams("cursor must be a string or null.");
-	if (maxAgeMs !== void 0 && maxAgeMs !== null && (typeof maxAgeMs !== "number" || !Number.isFinite(maxAgeMs) || maxAgeMs < 0)) return invalidParams("maxAgeMs must be a number of milliseconds.");
 	return {
 		name: typeof name === "string" ? name : "",
 		input: input ?? {},
 		cursor: typeof cursor === "string" ? cursor : void 0,
-		maxAgeMs: typeof maxAgeMs === "number" ? maxAgeMs : void 0
+		maxAgeMs: maxAgeMs === void 0 || maxAgeMs === null ? void 0 : typeof maxAgeMs === "number" ? maxAgeMs : NaN
 	};
 }
 /** The message of the call failure that ends a subscription. A subscription ends only with `internal`. */
@@ -125,5 +127,4 @@ async function startEventStream(session, id, params, settings) {
 		cancel: () => void subscribed.return()
 	};
 }
-//#endregion
 export { endMessage, eventCapabilities, forbidden, invalidParams, listEvents, servesEvents, startEventStream, subscriptionParams, unsupportedWebhook };

package/dist/mcp-poll.js

@@ -1,7 +1,8 @@
-import { endMessage, invalidParams, subscriptionParams } from "./mcp-events.js";
 import { systemClock } from "./clock.js";
+import { endMessage, invalidParams, subscriptionParams } from "./mcp-events.js";
+import { isMaxAgeMs } from "./session.js";
 import { MCP_EVENT_ERRORS, MCP_POLL_DEFAULTS, canonicalJson, decodePollCursor, encodePollCursor, mcpSubscribeError } from "@acid-cat/spec-ts";
-//#region src/mcp-poll.ts
+// src/mcp-poll.ts
 /**
 * Poll delivery through MCP (spec/bindings/mcp.md#poll): `events/poll` reads the occurrences of a poll lease. A lease
 * holds one subscription, in a session of its own, and a buffer of its occurrences. The HTTP and the stdio transports
@@ -55,12 +56,14 @@ var PollLeases = class {
 		const position = read.cursor === void 0 ? void 0 : decodePollCursor(read.cursor);
 		if (lease === void 0) {
 			const provider = read.cursor === void 0 ? void 0 : position?.provider;
-			const started = this.#start(key, read.name, read.input, provider, provider === void 0 ? void 0 : read.maxAgeMs, open);
+			const maxAgeMs = provider === void 0 && isMaxAgeMs(read.maxAgeMs) ? void 0 : read.maxAgeMs;
+			const started = this.#start(key, read.name, read.input, provider, maxAgeMs, open);
 			this.#starting.set(key, started);
 			const answer = await started.finally(() => this.#starting.delete(key));
 			if ("error" in answer) return answer;
 			return this.#result([], this.#cursorOf(answer, 0), read.cursor !== void 0 && provider === void 0, false);
 		}
+		if (!isMaxAgeMs(read.maxAgeMs)) return invalidParams("maxAgeMs must be an integer that is 0 or more.");
 		this.#renew(lease);
 		if (read.cursor === void 0) return this.#result([], this.#cursorOf(lease, lease.newest), false, false);
 		if (position?.lease === lease.id) return this.#read(lease, position.position, maxEvents, read.cursor);
@@ -175,5 +178,4 @@ function withoutTruncated(occurrence) {
 	const { truncated: _, ...rest } = occurrence;
 	return { ...rest };
 }
-//#endregion
 export { PollLeases };

package/dist/mcp-stdio.js

@@ -1,9 +1,9 @@
-import { createSession } from "./session.js";
+import { hasObjectOutput, listTools } from "./mcp.js";
 import { eventCapabilities, listEvents, servesEvents, startEventStream, unsupportedWebhook } from "./mcp-events.js";
 import { PollLeases } from "./mcp-poll.js";
-import { hasObjectOutput, listTools } from "./mcp.js";
+import { createSession } from "./session.js";
 import { KEEPALIVE_MS, MCP_PROTOCOL_VERSION, MCP_UNKNOWN_TOOL, isJsonObject, mcpToolResult } from "@acid-cat/spec-ts";
-//#region src/mcp-stdio.ts
+// src/mcp-stdio.ts
 /**
 * The MCP binding through standard input and standard output (spec/bindings/mcp.md#stdio). The process is one session.
 * The server serves revision 2026-07-28, and the `initialize` handshake of revisions 2025-11-25 and 2025-06-18.
@@ -321,5 +321,4 @@ var StdioServer = class {
 		this.#write(`${JSON.stringify(message)}\n`);
 	}
 };
-//#endregion
 export { main, runMcpStdio };

package/dist/mcp.js

@@ -1,10 +1,10 @@
-import { createSession } from "./session.js";
 import { openContext } from "./context.js";
-import { textStream } from "./stream.js";
 import { eventCapabilities, forbidden, listEvents, servesEvents, startEventStream, unsupportedWebhook } from "./mcp-events.js";
 import { PollLeases } from "./mcp-poll.js";
+import { createSession } from "./session.js";
+import { textStream } from "./stream.js";
 import { KEEPALIVE_MS, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, SSE_MEDIA_TYPE, bundle, isJsonObject, mcpToolResult, readBounded, screenRequest, sseMessage } from "@acid-cat/spec-ts";
-//#region src/mcp.ts
+// src/mcp.ts
 /**
 * The MCP binding (spec/bindings/mcp.md): an MCP server through HTTP, revision 2026-07-28. The server keeps no state
 * between requests, except poll leases and webhook subscriptions.
@@ -253,5 +253,4 @@ const messages = {
 	"too-large": "The request body is too large.",
 	"not-utf8": "The request body is not UTF-8 JSON."
 };
-//#endregion
 export { hasObjectOutput, listTools, mcpHandler };

package/dist/node.js

@@ -1,6 +1,6 @@
 import { webhookDelivery } from "./webhook.js";
 import { createServer } from "node:http";
-//#region src/node.ts
+// src/node.ts
 /**
 * The functions that need Node.js. The main entry point, `@acid-cat/core-ts`, works in all runtimes.
 *
@@ -172,5 +172,4 @@ function bodyOf(incoming) {
 		}
 	}, { highWaterMark: 0 });
 }
-//#endregion
 export { serve, webhookDelivery };

package/dist/session.d.ts

@@ -123,5 +123,10 @@ export interface SessionOptions<Context> {
      */
     readonly bufferLimit?: number | undefined;
 }
+/**
+ * True if `maxAgeMs` is absent, or an integer that is 0 or more (spec/events.md#resuming). A session rejects another
+ * value as `invalid-input`, after it checks the id of the event.
+ */
+export declare const isMaxAgeMs: (maxAgeMs: number | undefined) => boolean;
 /** Open a session for a target. */
 export declare function createSession<Context>(app: App<Context>, options: SessionOptions<Context>): Session<Context>;

package/dist/session.js

@@ -1,7 +1,7 @@
 import { catalogOf } from "./app.js";
 import { runSubscription } from "./subscription.js";
 import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from "@acid-cat/spec-ts";
-//#region src/session.ts
+// src/session.ts
 /**
 * Sessions and handles (spec/invocation.md, spec/bindings/typescript.md).
 */
@@ -36,6 +36,11 @@ function outsideView(capability) {
 		invokeExternal: reject
 	};
 }
+/**
+* True if `maxAgeMs` is absent, or an integer that is 0 or more (spec/events.md#resuming). A session rejects another
+* value as `invalid-input`, after it checks the id of the event.
+*/
+const isMaxAgeMs = (maxAgeMs) => maxAgeMs === void 0 || Number.isSafeInteger(maxAgeMs) && maxAgeMs >= 0;
 const always = {
 	getSnapshot: () => AVAILABLE,
 	subscribe: () => ({ unsubscribe() {} })
@@ -65,7 +70,13 @@ function createSession(app, options) {
 		if (lifetime.signal.aborted || signal?.aborted) return callFailure("cancelled", "The call was cancelled.");
 		const availability = entry.availability.getSnapshot();
 		if (!availability.available) return callFailure("unavailable", availability.reason);
-		const prepared = await prepare();
+		let prepared;
+		try {
+			prepared = await prepare();
+		} catch (cause) {
+			onDefect(id, cause);
+			return callFailure("internal", "The capability failed.");
+		}
 		if ("issues" in prepared) return callFailure("invalid-input", issueMessage(prepared.issues));
 		const controller = new AbortController();
 		const abort = () => controller.abort();
@@ -172,6 +183,7 @@ function createSession(app, options) {
 		const { signal } = subscribeOptions;
 		const cancelled = () => lifetime.signal.aborted || signal?.aborted === true;
 		if (cancelled()) return callFailure("cancelled", "The subscription was cancelled.");
+		if (!isMaxAgeMs(subscribeOptions.maxAgeMs)) return callFailure("invalid-input", "maxAgeMs must be an integer that is 0 or more.");
 		let prepared;
 		try {
 			prepared = await prepare();
@@ -379,5 +391,4 @@ async function checkFailure(failure, tag, schemas) {
 		...checked.value
 	};
 }
-//#endregion
-export { createSession };
+export { createSession, isMaxAgeMs };

package/dist/stream.js

@@ -1,4 +1,4 @@
-//#region src/stream.ts
+// src/stream.ts
 /**
 * A function that pulls the next step of a subscription. It gives `idle` when no step comes within `idleMs`
 * milliseconds. The `next()` that waits is kept for the next pull, so no occurrence is lost.
@@ -59,5 +59,4 @@ function textStream(produce, cancel, release) {
 		}
 	}, { highWaterMark: 0 });
 }
-//#endregion
 export { idlePuller, textStream };

package/dist/subscription.js

@@ -1,5 +1,5 @@
 import { CallFailureError, callFailure, occurrenceOf } from "@acid-cat/spec-ts";
-//#region src/subscription.ts
+// src/subscription.ts
 /**
 * One subscription (spec/events.md): the pump that reads the occurrences of the provider, the bounded buffer for a slow
 * client, and the iterator that the client reads.
@@ -141,5 +141,4 @@ function checkEmitted(value) {
 	if (truncated !== void 0 && truncated !== true) throw new TypeError("The truncated member of an occurrence is not true.");
 	return value;
 }
-//#endregion
 export { DEFAULT_BUFFER_LIMIT, runSubscription };

package/dist/webhook.js

@@ -1,12 +1,13 @@
-import { endMessage, invalidParams, subscriptionParams } from "./mcp-events.js";
 import { sleep, systemClock } from "./clock.js";
+import { endMessage, invalidParams, subscriptionParams } from "./mcp-events.js";
+import { isMaxAgeMs } from "./session.js";
 import { MCP_EVENT_ERRORS, MCP_WEBHOOK_DEFAULTS, canonicalJson, isGloballyRoutable, isJsonObject, mcpSubscribeError, webhookGrantMs, webhookSecretBytes, webhookSignature, webhookSubscriptionId } from "@acid-cat/spec-ts";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { lookup } from "node:dns";
 import { request } from "node:https";
 import { isIP } from "node:net";
 import { rootCertificates } from "node:tls";
-//#region src/webhook.ts
+// src/webhook.ts
 /**
 * Webhook delivery through MCP (spec/bindings/mcp.md#webhook), on Node.js. The server sends the occurrences of each
 * webhook subscription in HTTP `POST` requests to a URL of the client, signed as Standard Webhooks specifies.
@@ -139,6 +140,7 @@ function webhookDelivery(options = {}) {
 			secrets: [secret]
 		}, webhookIdOf("verification"), body), body, network);
 		if ("failure" in posted) return posted.failure;
+		if (posted.status >= 300 && posted.status < 400) return "challenge_failed";
 		if (posted.status < 200 || posted.status >= 300) return statusError(posted.status);
 		if (!sameText(challengeOf(posted.text), challenge)) return "challenge_failed";
 		verified.add(pair);
@@ -164,7 +166,7 @@ function webhookDelivery(options = {}) {
 				max: settings.maxSubscriptions
 			}
 		} };
-		const id = await webhookSubscriptionId(principal, url.href, request.name, request.input);
+		const id = await webhookSubscriptionId(principal, request.rawUrl, request.name, request.input);
 		const own = await open();
 		const subscribed = await own.session.subscribe(request.name, request.input, {
 			...request.cursor === void 0 ? {} : { cursor: request.cursor },
@@ -207,15 +209,11 @@ function webhookDelivery(options = {}) {
 			const read = readSubscribe(params);
 			if ("error" in read) return read;
 			const { url, secret } = read;
-			const key = canonicalJson([
-				principal,
-				url.href,
-				read.name,
-				read.input
-			]);
+			const key = subscriptionKey(principal, read.rawUrl, read.name, read.input);
 			await starting.get(key);
 			const existing = subscriptions.get(key);
 			if (existing !== void 0) {
+				if (!isMaxAgeMs(read.maxAgeMs)) return invalidParams("maxAgeMs must be an integer that is 0 or more.");
 				if (existing.secret !== secret) {
 					existing.previous = {
 						secret: existing.secret,
@@ -234,13 +232,7 @@ function webhookDelivery(options = {}) {
 			const { name, arguments: input = {}, delivery } = params;
 			const url = isJsonObject(delivery) ? delivery["url"] : void 0;
 			if (typeof name !== "string" || typeof url !== "string") return Promise.resolve(invalidParams("events/unsubscribe needs name and delivery.url."));
-			const parsed = URL.canParse(url) ? new URL(url).href : url;
-			const subscription = subscriptions.get(canonicalJson([
-				principal,
-				parsed,
-				name,
-				input
-			]));
+			const subscription = subscriptions.get(subscriptionKey(principal, url, name, input));
 			if (subscription === void 0) return Promise.resolve({ error: {
 				code: MCP_EVENT_ERRORS.notFound,
 				message: "There is no such subscription.",
@@ -256,6 +248,13 @@ function webhookDelivery(options = {}) {
 		}
 	};
 }
+/** The key of a webhook subscription: the principal, `delivery.url` as the client sent it, the id, and the input. */
+const subscriptionKey = (principal, rawUrl, name, input) => canonicalJson([
+	principal,
+	rawUrl,
+	name,
+	input
+]);
 /** Read and check the parameters of `events/subscribe`. */
 function readSubscribe(params) {
 	const read = subscriptionParams(params);
@@ -270,6 +269,7 @@ function readSubscribe(params) {
 		...read,
 		ttlMs,
 		url: new URL(url),
+		rawUrl: url,
 		secret
 	};
 }
@@ -381,5 +381,4 @@ function failureOf(error) {
 	if (/^(ERR_TLS|ERR_SSL|CERT_|UNABLE_TO_|DEPTH_ZERO|SELF_SIGNED|HOSTNAME_MISMATCH)/.test(code) || /certificate|SSL|TLS/i.test(error.message)) return "tls_error";
 	return "connection_refused";
 }
-//#endregion
 export { webhookDelivery };

package/dist/webmcp.js

@@ -1,5 +1,5 @@
 import { CallFailureError, bundle, isCallFailure } from "@acid-cat/spec-ts";
-//#region src/webmcp.ts
+// src/webmcp.ts
 /**
 * The WebMCP binding (spec/bindings/webmcp.md): register capabilities as WebMCP tools in a web page.
 */
@@ -136,5 +136,4 @@ function installWebMcp(session, options = {}) {
 		}
 	};
 }
-//#endregion
 export { findHost, installWebMcp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Serve AcidCat capabilities and events in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
@@ -36,16 +36,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.10.0",
-    "@acid-cat/mcp-handshake": "0.10.0",
-    "@acid-cat/spec-ts": "0.10.0"
+    "@acid-cat/catalog": "0.10.2",
+    "@acid-cat/mcp-handshake": "0.10.2",
+    "@acid-cat/spec-ts": "0.10.2"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.10.0",
-    "@types/node": "26.6.5",
+    "@acid-cat/cli": "0.10.2",
+    "@types/node": "26.6.6",
     "esbuild": "0.28.2",
-    "graphql": "17.0.2",
-    "playwright": "1.64.0",
+    "graphql": "17.1.0",
+    "playwright": "1.65.0",
     "typescript": "7.0.2",
     "zod": "4.6.7"
   }