@hydranium/protocol 1.0.0-next.10

package/lib/rpc/create-rpc-proxy.d.ts

@@ -0,0 +1,188 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Event, type MessageConnection } from 'vscode-jsonrpc';
+import { type BindRpcMethodsOptions } from './bind-rpc-methods';
+/**
+ * Lifecycle events surfaced on every {@link createRpcProxy} return — `onDidOpenConnection`
+ * fires once after the underlying `MessageConnection` resolves; `onDidCloseConnection`
+ * fires when the connection's `onClose` triggers. Useful for proxy-only consumers
+ * (widgets, downstream services) that don't hold the `MessageConnection` directly
+ * and would otherwise need it threaded through just to react to disconnects.
+ *
+ * Reconnection is NOT modelled — the framework assumes a single connection
+ * lifetime per proxy. If the transport drops, the adopter constructs a new
+ * connection + proxy.
+ *
+ * **Reserved property names on `RpcProxy<T>`.** The proxy's get-trap
+ * intercepts four property names — any wire method declared on `T` with
+ * one of these names would shadow the reserved behaviour instead of
+ * dispatching a wire call. Adopters defining wire-method names should
+ * avoid:
+ *
+ *   - `onDidOpenConnection` / `onDidCloseConnection` — return the
+ *     lifecycle events declared on this interface.
+ *   - `then` — returns `undefined` so the proxy is not auto-awaited
+ *     when caught by Promise-detection in the host environment.
+ *   - `toJSON` — returns `undefined` so JSON serializers do not try to
+ *     flatten the proxy.
+ *
+ * Symbol property accesses also return `undefined` (the proxy is not
+ * iterable, not a thenable, not serialisable).
+ */
+export interface RpcProxyLifecycle {
+    /**
+     * Fires exactly once, when the underlying connection promise resolves. It
+     * does NOT replay: a proxy built over an already-resolved connection fires
+     * on the next microtask, so a subscriber attached after that never hears
+     * anything. Subscribe in the same synchronous block that builds the proxy,
+     * or track readiness yourself.
+     *
+     * Never fires if the connection promise rejects — a failed transport
+     * construction is indistinguishable here from one still pending, and is
+     * meant to be observed where the connection is built.
+     */
+    readonly onDidOpenConnection: Event<void>;
+    /**
+     * Fires when the transport closes. Reconnection is not modelled, so it fires
+     * at most once and is never followed by another open — a consumer that has
+     * to survive a drop constructs a new proxy rather than waiting here.
+     */
+    readonly onDidCloseConnection: Event<void>;
+}
+/** Proxy of `T` plus the framework's connection-lifecycle events. */
+export type RpcProxy<T extends object> = T & RpcProxyLifecycle;
+/**
+ * Options controlling how method-name properties on the returned proxy
+ * are translated into wire calls.
+ *
+ * Generic over `TLocal` — the type of an OPTIONAL inbound handler target
+ * (see {@link localTarget} / {@link localMethods}). `TLocal` defaults to
+ * `never`, so callers that only want an outbound proxy omit the local
+ * fields entirely and the proxy behaves exactly as a pure remote proxy.
+ */
+export interface CreateRpcProxyOptions<TLocal extends object = never> {
+    /**
+     * Prefix prepended to the property name to form the JSON-RPC method
+     * string. For example, prefix `'data-server/'` turns a property access
+     * `proxy.getModelDocument` into the wire method
+     * `'data-server/getModelDocument'`. Defaults to the empty string —
+     * the property name is the wire name.
+     *
+     * When {@link localTarget} is supplied, the SAME prefix applies to the
+     * inbound handler registrations — both ends of a combined connection
+     * share one namespace.
+     */
+    readonly methodNamespace?: string;
+    /**
+     * Predicate to discriminate notification methods from request methods
+     * by their TS property name. Notification methods lower to
+     * `connection.sendNotification` and return `void`; request methods
+     * lower to `connection.sendRequest` and return `Promise<TResult>`.
+     *
+     * Default: property names starting with `'on'` followed by an uppercase
+     * letter are notifications. Adopters defining typed contracts in the
+     * `DataClientProtocol` style get the right routing without per-method
+     * configuration.
+     *
+     * Applies symmetrically to the {@link localTarget} binding, so the
+     * inbound and outbound sides agree on which methods are notifications.
+     */
+    readonly isNotification?: (methodName: string) => boolean;
+    /**
+     * OPTIONAL inbound-handler target. When supplied together with
+     * {@link localMethods}, `createRpcProxy` ALSO binds those methods of
+     * `localTarget` as inbound request/notification handlers on the same
+     * connection (delegating to `bindRpcMethods`) — collapsing the common
+     * "proxy the remote + handle the local" two-step into one call. The
+     * binding is torn down on `connection.onClose`; the return value stays
+     * just the remote proxy (no `Disposable` surfaced — there is no use
+     * case for unbinding a connection-scoped target before its connection
+     * closes). Callers that need the explicit `Disposable` call
+     * `bindRpcMethods` directly instead.
+     *
+     * Omit (the `TLocal = never` default) for a pure outbound proxy.
+     */
+    readonly localTarget?: TLocal;
+    /**
+     * Method names of {@link localTarget} to bind as inbound handlers.
+     * REQUIRED for the binding to happen (no auto-enumeration — TypeScript
+     * access modifiers are erased at runtime, so a class instance's
+     * prototype carries internal helpers that must not become wire
+     * endpoints; the explicit list is the allowlist). Declare it
+     * `as const satisfies keyof TLocal` at the call site for a compile-time
+     * drift check; `bindRpcMethods` additionally verifies each name exists
+     * on the target at attach time.
+     */
+    readonly localMethods?: readonly (keyof TLocal & string)[];
+    /**
+     * Forwarded to the inbound {@link localTarget} binding: when supplied, every
+     * inbound handler is timed into this collector under its wire name. Lets a
+     * head that owns its server through `createRpcProxy` (rather than a bare
+     * `bindRpcMethods` call) still capture per-method latency. Absent by default.
+     */
+    readonly latency?: BindRpcMethodsOptions['latency'];
+}
+/**
+ * Default notification discriminator — `on`-followed-by-an-uppercase-letter
+ * methods are notifications (`onProgress`, `onDocumentUpdated`).
+ *
+ * The uppercase requirement is what keeps the heuristic honest: a
+ * request-shaped method that merely *starts* with the letters "on"
+ * (`onboardUser`, `onlineCheck`) stays a request, instead of being misrouted
+ * as a fire-and-forget notification with its `Promise` result silently
+ * dropped. It follows the observer-callback convention the framework's
+ * contracts already use, where the capital always marks the event name.
+ *
+ * Still lexical, so it cannot catch everything — `onDemandRebuild` reads as a
+ * request but matches. Supply a custom
+ * {@link CreateRpcProxyOptions.isNotification} for contracts that don't fit
+ * the convention, and pass the same predicate to both ends.
+ */
+export declare function defaultIsNotification(methodName: string): boolean;
+/**
+ * Build a typed RPC proxy `T` over a vscode-jsonrpc {@link MessageConnection}.
+ * Every method access on the returned object lowers transparently to
+ * `connection.sendRequest` (request methods) or `connection.sendNotification`
+ * (notification methods, by default `on*`-prefixed). The single-arg
+ * payload shape is preserved: `proxy.foo(args)` sends `(method, args)`
+ * over the wire and resolves with the response.
+ *
+ * `on` + an uppercase letter is the only notification marker — see
+ * {@link defaultIsNotification}, and pass a custom `isNotification` to both
+ * ends for a contract that doesn't fit.
+ *
+ * **Wire tracing.** The proxy adds no tracing layer of its own, deliberately:
+ * vscode-jsonrpc's own `connection.trace` already covers wire method names,
+ * params, results and errors, and a second layer here would double every
+ * traced line.
+ *
+ * Accepts either a ready connection or a `Promise<MessageConnection>` —
+ * proxy methods called before the promise resolves queue until it does,
+ * then dispatch, so adopters can wire the proxy before its underlying
+ * transport is available (e.g. before the Langium services finish
+ * constructing).
+ *
+ * A few property names are intercepted rather than dispatched — see
+ * {@link RpcProxyLifecycle} for the reserved list and why each is guarded.
+ *
+ * Each method of `T` dispatches under `<methodNamespace><methodName>`: a
+ * request method resolves through `connection.sendRequest`, while one the
+ * notification heuristic matches goes out through `sendNotification` and
+ * returns nothing, so a caller that awaits it waits on `undefined` rather
+ * than on delivery.
+ *
+ * **Combined proxy + inbound binding.** Supply `localTarget` + `localMethods`
+ * to ALSO register inbound handlers on the same connection in one call —
+ * the typical both-ends-of-a-bidirectional-connection setup. The remote
+ * proxy is still the return value; the inbound binding tears down on
+ * `connection.onClose`, so binding twice over one connection leaks the
+ * first set of handlers until it closes.
+ */
+export declare function createRpcProxy<T extends object, TLocal extends object = never>(connection: MessageConnection | Promise<MessageConnection>, options?: CreateRpcProxyOptions<TLocal>): RpcProxy<T>;
+//# sourceMappingURL=create-rpc-proxy.d.ts.map

package/lib/rpc/create-rpc-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-rpc-proxy.d.ts","sourceRoot":"","sources":["../../src/rpc/create-rpc-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAW,KAAK,KAAK,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,KAAK,qBAAqB,EAAkB,MAAM,oBAAoB,CAAC;AAGhF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,iBAAiB;IAC/B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,qEAAqE;AACrE,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG,iBAAiB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB,CAAC,MAAM,SAAS,MAAM,GAAG,KAAK;IACjE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1D;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAE3D;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;CACtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM,GAAG,KAAK,EAC3E,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,EAC1D,OAAO,GAAE,qBAAqB,CAAC,MAAM,CAAM,GAC3C,QAAQ,CAAC,CAAC,CAAC,CA0Eb"}

package/lib/rpc/create-rpc-proxy.js

@@ -0,0 +1,158 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultIsNotification = defaultIsNotification;
+exports.createRpcProxy = createRpcProxy;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+const bind_rpc_methods_1 = require("./bind-rpc-methods");
+const wire_prefix_1 = require("./wire-prefix");
+/**
+ * Default notification discriminator — `on`-followed-by-an-uppercase-letter
+ * methods are notifications (`onProgress`, `onDocumentUpdated`).
+ *
+ * The uppercase requirement is what keeps the heuristic honest: a
+ * request-shaped method that merely *starts* with the letters "on"
+ * (`onboardUser`, `onlineCheck`) stays a request, instead of being misrouted
+ * as a fire-and-forget notification with its `Promise` result silently
+ * dropped. It follows the observer-callback convention the framework's
+ * contracts already use, where the capital always marks the event name.
+ *
+ * Still lexical, so it cannot catch everything — `onDemandRebuild` reads as a
+ * request but matches. Supply a custom
+ * {@link CreateRpcProxyOptions.isNotification} for contracts that don't fit
+ * the convention, and pass the same predicate to both ends.
+ */
+function defaultIsNotification(methodName) {
+    return /^on[A-Z]/.test(methodName);
+}
+/**
+ * Runtime enforcement of the single-arg convention. TypeScript catches
+ * misuse at compile time for typed contract callers, but loosely-typed
+ * callsites (`any` / `unknown` proxy) would silently drop extra args.
+ * Throw loudly so the violation is visible.
+ */
+function assertSingleArg(wireName, args) {
+    if (args.length > 1) {
+        throw new Error(`RPC method '${wireName}' called with ${args.length} arguments — typed contracts use a single params object. ` +
+            'Pass a single object instead: proxy.foo({ ...args }).');
+    }
+}
+/**
+ * Build a typed RPC proxy `T` over a vscode-jsonrpc {@link MessageConnection}.
+ * Every method access on the returned object lowers transparently to
+ * `connection.sendRequest` (request methods) or `connection.sendNotification`
+ * (notification methods, by default `on*`-prefixed). The single-arg
+ * payload shape is preserved: `proxy.foo(args)` sends `(method, args)`
+ * over the wire and resolves with the response.
+ *
+ * `on` + an uppercase letter is the only notification marker — see
+ * {@link defaultIsNotification}, and pass a custom `isNotification` to both
+ * ends for a contract that doesn't fit.
+ *
+ * **Wire tracing.** The proxy adds no tracing layer of its own, deliberately:
+ * vscode-jsonrpc's own `connection.trace` already covers wire method names,
+ * params, results and errors, and a second layer here would double every
+ * traced line.
+ *
+ * Accepts either a ready connection or a `Promise<MessageConnection>` —
+ * proxy methods called before the promise resolves queue until it does,
+ * then dispatch, so adopters can wire the proxy before its underlying
+ * transport is available (e.g. before the Langium services finish
+ * constructing).
+ *
+ * A few property names are intercepted rather than dispatched — see
+ * {@link RpcProxyLifecycle} for the reserved list and why each is guarded.
+ *
+ * Each method of `T` dispatches under `<methodNamespace><methodName>`: a
+ * request method resolves through `connection.sendRequest`, while one the
+ * notification heuristic matches goes out through `sendNotification` and
+ * returns nothing, so a caller that awaits it waits on `undefined` rather
+ * than on delivery.
+ *
+ * **Combined proxy + inbound binding.** Supply `localTarget` + `localMethods`
+ * to ALSO register inbound handlers on the same connection in one call —
+ * the typical both-ends-of-a-bidirectional-connection setup. The remote
+ * proxy is still the return value; the inbound binding tears down on
+ * `connection.onClose`, so binding twice over one connection leaks the
+ * first set of handlers until it closes.
+ */
+function createRpcProxy(connection, options = {}) {
+    const methodNamespace = options.methodNamespace ?? '';
+    (0, wire_prefix_1.assertValidMethodNamespace)(methodNamespace, 'createRpcProxy');
+    const isNotification = options.isNotification ?? defaultIsNotification;
+    const resolvedConnection = Promise.resolve(connection);
+    // Tied to `connection.onClose` so the inbound handlers release with the
+    // connection; see `localTarget` for why no `Disposable` is surfaced.
+    const { localTarget, localMethods } = options;
+    if (localTarget && localMethods && localMethods.length > 0) {
+        const binding = (0, bind_rpc_methods_1.bindRpcMethods)(connection, localTarget, localMethods, { methodNamespace, isNotification, latency: options.latency });
+        resolvedConnection.then(conn => conn.onClose(() => binding.dispose())).catch(() => undefined);
+    }
+    const onDidOpenConnectionEmitter = new vscode_jsonrpc_1.Emitter();
+    const onDidCloseConnectionEmitter = new vscode_jsonrpc_1.Emitter();
+    resolvedConnection
+        .then(conn => {
+        onDidOpenConnectionEmitter.fire(undefined);
+        conn.onClose(() => onDidCloseConnectionEmitter.fire(undefined));
+    })
+        .catch(() => {
+        // Connection promise rejected — treat as never-opened; lifecycle
+        // events simply never fire. Adopters observe transport-construction
+        // failures through their own connection-construction error handling.
+    });
+    const target = Object.create(null);
+    return new Proxy(target, {
+        get(_t, prop) {
+            if (typeof prop !== 'string') {
+                return undefined;
+            }
+            // Keep the proxy out of thenable / serializer code paths so it
+            // doesn't trigger spurious requests.
+            if (prop === 'then' || prop === 'toJSON') {
+                return undefined;
+            }
+            if (prop === 'onDidOpenConnection') {
+                return onDidOpenConnectionEmitter.event;
+            }
+            if (prop === 'onDidCloseConnection') {
+                return onDidCloseConnectionEmitter.event;
+            }
+            const wireName = methodNamespace + prop;
+            if (isNotification(prop)) {
+                return (...args) => {
+                    assertSingleArg(wireName, args);
+                    // Fire-and-forget; rejection (e.g. connection closed) is swallowed
+                    // to match the notification contract — adopters observe transport
+                    // failures via the connection's own close / error events, never
+                    // via a notification's return value.
+                    void resolvedConnection.then(connection => connection.sendNotification(wireName, args[0])).catch(() => undefined);
+                };
+            }
+            return (...args) => {
+                assertSingleArg(wireName, args);
+                // Capture the calling stack frame BEFORE the await so debugging gets
+                // both client- and server-side stacks on rejection. vscode-jsonrpc's
+                // default error envelope surfaces only the server-side stack; without
+                // this, a rejected RPC promise looks like it came from "somewhere
+                // inside vscode-jsonrpc" rather than from the calling code.
+                const capturedError = new Error(`RPC request '${wireName}' failed`);
+                return resolvedConnection
+                    .then(connection => connection.sendRequest(wireName, args[0]))
+                    .catch((err) => {
+                    if (err instanceof Error && capturedError.stack) {
+                        err.stack = `${err.stack ?? err.message}\nCaused by request from:\n${capturedError.stack}`;
+                    }
+                    throw err;
+                });
+            };
+        }
+    });
+}
+//# sourceMappingURL=create-rpc-proxy.js.map

package/lib/rpc/create-rpc-proxy.js.map

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

package/lib/rpc/index.d.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './bind-rpc-methods';
+export * from './create-rpc-proxy';
+export * from './wire-prefix';
+//# sourceMappingURL=index.d.ts.map

package/lib/rpc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rpc/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAMlF,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC"}

package/lib/rpc/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Generic JSON-RPC primitives shared across the framework's typed
+// protocol heads — see `data/data-protocol-methods.ts` for the
+// specialised composition.
+__exportStar(require("./bind-rpc-methods"), exports);
+__exportStar(require("./create-rpc-proxy"), exports);
+__exportStar(require("./wire-prefix"), exports);
+//# sourceMappingURL=index.js.map

package/lib/rpc/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rpc/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,kEAAkE;AAClE,+DAA+D;AAC/D,2BAA2B;AAE3B,qDAAmC;AACnC,qDAAmC;AACnC,gDAA8B"}

package/lib/rpc/wire-prefix.d.ts

@@ -0,0 +1,37 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/**
+ * Validates that a wire-name prefix — the `methodNamespace` option shared
+ * by `bindRpcMethods` and
+ * `createRpcProxy` — carries a
+ * trailing `/`.
+ *
+ * **Why this exists.** Adopters reading the LSP-namespace analogy
+ * (`textDocument/*`, `workspace/*`) naturally pass `'mylang'` expecting
+ * `'mylang/getModelDocument'` on the wire. Concatenating verbatim instead
+ * yields `'mylanggetModelDocument'`, and because the proxy and binding sites
+ * pick the wrong prefix in lockstep the mismatch is silent on a single-process
+ * adopter, audible only as a per-method "Unhandled method" on the wire log.
+ *
+ * Throwing is preferred over coercion: coercion would disguise the case where
+ * the adopter intended a different separator (`'.'`, `':'`), and throwing at
+ * construction time surfaces the bug at the adopter's own callsite rather than
+ * at the first wire response.
+ *
+ * Accepts the empty string (explicit no-prefix mode) or any non-empty string
+ * ending with `/`; anything else throws {@link TypeError} synchronously.
+ *
+ * @param methodNamespace The configured prefix (e.g. `'mylang/'`,
+ *    `'data-server/'`, `''`).
+ * @param caller Name of the validating function, embedded in the thrown
+ *    message so the error reads as if it came from the adopter-facing
+ *    function rather than this helper.
+ */
+export declare function assertValidMethodNamespace(methodNamespace: string, caller: string): void;
+//# sourceMappingURL=wire-prefix.d.ts.map

package/lib/rpc/wire-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-prefix.d.ts","sourceRoot":"","sources":["../../src/rpc/wire-prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,0BAA0B,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAWxF"}

package/lib/rpc/wire-prefix.js

@@ -0,0 +1,49 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidMethodNamespace = assertValidMethodNamespace;
+/**
+ * Validates that a wire-name prefix — the `methodNamespace` option shared
+ * by `bindRpcMethods` and
+ * `createRpcProxy` — carries a
+ * trailing `/`.
+ *
+ * **Why this exists.** Adopters reading the LSP-namespace analogy
+ * (`textDocument/*`, `workspace/*`) naturally pass `'mylang'` expecting
+ * `'mylang/getModelDocument'` on the wire. Concatenating verbatim instead
+ * yields `'mylanggetModelDocument'`, and because the proxy and binding sites
+ * pick the wrong prefix in lockstep the mismatch is silent on a single-process
+ * adopter, audible only as a per-method "Unhandled method" on the wire log.
+ *
+ * Throwing is preferred over coercion: coercion would disguise the case where
+ * the adopter intended a different separator (`'.'`, `':'`), and throwing at
+ * construction time surfaces the bug at the adopter's own callsite rather than
+ * at the first wire response.
+ *
+ * Accepts the empty string (explicit no-prefix mode) or any non-empty string
+ * ending with `/`; anything else throws {@link TypeError} synchronously.
+ *
+ * @param methodNamespace The configured prefix (e.g. `'mylang/'`,
+ *    `'data-server/'`, `''`).
+ * @param caller Name of the validating function, embedded in the thrown
+ *    message so the error reads as if it came from the adopter-facing
+ *    function rather than this helper.
+ */
+function assertValidMethodNamespace(methodNamespace, caller) {
+    if (methodNamespace === '' || methodNamespace.endsWith('/')) {
+        return;
+    }
+    throw new TypeError(`${caller}: methodNamespace '${methodNamespace}' must end with '/' (or be empty). ` +
+        "Adopters reading the LSP-namespace analogy ('textDocument/*', 'workspace/*') often " +
+        `forget the trailing slash, producing wire names like '${methodNamespace}someMethod' ` +
+        `that do not match handler bindings under '${methodNamespace}/someMethod'. ` +
+        `Either pass '${methodNamespace}/' or use the empty string for no prefix.`);
+}
+//# sourceMappingURL=wire-prefix.js.map

package/lib/rpc/wire-prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-prefix.js","sourceRoot":"","sources":["../../src/rpc/wire-prefix.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AA6BlF,gEAWC;AAtCD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,0BAA0B,CAAC,eAAuB,EAAE,MAAc;IAC/E,IAAI,eAAe,KAAK,EAAE,IAAI,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO;IACV,CAAC;IACD,MAAM,IAAI,SAAS,CAChB,GAAG,MAAM,sBAAsB,eAAe,qCAAqC;QAChF,qFAAqF;QACrF,yDAAyD,eAAe,cAAc;QACtF,6CAA6C,eAAe,gBAAgB;QAC5E,gBAAgB,eAAe,2CAA2C,CAC/E,CAAC;AACL,CAAC"}

package/lib/testing/data-doubles.d.ts

@@ -0,0 +1,121 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/**
+ * The two CLIENT-side doubles of the data head: a {@link DataPort} whose
+ * transport the test supplies, and a {@link DataClientProtocol} that records
+ * what arrived.
+ *
+ * # Why standalone, when a harness already builds one
+ *
+ * `makeDataServerHarness` builds a capturing client too, but fused into a
+ * server-bearing harness: taking it means taking a duplex pair, a `DataServer`
+ * and a proxy. That is the right shape for testing the server. It is the wrong
+ * shape — and not available at all — for testing the CLIENT half: a
+ * `DataSession`, a widget model, a host's port adapter. Those need to stand a
+ * double on one side of the boundary and something else entirely on the other,
+ * which is why both halves get hand-rolled per suite instead.
+ *
+ * # Runner-agnostic, deliberately
+ *
+ * No `jest.fn`, no `vi.fn`, no `expect`. The recorded arrays ARE the assertion
+ * surface, so the same double works under vitest, jest and a bare script. A
+ * mock-framework double would also make "was it called" the observable, when
+ * what a data-head test actually asserts is the CONTENT of what arrived —
+ * which `sourceClientId`, which version, which reason.
+ */
+import { type MessageConnection } from 'vscode-jsonrpc';
+import type { DataPort } from '../client/data-port';
+import type { DataClientProtocol } from '../data/data-server-protocol';
+import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from '../data/events';
+import type { Project } from '../project';
+import type { TransferDiagnostic } from '../transfer-diagnostic';
+import type { TransferElement } from '../transfer-element';
+/** Inputs to {@link makeFakeDataPort}. */
+export interface FakeDataPortOptions {
+    /**
+     * Establish one transport generation and hand back a LISTENING connection —
+     * the port's whole contract. Called once per generation, so a test that
+     * asserts on reconnection must return a FRESH connection each time rather
+     * than closing over one.
+     *
+     * Throwing (or rejecting) here is the transport-construction failure path,
+     * which the consumer surfaces through {@link FakeDataPort.reported}.
+     */
+    connect(): MessageConnection | Promise<MessageConnection>;
+    /**
+     * Stable client identity. Defaults to `'fake-data-port'`, which avoids the
+     * three sentinels the framework reserves (`'language-client'`, `'unknown'`,
+     * `'revert-on-close'`); override it when a test needs two distinguishable
+     * clients on one server.
+     */
+    clientId?: string;
+}
+/** A {@link DataPort} that records what passed through it. */
+export interface FakeDataPort extends DataPort {
+    /**
+     * Every connection {@link FakeDataPortOptions.connect} handed back, in
+     * order. Read from outside: "one connection shared across concurrent
+     * callers" and "a fresh connection after a teardown" are assertions about
+     * this length and about nothing else observable — a session that memoised a
+     * rejected promise, for instance, differs from one that retries ONLY here.
+     */
+    readonly connections: readonly MessageConnection[];
+    /**
+     * Every {@link DataPort.reportError} call, in order. Read from outside: this
+     * is the only place a transport failure surfaces, so a test for the failure
+     * path asserts on the `context` string here rather than on a rejection that
+     * the consumer may legitimately swallow.
+     */
+    readonly reported: readonly {
+        readonly error: unknown;
+        readonly context: string;
+    }[];
+    /**
+     * Fire {@link DataPort.onDispose} — the host tearing the transport down, a
+     * language-server restart being the case that forces the event to exist.
+     * Drives the consumer's reconnection path, which has no other trigger.
+     */
+    fireDispose(): void;
+    /** Release the emitter. Idempotent; does not close the connections, which the test owns. */
+    dispose(): void;
+}
+/**
+ * A {@link DataPort} over a transport the caller supplies.
+ *
+ * It deliberately does not create the transport itself. What varies between the
+ * cases worth testing is exactly that: an in-process duplex pair, a socket, a
+ * connection with no server behind it, a different one per generation.
+ */
+export declare function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort;
+/** A {@link DataClientProtocol} plus the arrays it records into. */
+export interface CapturingDataClient<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> {
+    /** The client to hand to a `DataSession` or bind as an RPC `localTarget`. */
+    readonly client: DataClientProtocol<TTransfer, TDiagnostic, TProject>;
+    /** Every `onDocumentUpdated` event, in arrival order. */
+    readonly updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[];
+    /** Every `onDocumentSaved` event, in arrival order. */
+    readonly saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[];
+    /** Every `onProjectsChanged` event, in arrival order. */
+    readonly projectsChanges: ProjectsChangedEvent<TProject>[];
+}
+/**
+ * A {@link DataClientProtocol} that records every notification it receives.
+ *
+ * Recording ALL THREE channels even when a suite reads one is deliberate: an
+ * event delivered on the wrong channel is a real defect of the data head, and a
+ * double that drops the other two turns it into silence on the one being
+ * watched.
+ *
+ * An override replaces a channel's recording rather than supplementing it, so
+ * the corresponding array stays empty — that is what makes an override usable
+ * as a barrier (rejecting, counting differently, throwing) rather than only as
+ * a spy.
+ */
+export declare function makeCapturingDataClient<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project>(overrides?: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>>): CapturingDataClient<TTransfer, TDiagnostic, TProject>;
+//# sourceMappingURL=data-doubles.d.ts.map

package/lib/testing/data-doubles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-doubles.d.ts","sourceRoot":"","sources":["../../src/testing/data-doubles.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAW,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AACrH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IACjC;;;;;;;;OAQG;IACH,OAAO,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpF;;;;OAIG;IACH,WAAW,IAAI,IAAI,CAAC;IACpB,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAwB3E;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB,CACjC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO;IAElC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IACtE,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;IACzE,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;IACrE,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC;CAC7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACpC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,EACnC,SAAS,GAAE,OAAO,CAAC,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAM,GAAG,mBAAmB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAsBtI"}