@hydranium/protocol 1.0.0-next.10

package/src/rpc/README.md

@@ -0,0 +1,163 @@
+# JSON-RPC primitives
+
+Exported from the package root, `@hydranium/protocol`. There is no
+`@hydranium/protocol/rpc` subpath: the package's `exports` map publishes `.`,
+`./client`, `./data` and `./testing` (plus their `./lib/*` twins), so importing
+this directory by path fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+Generic JSON-RPC primitives for typed protocol heads over a vscode-jsonrpc
+`MessageConnection`. This page is the reference; the shape of the pattern and
+why the two helpers mirror each other are in the
+[package README](../../README.md#the-rpc-pattern).
+
+## The pair
+
+### `bindRpcMethods(connection, target, methodNames, options?)`
+
+Server side. Registers each method named in `methodNames` on `target` as a
+handler on `connection` under the wire name `<methodNamespace><methodName>`.
+Notification methods (by the configured heuristic) register with
+`onNotification`; request methods register with `onRequest`. Returns a
+`Disposable` that tears down every registration.
+
+### `createRpcProxy<T>(connection, options?)`
+
+Caller side. Returns a JS `Proxy` typed as `T & RpcProxyLifecycle`. Each
+property access lowers to `sendRequest` (request methods) or
+`sendNotification` (notification methods, by the same heuristic) under the
+same wire-name composition. The lifecycle events (`onDidOpenConnection` /
+`onDidCloseConnection`) let proxy-only consumers react to the connection
+without holding the `MessageConnection` reference directly.
+
+## Shared semantics
+
+The options are deliberately mirrored across both helpers. Server and client
+MUST agree on each — a mismatch produces silent routing failures.
+
+### Wire-name composition: `methodNamespace`
+
+Both helpers compose the wire method name as
+`(methodNamespace ?? '') + methodName`. Adopters that share a connection
+across multiple protocol heads partition the wire surface with namespaced
+prefixes — the LSP analogy is `textDocument/*` / `workspace/*`. The
+data-server head ships with `'data-server/'` by default; adopters that
+combine the data-server with their own protocol head under one prefix pass
+their adopter namespace (e.g. `'myapp/'`) on both sides.
+
+Trailing-slash discipline is the adopter's responsibility — `'foo'` is a
+literal prefix, not interpreted as a namespace segment.
+
+### Notification discrimination: `isNotification`
+
+Default: property names starting with `'on'` followed by an uppercase letter
+are notifications. That matches the observer-pattern convention used
+throughout the framework's contracts (`onDocumentUpdated`, `onDocumentSaved`,
+etc.), while leaving request-shaped names that merely begin with the letters
+"on" (`onboardUser`, `onlineCheck`) routed as requests.
+
+For contracts that don't fit the convention, both helpers accept an
+`isNotification: (name: string) => boolean` override. Pass the same
+predicate on both sides — they must agree on every method, otherwise one
+end will register a request handler while the other sends a notification
+(no reply, silent timeout).
+
+### Single-arg-per-method convention
+
+Method dispatch passes JSON-RPC `params` to the target as a single argument.
+This is the framework's convention throughout — adopters define methods as
+`doStuff(args: { x, y })`, not `doStuff(x, y)`. The proxy enforces the
+convention at runtime: calling `proxy.doStuff(a, b)` with more than one
+argument throws (loose `any` / `unknown` proxies would otherwise drop extra
+args silently).
+
+### Deferred connection
+
+Both helpers accept `MessageConnection | Promise<MessageConnection>`. When
+the promise form is passed:
+
+- `createRpcProxy` — outgoing calls queue until the connection resolves,
+  then dispatch in order.
+- `bindRpcMethods` — handler registration queues until the connection
+  resolves, then attaches in one pass. The returned disposable cancels
+  queued work if disposed before resolve; otherwise it tears down the
+  attached handlers as usual.
+
+Wire-side safety: vscode-jsonrpc buffers nothing on the *receiving* side
+until `connection.listen()` is called, so adopters wiring handlers in
+`@postConstruct` (before the connection's other end opens) cannot drop a
+message that arrives during the queue window.
+
+## Reserved property names on `RpcProxy<T>`
+
+The proxy's `get` trap intercepts four property names. A wire method
+declared on `T` with one of these names would shadow the reserved
+behaviour instead of dispatching a wire call. Adopters defining wire
+methods should avoid:
+
+- `onDidOpenConnection` / `onDidCloseConnection` — return the lifecycle events
+- `then` — returns `undefined` so the proxy isn't auto-awaited by host-environment promise detection
+- `toJSON` — returns `undefined` so serialisers don't try to flatten the proxy
+
+Symbol property accesses also return `undefined` (the proxy is not
+iterable, not a thenable, not serialisable).
+
+## Example
+
+A minimal adopter contract paired across the wire:
+
+<!-- snippet-preamble
+import { bindRpcMethods, createRpcProxy } from '@hydranium/protocol';
+import type { MessageConnection } from 'vscode-jsonrpc';
+declare const connection: MessageConnection;
+-->
+
+```ts
+interface CounterApi {
+   increment(args: { by: number }): Promise<{ value: number }>;
+   onChanged(event: { value: number }): void;
+}
+
+// Server side — adopter implements the contract on a class:
+class CounterServer implements CounterApi {
+   private value = 0;
+   async increment(args: { by: number }): Promise<{ value: number }> {
+      this.value += args.by;
+      return { value: this.value };
+   }
+   onChanged(): void {
+      throw new Error('outbound notification — never called on the server');
+   }
+}
+
+const server = new CounterServer();
+const disposable = bindRpcMethods<CounterApi>(
+   connection,
+   server,
+   ['increment', 'onChanged'],
+   { methodNamespace: 'counter/' }
+);
+
+// Caller side — typed proxy over the same wire prefix:
+const proxy = createRpcProxy<CounterApi>(connection, { methodNamespace: 'counter/' });
+const { value } = await proxy.increment({ by: 3 });
+```
+
+The data-server head is built from these same two primitives rather than from
+a data-specific wrapper: `DataServer` binds its own contract and its client
+proxy in a single `createRpcProxy` call, over the method-name lists
+`@hydranium/protocol/data` publishes (`DATA_SERVER_PROTOCOL_METHODS` and its
+client dual). An adopter composing a head of their own follows the same shape.
+
+## Relationship to other RPC libraries
+
+- **vscode-jsonrpc directly.** These helpers are a thin typed shell over
+  `connection.sendRequest` / `onRequest` / `sendNotification` /
+  `onNotification`. Adopters wanting to opt out for one specific method
+  can always reach the connection underneath.
+- **LSP `RequestType` / `NotificationType` keys.** LSP-style codebases
+  declare each wire method as a typed symbol; this framework declares the
+  whole protocol as an interface and walks its keys. Interface-based is
+  the right call for a *generic* framework (one declaration, N adopters);
+  adopters coming from LSP looking for `RequestType` helpers won't find
+  them — the equivalent here is the contract interface plus its
+  method-name list (e.g. `DATA_SERVER_PROTOCOL_METHODS`).

package/src/rpc/bind-rpc-methods.ts

@@ -0,0 +1,180 @@
+/********************************************************************************
+ * 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 { MessageConnection } from 'vscode-jsonrpc';
+import type { LatencyCollector } from '../latency-collector';
+import { type Disposable, DisposableCollection } from '../util';
+import { defaultIsNotification } from './create-rpc-proxy';
+import { assertValidMethodNamespace } from './wire-prefix';
+
+/**
+ * Options controlling how method names are translated into wire-method
+ * registrations on the supplied connection. The defaults match
+ * `createRpcProxy` so the two helpers compose cleanly: an adopter
+ * defining a contract `T` registers handlers with `bindRpcMethods(conn, target, names, opts)`
+ * on one side and a typed proxy with `createRpcProxy<T>(conn, opts)` on
+ * the other — same wire prefix, same notification heuristic, no drift.
+ */
+export interface BindRpcMethodsOptions {
+   /**
+    * Prefix prepended to each method name to form the JSON-RPC wire string.
+    * Defaults to the empty string.
+    */
+   readonly methodNamespace?: string;
+
+   /**
+    * Predicate to discriminate notification methods from request methods.
+    * Notification methods register with `connection.onNotification`;
+    * request methods register with `connection.onRequest`. Default: `on`
+    * followed by an uppercase letter marks a notification, matching
+    * `createRpcProxy`.
+    */
+   readonly isNotification?: (methodName: string) => boolean;
+
+   /**
+    * When `true` (the default), every name in `methodNames` MUST exist
+    * as a function on `target` — missing names throw at attach time. This
+    * catches typos in adopter-supplied `additionalMethods` arrays where
+    * the names are string literals.
+    *
+    * Set to `false` to fall back to the silent-skip behaviour (useful
+    * for transitional method-name lists where some methods are not yet
+    * implemented on every target).
+    */
+   readonly requireAll?: boolean;
+
+   /**
+    * Invoked when a notification handler throws. Notifications have no reply
+    * channel, so the error cannot propagate back to the caller; this hook
+    * lets a caller that holds a logger route the failure somewhere
+    * structured. Receives the wire-method name and the thrown value.
+    *
+    * Defaults to `console.error` — the protocol layer carries no logger of
+    * its own, and a caller in a process whose stdout is not the JSON-RPC
+    * transport (the framework's IPC / socket heads) can leave the default in
+    * place. Callers binding handlers over a `--stdio` LSP connection should
+    * pass a hook that routes through `connection.console` instead.
+    */
+   readonly onNotificationError?: (wireName: string, error: unknown) => void;
+
+   /**
+    * When supplied, every dispatched handler is timed into this collector under
+    * its wire name (`<prefix><methodName>`) — the single RPC chokepoint the
+    * latency/throughput surface hooks, so no per-handler change is needed.
+    * Requests and notifications are both timed. Absent by default (no overhead).
+    */
+   readonly latency?: LatencyCollector;
+}
+
+/**
+ * Register each named method on `target` as a handler on `connection`
+ * under the wire-name `<prefix><methodName>`. Notification methods (by
+ * default `on` + an uppercase letter) register as fire-and-forget listeners; request
+ * methods register as request handlers and propagate the method's return
+ * value back to the caller.
+ *
+ * The returned disposable tears down every registered handler in one call —
+ * sufficient for the framework's lifecycle: bind handlers at construction,
+ * dispose at shutdown.
+ *
+ * Method dispatch always passes the JSON-RPC `params` to the target
+ * method as a single argument. This matches the single-arg-per-method
+ * convention used throughout the framework's typed contracts — adopters
+ * defining methods with multiple positional parameters would need a
+ * different binder.
+ *
+ * Errors thrown synchronously from a request handler — or surfaced as a
+ * rejected promise — propagate back to the caller through vscode-jsonrpc's
+ * standard error envelope. Errors from a notification handler cannot, and are
+ * routed to {@link BindRpcMethodsOptions.onNotificationError} instead.
+ *
+ * Accepts either a ready connection or a `Promise<MessageConnection>` —
+ * registrations queue until the connection resolves, then attach. The
+ * returned disposable can be invoked at any time: if it fires before the
+ * connection resolves the queued work is cancelled and never attaches;
+ * if it fires afterwards the registrations dispose normally. Mirrors
+ * `createRpcProxy`'s deferred-connection pattern so adopters can wire
+ * inbound handlers in `@postConstruct` before the underlying transport
+ * exists. Wire-side safety: no notifications can arrive before
+ * `connection.listen()` runs, so a not-yet-attached handler cannot drop
+ * a real message.
+ */
+export function bindRpcMethods<T extends object>(
+   connection: MessageConnection | Promise<MessageConnection>,
+   target: T,
+   methodNames: readonly (keyof T & string)[],
+   options: BindRpcMethodsOptions = {}
+): Disposable {
+   const methodNamespace = options.methodNamespace ?? '';
+   assertValidMethodNamespace(methodNamespace, 'bindRpcMethods');
+   const isNotification = options.isNotification ?? defaultIsNotification;
+   const requireAll = options.requireAll ?? true;
+   const onNotificationError =
+      options.onNotificationError ??
+      ((wireName: string, error: unknown) => console.error(`[bindRpcMethods] notification handler '${wireName}' threw:`, error));
+   const disposables = new DisposableCollection();
+   let cancelled = false;
+
+   const attach = (resolved: MessageConnection): void => {
+      if (cancelled) {
+         return;
+      }
+      for (const methodName of methodNames) {
+         const wireName = methodNamespace + methodName;
+         const method = target[methodName];
+         if (typeof method !== 'function') {
+            if (requireAll) {
+               throw new Error(
+                  `bindRpcMethods: method '${methodName}' is not a function on the target. ` +
+                     `Either fix the typo, implement the method, or pass { requireAll: false } to opt into silent-skip ` +
+                     'for transitional method-name lists.'
+               );
+            }
+            continue;
+         }
+         const bound = (method as (params: unknown) => unknown).bind(target);
+         // Time the dispatch at this one chokepoint when a collector is present.
+         const latency = options.latency;
+         const dispatch = latency ? (params: unknown): unknown => latency.time(wireName, () => bound(params)) : bound;
+
+         if (isNotification(methodName)) {
+            disposables.push(
+               resolved.onNotification(wireName, (params: unknown) => {
+                  try {
+                     dispatch(params);
+                  } catch (err: unknown) {
+                     onNotificationError(wireName, err);
+                  }
+               })
+            );
+         } else {
+            disposables.push(resolved.onRequest(wireName, async (params: unknown) => dispatch(params)));
+         }
+      }
+   };
+
+   if (connection instanceof Promise) {
+      void connection
+         .then(resolved => attach(resolved))
+         .catch(() => {
+            // Connection promise rejected — treat as never-resolved; nothing
+            // to register. Adopters observe transport failures through their
+            // own connection-construction error handling.
+         });
+   } else {
+      attach(connection);
+   }
+
+   return {
+      dispose(): void {
+         cancelled = true;
+         disposables.dispose();
+      }
+   };
+}

package/src/rpc/create-rpc-proxy.ts

@@ -0,0 +1,292 @@
+/********************************************************************************
+ * 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 { Emitter, type Event, type MessageConnection } from 'vscode-jsonrpc';
+import { type BindRpcMethodsOptions, bindRpcMethods } from './bind-rpc-methods';
+import { assertValidMethodNamespace } from './wire-prefix';
+
+/**
+ * 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 function defaultIsNotification(methodName: string): boolean {
+   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: string, args: unknown[]): void {
+   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.
+ */
+export function createRpcProxy<T extends object, TLocal extends object = never>(
+   connection: MessageConnection | Promise<MessageConnection>,
+   options: CreateRpcProxyOptions<TLocal> = {}
+): RpcProxy<T> {
+   const methodNamespace = options.methodNamespace ?? '';
+   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 = bindRpcMethods(connection, localTarget, localMethods, { methodNamespace, isNotification, latency: options.latency });
+      resolvedConnection.then(conn => conn.onClose(() => binding.dispose())).catch(() => undefined);
+   }
+
+   const onDidOpenConnectionEmitter = new Emitter<void>();
+   const onDidCloseConnectionEmitter = new Emitter<void>();
+   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) as T;
+   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: unknown[]): void => {
+               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: unknown[]): Promise<unknown> => {
+            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: unknown) => {
+                  if (err instanceof Error && capturedError.stack) {
+                     err.stack = `${err.stack ?? err.message}\nCaused by request from:\n${capturedError.stack}`;
+                  }
+                  throw err;
+               });
+         };
+      }
+   }) as RpcProxy<T>;
+}

package/src/rpc/index.ts

@@ -0,0 +1,16 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Generic JSON-RPC primitives shared across the framework's typed
+// protocol heads — see `data/data-protocol-methods.ts` for the
+// specialised composition.
+
+export * from './bind-rpc-methods';
+export * from './create-rpc-proxy';
+export * from './wire-prefix';