@try-works/dsh-model-as-tool 0.1.2 → 0.3.6

package/lib/mcp/server.js

@@ -53,15 +53,44 @@ export async function dispatch(request, host, options = {}) {
         negotiateVersion(metadata);
         // Capabilities the CLIENT requires. A requirement this server cannot meet is
         // -32021 rather than a silent partial service.
+        const wiring = { subscriptions: options.subscriptions !== undefined };
         const required = requiredCapabilities(metadata.clientCapabilities);
-        const unsupported = unsupportedRequiredCapabilities(required);
+        const unsupported = unsupportedRequiredCapabilities(required, wiring);
         if (unsupported.length > 0) {
-            throw new WireError(ERROR_CODES.unsupportedClientCapability, `the client requires unsupported capability: ${unsupported.join(', ')}`, { unsupported });
+            throw new WireError(ERROR_CODES.unsupportedClientCapability, `the client requires unsupported capability: ${unsupported.join(', ')}`, 
+            /**
+             * THE PINNED SCHEMA'S OWN FIELD NAME, and this was WRONG.
+             *
+             * `MissingRequiredClientCapabilityError` REQUIRES `data.requiredCapabilities`. This
+             * sent `{ unsupported: [...] }`, which Ajv rejects against the pinned definition:
+             *
+             *   INVALID -> /error/data must have required property 'requiredCapabilities'
+             *
+             * It went unnoticed because the GENERIC `JSONRPCErrorResponse` accepts ANY `data`,
+             * every fixture took that path, and no fixture covered `-32021` at all — so the
+             * conformance suite validated a shape the specific error definition forbids.
+             * P26-03 requires `-32021` "and the schema-defined data"; this is that shape.
+             */
+            /**
+             * A `ClientCapabilities` OBJECT, not an array of names — and this was STILL wrong.
+             *
+             * The previous correction fixed the FIELD NAME (`unsupported` -> `requiredCapabilities`)
+             * and left the VALUE as an array of strings. The pinned definition is precise:
+             *
+             *     requiredCapabilities -> $ref ClientCapabilities  (type: object)
+             *
+             * so the shape is `{ sampling: {} }`, a capabilities object keyed by capability name.
+             * Both defects are the same kind — a plausible shape that no fixture covered — and this
+             * one survived the first fix because only a LIVE response validated against the pinned
+             * definition could distinguish an array from an object. The fixture probe never saw it,
+             * and no test asserted the value's TYPE.
+             */
+            { requiredCapabilities: Object.fromEntries(unsupported.map(name => [name, {}])) });
         }
         switch (request.method) {
             case 'server/discover':
                 return {
-                    response: { jsonrpc: '2.0', id, result: successResult(discoverResult(), host.serverInfo) },
+                    response: { jsonrpc: '2.0', id, result: successResult(discoverResult(wiring), host.serverInfo) },
                     httpStatus: 200,
                 };
             case 'tools/list':
@@ -72,7 +101,15 @@ export async function dispatch(request, host, options = {}) {
                         result: successResult({
                             // Deterministic ordering (MCP-06): the caller sees a stable list, so
                             // a client diffing two listings does not see spurious changes.
+                            //
+                            // SEC-04: an AUTHENTICATED external caller sees only its GRANTED
+                            // tools — the list is the client's authorized set, not the operator's
+                            // whole surface. The grant stays the AUTHORITY: calling a
+                            // non-granted tool still yields the grant refusal, this only
+                            // narrows what a client is shown. The caller-less path (stdio /
+                            // native) sees the full surface.
                             tools: [...host.listTools()]
+                                .filter(tool => options.caller === undefined || options.caller.allowedTools.includes(tool.name))
                                 .sort((left, right) => left.name.localeCompare(right.name))
                                 .map(toMcpTool),
                             // Required by the schema's CacheableResult; omitting them makes the
@@ -101,7 +138,7 @@ export async function dispatch(request, host, options = {}) {
                 };
             }
             case 'tools/call':
-                return await callTool(request, id, host, options.signal ?? new AbortController().signal);
+                return await callTool(request, id, host, options.signal ?? new AbortController().signal, options.caller);
             default:
                 throw new WireError(ERROR_CODES.methodNotFound, `unknown method ${JSON.stringify(request.method)}`);
         }
@@ -114,13 +151,43 @@ export async function dispatch(request, host, options = {}) {
         // payload (MCP-10), so it leaves as a JSON-RPC error.
         return {
             response: errorResponse(id, wire),
-            // Header problems are a transport-level rejection as well as a JSON-RPC error.
-            httpStatus: wire.code === ERROR_CODES.headerMismatch || wire.code === ERROR_CODES.invalidParams ? 400 : 200,
+            /**
+             * THE PINNED SCHEMA'S OWN `MUST`, read from the schema rather than inferred.
+             *
+             * Three error definitions state it in as many words — "For HTTP, the response status
+             * code MUST be `400 Bad Request`":
+             *
+             *   HeaderMismatchError                  -> -32020
+             *   MissingRequiredClientCapabilityError -> -32021
+             *   UnsupportedProtocolVersionError      -> -32022
+             *
+             * Only the FIRST and `invalidParams` were mapped to 400, so a client requiring an
+             * unsupported capability — or presenting an unsupported protocol version — received an
+             * error body under a 200 status. The suite stayed green either way, so the status was
+             * untested in BOTH directions.
+             *
+             * Kept as a named SET so the next transport-level rejection is a one-line addition
+             * rather than another condition somebody can forget.
+             */
+            httpStatus: TRANSPORT_LEVEL_REJECTIONS.has(wire.code) ? 400 : 200,
         };
     }
 }
+/**
+ * The JSON-RPC codes the pinned schema requires be answered with HTTP 400 as well.
+ *
+ * Every one of these definitions says, verbatim: "For HTTP, the response status code MUST
+ * be `400 Bad Request`." Kept as a named set so the rule lives in ONE place and the next
+ * transport-level rejection is an addition rather than another forgotten condition.
+ */
+const TRANSPORT_LEVEL_REJECTIONS = new Set([
+    ERROR_CODES.headerMismatch, // -32020
+    ERROR_CODES.unsupportedClientCapability, // -32021
+    ERROR_CODES.unsupportedProtocolVersion, // -32022
+    ERROR_CODES.invalidParams, // -32602, a malformed request shape
+]);
 /** Handle `tools/call`. */
-async function callTool(request, id, host, signal) {
+async function callTool(request, id, host, signal, caller) {
     const name = request.params?.name;
     if (typeof name !== 'string' || name.length === 0) {
         throw new WireError(ERROR_CODES.invalidParams, 'tools/call requires params.name');
@@ -140,7 +207,7 @@ async function callTool(request, id, host, signal) {
     if (definition.importedFromMcp) {
         throw new WireError(ERROR_CODES.invalidParams, `tool ${JSON.stringify(name)} was imported from MCP and is not re-exported`);
     }
-    const outcome = await host.callTool(name, (args ?? {}), signal);
+    const outcome = await host.callTool(name, (args ?? {}), signal, caller);
     const result = outcome.isError === true
         // An application failure is a tool-error RESULT (P26-04), so the protocol
         // exchange still succeeded.
@@ -156,13 +223,13 @@ async function callTool(request, id, host, signal) {
     };
 }
 /** The `server/discover` result, in the shape the pinned schema requires. */
-function discoverResult() {
+function discoverResult(wiring = {}) {
     return {
         // `supportedVersions` is the field the schema defines; there is no
         // `protocolVersion` on a DiscoverResult, which is the mistake pinning the schema
         // caught. A client learns the versions the server speaks, not one it picked.
         supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
-        capabilities: serverCapabilities(),
+        capabilities: serverCapabilities(wiring),
         ...cacheableResultFields(),
     };
 }
@@ -174,10 +241,10 @@ function discoverResult() {
  * advertised only when it is genuinely implemented.
  * @returns the `ServerCapabilities` object.
  */
-function serverCapabilities() {
-    const implemented = new Set(implementedCapabilities());
+function serverCapabilities(wiring = {}) {
+    const implemented = new Set(implementedCapabilities(wiring));
     return {
-        ...implemented.has('tools') ? { tools: {} } : {},
+        ...implemented.has('tools') ? { tools: { listChanged: implemented.has('subscriptions/listen') } } : {},
         ...implemented.has('prompts') ? { prompts: {} } : {},
         ...implemented.has('resources/subscribe') ? { resources: {} } : {},
         ...implemented.has('logging') ? { logging: {} } : {},

package/lib/mcp/stdio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/mcp/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAElE,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,2CAA2C;IAC3C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KACzF,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAChF;AAED,wBAAwB;AACxB,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACrD,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAAA;IACb,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBtF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,GAAG,WAAW,CAyGrF"}
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/mcp/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAElE,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,2CAA2C;IAC3C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KACzF,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAChF;AAED,wBAAwB;AACxB,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACrD,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAAA;IACb,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBtF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,GAAG,WAAW,CAiHrF"}

package/lib/mcp/stdio.js

@@ -73,9 +73,17 @@ export function createStdioBridge(endpoint, io) {
             catch {
                 // A malformed frame is answered on the PROTOCOL channel, because the client
                 // is waiting for a response and a diagnostic would not reach it.
+                /**
+                 * The `id` is OMITTED rather than set to `null`, which is the rule `protocol.ts`
+                 * documents three hundred lines away and this site contradicted.
+                 *
+                 * JSON-RPC 2.0 conventionally allows `id: null` for an undeterminable id, but the
+                 * pinned revision types `RequestId` as `string | integer` and does not admit null,
+                 * while `id` itself is OPTIONAL. A frame that failed to parse has no id to echo, so
+                 * omitting it is the conformant way to say "unknown".
+                 */
                 return frame({
                     jsonrpc: '2.0',
-                    id: null,
                     error: { code: -32700, message: 'the frame is not valid JSON' },
                 });
             }

package/lib/mcp/subscriptions.d.ts

@@ -27,7 +27,7 @@
  *
  * @module @try-works/dsh-model-as-tool/mcp/subscriptions
  */
-import type { WireRequest } from './protocol.ts';
+import { type WireRequest } from './protocol.ts';
 /** The notification types the revision defines for catalog changes. */
 export type SubscriptionFilterKey = 'toolsListChanged' | 'promptsListChanged' | 'resourcesListChanged' | 'resourceSubscriptions';
 /** The filter a client requested, or the subset the server acknowledged. */
@@ -79,6 +79,7 @@ export declare function acknowledgeFilter(requested: SubscriptionFilter): Subscr
 /** Manages the active catalog subscriptions. */
 export declare class SubscriptionRegistry {
     #private;
+    /** Counter for ids this server issues, so an id is never caller-chosen. */
     /** Active subscriptions, for diagnostics. */
     get active(): readonly Subscription[];
     /**
@@ -132,4 +133,45 @@ export declare class SubscriptionRegistry {
  * @returns the notification.
  */
 export declare function cancelSubscription(subscriptionId: string): Record<string, unknown>;
+/**
+ * The DELIVERY half of P26-09 (task-73): what a streaming transport
+ * implements. The registry owns the subscriptions and the filtering; the sink
+ * owns the per-client open streams. A production SSE transport provides its
+ * writer here; the tests inject a collecting sink that exercises the SAME
+ * consumer path end to end.
+ */
+export interface SubscriptionDeliverySink {
+    /** Deliver one addressed notification to its client's open stream. */
+    deliver(message: SubscriptionMessage): void;
+    /** Close every stream belonging to one client (teardown-cancelled first). */
+    closeClient(clientId: string, reason: string): void;
+}
+/**
+ * Run one catalog-change publication through the delivery consumer: the
+ * registry's per-caller filtering decides WHO gets the event, and the sink
+ * carries it to each client's stream. Acknowledgement ordering is the
+ * registry's own guarantee — an acknowledgement is marked sent before any
+ * publish can run, so no event can precede it.
+ * @param registry - the subscription state.
+ * @param generation - the catalog generation that changed.
+ * @param sink - the delivery transport.
+ * @returns how many subscribers received the change.
+ */
+export declare function deliverCatalogChange(registry: SubscriptionRegistry, generation: number, sink: SubscriptionDeliverySink): number;
+/**
+ * The memory sink: one per-client queue, used by the tests to exercise the
+ * consumer and by the host as the transport seam until a streaming endpoint
+ * injects its writer. It honours the same contract a real transport must:
+ * delivery only to the addressed client, and closeClient stops that client's
+ * queue entirely.
+ */
+export declare class MemoryDeliverySink implements SubscriptionDeliverySink {
+    #private;
+    /** The delivered messages for one client, in delivery order. */
+    forClient(clientId: string): readonly SubscriptionMessage[];
+    /** Whether the sink closed a client, and why. */
+    closeReason(clientId: string): string | undefined;
+    deliver(message: SubscriptionMessage): void;
+    closeClient(clientId: string, reason: string): void;
+}
 //# sourceMappingURL=subscriptions.d.ts.map

package/lib/mcp/subscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/mcp/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,GACtB,uBAAuB,CAAA;AAE3B,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC,GAAG;IACjF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,qBAAqB,EAAyB,CAAA;AAEvF,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,2CAA2C,CAAA;AAE3E,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;IACzC;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,gCAAgC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,kBAAkB,GAAG,kBAAkB,CAQnF;AAED,gDAAgD;AAChD,qBAAa,oBAAoB;;IAK/B,6CAA6C;IAC7C,IAAI,MAAM,IAAI,SAAS,YAAY,EAAE,CAEpC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG;QAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAChC;IA+BD;;;;;;OAMG;IACH,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE;IA0B1E;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE;IAyBxD;;;;;OAKG;IACH,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IASxD,kDAAkD;IAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE;CAGrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMlF"}
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/mcp/subscriptions.ts"],"names":[],"mappings":"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"}

package/lib/mcp/subscriptions.js

@@ -27,6 +27,7 @@
  *
  * @module @try-works/dsh-model-as-tool/mcp/subscriptions
  */
+import { ERROR_CODES, WireError } from "./protocol.js";
 /**
  * The notification types this server actually emits.
  *
@@ -59,7 +60,6 @@ export function acknowledgeFilter(requested) {
 export class SubscriptionRegistry {
     #subscriptions = new Map();
     /** Counter for ids this server issues, so an id is never caller-chosen. */
-    #issued = 0;
     /** Active subscriptions, for diagnostics. */
     get active() {
         return [...this.#subscriptions.values()];
@@ -74,13 +74,47 @@ export class SubscriptionRegistry {
      * @returns the result envelope, the acknowledgement, and the subscription id.
      */
     listen(request, clientId) {
-        const requested = (request.params?.notifications ?? {});
-        const acknowledged = acknowledgeFilter(requested);
-        // Server-issued. A caller-chosen id would let one client address another
-        // client's subscription in a later cancellation.
-        const subscriptionId = `sub_${Date.now().toString(36)}_${(++this.#issued).toString(36)}`;
-        const subscription = { subscriptionId, clientId, acknowledged, announced: true };
-        this.#subscriptions.set(subscriptionId, subscription);
+        /**
+         * `notifications` IS REQUIRED, and this used to default it.
+         *
+         * The pinned schema's `SubscriptionsListenRequestParams` declares
+         * `required: ["_meta","notifications"]`. Defaulting an absent filter to `{}` and
+         * returning SUCCESS contradicted that AND contradicted this module's own rule that a
+         * missing required field is `invalidParams` rather than a defaulted value — a client
+         * would receive an acknowledgement for a subscription it never described, and the
+         * filter it believed it had sent would be silently empty.
+         */
+        const requested = request.params?.notifications;
+        if (requested === undefined || requested === null || typeof requested !== 'object' || Array.isArray(requested)) {
+            throw new WireError(ERROR_CODES.invalidParams, 'subscriptions/listen requires params.notifications; a missing filter is invalid rather than defaulted');
+        }
+        const filter = requested;
+        const acknowledged = acknowledgeFilter(filter);
+        /**
+         * THE SUBSCRIPTION IS IDENTIFIED BY THE LISTEN REQUEST'S OWN ID.
+         *
+         * This used to invent `sub_<time>_<n>`, which was WRONG, and the pinned schema says so
+         * in as many words. `CancelledNotification` states that the server's stream-terminating
+         * cancellation "references the ID of the `subscriptions/listen` request that opened the
+         * stream", and `SubscriptionsListenResultMetaObject` types its required
+         * `io.modelcontextprotocol/subscriptionId` as a **`RequestId`** — the same type as a
+         * request id — "so the client can correlate it with the originating subscription".
+         *
+         * A server-invented id that the client never saw cannot be correlated with anything, so
+         * a client could neither match the acknowledgement to its request nor recognise the
+         * cancellation that ends the stream.
+         *
+         * The original comment claimed a caller-chosen id would let one client address
+         * another's subscription. That concern is real but it is NOT addressed by inventing an
+         * id: subscriptions are keyed by this id and BOUND to `clientId`, and the binding is
+         * what prevents cross-client addressing.
+         */
+        const subscriptionId = request.id;
+        if (typeof subscriptionId !== 'string' && typeof subscriptionId !== 'number') {
+            throw new WireError(ERROR_CODES.invalidParams, 'subscriptions/listen requires a string or integer request id, which IS the subscription id');
+        }
+        const subscription = { subscriptionId: String(subscriptionId), clientId, acknowledged, announced: true };
+        this.#subscriptions.set(String(subscriptionId), subscription);
         return {
             result: {
                 resultType: 'complete',
@@ -98,7 +132,7 @@ export class SubscriptionRegistry {
                     _meta: { [SUBSCRIPTION_ID_KEY]: subscriptionId },
                 },
             },
-            subscriptionId,
+            subscriptionId: String(subscriptionId),
         };
     }
     /**
@@ -204,4 +238,51 @@ export function cancelSubscription(subscriptionId) {
         params: { requestId: subscriptionId },
     };
 }
+/**
+ * Run one catalog-change publication through the delivery consumer: the
+ * registry's per-caller filtering decides WHO gets the event, and the sink
+ * carries it to each client's stream. Acknowledgement ordering is the
+ * registry's own guarantee — an acknowledgement is marked sent before any
+ * publish can run, so no event can precede it.
+ * @param registry - the subscription state.
+ * @param generation - the catalog generation that changed.
+ * @param sink - the delivery transport.
+ * @returns how many subscribers received the change.
+ */
+export function deliverCatalogChange(registry, generation, sink) {
+    const messages = registry.publishToolListChanged(generation);
+    for (const message of messages)
+        sink.deliver(message);
+    return messages.length;
+}
+/**
+ * The memory sink: one per-client queue, used by the tests to exercise the
+ * consumer and by the host as the transport seam until a streaming endpoint
+ * injects its writer. It honours the same contract a real transport must:
+ * delivery only to the addressed client, and closeClient stops that client's
+ * queue entirely.
+ */
+export class MemoryDeliverySink {
+    #queues = new Map();
+    #closed = new Map();
+    /** The delivered messages for one client, in delivery order. */
+    forClient(clientId) {
+        return [...(this.#queues.get(clientId) ?? [])];
+    }
+    /** Whether the sink closed a client, and why. */
+    closeReason(clientId) {
+        return this.#closed.get(clientId);
+    }
+    deliver(message) {
+        if (this.#closed.has(message.clientId))
+            return;
+        const queue = this.#queues.get(message.clientId) ?? [];
+        queue.push(message);
+        this.#queues.set(message.clientId, queue);
+    }
+    closeClient(clientId, reason) {
+        this.#closed.set(clientId, reason);
+        this.#queues.delete(clientId);
+    }
+}
 //# sourceMappingURL=subscriptions.js.map

package/lib/model-qualification.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Model qualification and capability resolution (MODEL-01, MODEL-04, MODEL-05, MODEL-06).
+ *
+ * Four rules, each guarding a way of claiming more than is known:
+ *
+ * - **A platform table is not proof of correct inference** (MODEL-05). A record is
+ *   qualified only when the exact revision, artifact hash, tokenizer, processor, engine
+ *   version, ABI and execution provider are all recorded. A missing field is a GAP, and
+ *   a gap is not a qualification.
+ * - **A model's modality list is not an adapter's** (MODEL-05). A model can support
+ *   video while the selected adapter does not, so what is ADVERTISED is the INTERSECTION
+ *   of the two, described as such.
+ * - **A model name is not a capability test** (MODEL-06). Capability comes from the
+ *   resolved model, never from recognising a brand.
+ * - **Unknown is not unsupported** (MODEL-06). The requirement says to record them
+ *   separately, because collapsing them lets an unevaluated capability be reported as a
+ *   known absence — or, worse, the reverse.
+ *
+ * @module @try-works/dsh-model-as-tool/model-qualification
+ */
+/**
+ * What is known about one capability.
+ *
+ * Three states rather than two, because MODEL-06 requires unknown and unsupported to be
+ * recorded separately.
+ */
+export type CapabilityState = 
+/** Evaluated, and it works. */
+'supported'
+/** Evaluated, and it does not. */
+ | 'unsupported'
+/** NOT evaluated. Reporting this as either of the others is the defect. */
+ | 'unknown';
+/** A capability of a model or an adapter. */
+export type Modality = 'text' | 'code' | 'image' | 'audio' | 'video' | 'embedding';
+/**
+ * The exact path a model is executed through (MODEL-05).
+ *
+ * Every field is required for qualification, because each one has been the difference
+ * between "the package imports" and "inference is correct".
+ */
+export interface QualificationRecord {
+    /** The model revision, not a branch or floating tag. */
+    readonly modelRevision: string;
+    /** The SHA of the exported artifact that is actually loaded. */
+    readonly artifactSha: string;
+    /** The tokenizer identity. */
+    readonly tokenizer: string;
+    /** The processor or preprocessing recipe identity. */
+    readonly processor: string;
+    /** The engine or package version. */
+    readonly engineVersion: string;
+    /** The Node ABI. */
+    readonly nodeAbi: string;
+    /** The CPU architecture, e.g. `x64`. */
+    readonly architecture: string;
+    /** The execution provider, e.g. `cpu` or `wasm`. */
+    readonly executionProvider: string;
+}
+/** The fields a qualification record must carry. */
+export declare const QUALIFICATION_FIELDS: readonly (keyof QualificationRecord)[];
+/**
+ * Report which qualification fields are missing (MODEL-05).
+ *
+ * A platform table, a successful package import or a runnable base model is not proof of
+ * correct inference, so a record with gaps is not a qualification however well it runs.
+ * @param record - the partial record.
+ * @returns the missing fields.
+ */
+export declare function qualificationGaps(record: Partial<QualificationRecord>): readonly (keyof QualificationRecord)[];
+/**
+ * Whether a record qualifies a path (MODEL-05).
+ * @param record - the partial record.
+ * @returns whether every required field is present.
+ */
+export declare function isQualified(record: Partial<QualificationRecord>): record is QualificationRecord;
+/** What a model supports, and what an adapter supports. */
+export interface ModalityClaim {
+    readonly modelSupports: readonly Modality[];
+    readonly adapterSupports: readonly Modality[];
+}
+/**
+ * The capabilities that may be ADVERTISED (MODEL-05).
+ *
+ * The intersection, because a model can support a modality while the selected adapter
+ * does not. Advertising the model's list would promise something the adapter cannot do.
+ * @param claim - what each side supports.
+ * @returns the advertisable modalities.
+ */
+export declare function advertisableModalities(claim: ModalityClaim): readonly Modality[];
+/**
+ * Describe a model's capability as the INTERSECTION (MODEL-05).
+ *
+ * The description names what is not advertisable and why, so a reader is not left to
+ * infer that the model lacks the modality when in fact the adapter does.
+ * @param claim - what each side supports.
+ * @returns a description that is true of the pairing.
+ */
+export declare function describeCapability(claim: ModalityClaim): string;
+/**
+ * Resolve one capability (MODEL-06).
+ *
+ * A capability is resolved from what was EVALUATED. A model name is never consulted,
+ * because a brand is not a capability test, and an unevaluated capability returns
+ * `unknown` rather than being inferred from a sibling.
+ * @param evidence - the observed result, or undefined when not evaluated.
+ * @returns the state.
+ */
+export declare function resolveCapability(evidence: boolean | undefined): CapabilityState;
+/**
+ * Whether a model name may be used to infer a capability (MODEL-06).
+ *
+ * It may not. Returns false so the prohibition is asserted rather than merely intended:
+ * a rule that lives only in a comment is one a future branch will not read.
+ * @returns always false.
+ */
+export declare function modelNameImpliesCapability(): boolean;
+/** How a candidate implementation executes (MODEL-04). */
+export type ExecutionMode = 
+/** Pure JavaScript or WASM usable in plain Node. */
+'js-wasm-node'
+/** Prebuilt ONNX Runtime for Node. */
+ | 'onnxruntime-node'
+/** A managed native Windows executable with pinned assets. */
+ | 'managed-native-windows'
+/** Requires Python on the end user's machine. */
+ | 'python-required'
+/** Requires WSL. */
+ | 'wsl-required'
+/** Requires Docker. */
+ | 'docker-required'
+/** Requires a GPU. */
+ | 'gpu-required'
+/** Only works in a browser. */
+ | 'browser-only'
+/** Requires a consumer-side compile step. */
+ | 'consumer-compile';
+/** Why a mode was refused. */
+export interface ModeVerdict {
+    readonly acceptable: boolean;
+    readonly reason?: string;
+}
+/**
+ * Whether an execution mode is acceptable for the end user (MODEL-04).
+ *
+ * Python, WSL, Docker, a GPU and a consumer compile step are all refused: maintainers may
+ * use Python to export artifacts, but it MUST NOT be required on an end user's Windows
+ * machine. A browser-only API does not establish Node support.
+ * @param mode - the mode.
+ * @returns the verdict, with a reason when refused.
+ */
+export declare function executionModeVerdict(mode: ExecutionMode): ModeVerdict;
+/** An embedding space identity (MODEL-01, BASE-12). */
+export interface EmbeddingSpace {
+    /** The model that produces it. */
+    readonly modelId: string;
+    /** The dimensionality of the vectors it produces. */
+    readonly dimensions: number;
+}
+/**
+ * Whether one embedding space may silently stand in for another (BASE-12).
+ *
+ * Only when the dimensions MATCH. EmbeddingGemma 2 is 768-dimensional and MiniLM is
+ * 384-dimensional, so substituting one for the other silently would compare vectors of
+ * different widths and produce meaningless similarity.
+ * @param from - the space in use.
+ * @param to - the proposed replacement.
+ * @returns whether the substitution is safe without an explicit migration.
+ */
+export declare function maySubstituteSilently(from: EmbeddingSpace, to: EmbeddingSpace): boolean;
+/**
+ * Describe an embedding substitution (BASE-12).
+ * @param from - the space in use.
+ * @param to - the proposed replacement.
+ * @returns a description naming the incompatibility when there is one.
+ */
+export declare function describeSubstitution(from: EmbeddingSpace, to: EmbeddingSpace): string;
+/**
+ * The reduced dimensionalities EmbeddingGemma 2 supports (MODEL-01).
+ *
+ * The model card describes 768 reducible to 512, 256 and 128. Recorded rather than
+ * assumed, because a reduction that is not applied consistently produces vectors that
+ * cannot be compared with each other.
+ */
+export declare const EMBEDDINGGEMMA2_DIMENSIONS: readonly number[];
+/**
+ * Whether a stated dimensionality is one EmbeddingGemma 2 can produce (MODEL-01).
+ * @param dimensions - the stated width.
+ * @returns whether it is a documented width.
+ */
+export declare function isEmbeddingGemma2Width(dimensions: number): boolean;
+//# sourceMappingURL=model-qualification.d.ts.map

package/lib/model-qualification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-qualification.d.ts","sourceRoot":"","sources":["../src/model-qualification.ts"],"names":[],"mappings":"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"}