@hydranium/protocol 1.0.0-next.10

package/src/rpc/wire-prefix.ts

@@ -0,0 +1,48 @@
+/********************************************************************************
+ * 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 function assertValidMethodNamespace(methodNamespace: string, caller: string): void {
+   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.`
+   );
+}

package/src/testing/data-doubles.ts

@@ -0,0 +1,178 @@
+/********************************************************************************
+ * 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 { Emitter, 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 function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort {
+   const connections: MessageConnection[] = [];
+   const reported: { error: unknown; context: string }[] = [];
+   const disposeEmitter = new Emitter<void>();
+   return {
+      clientId: options.clientId ?? 'fake-data-port',
+      connections,
+      reported,
+      onDispose: disposeEmitter.event,
+      async connect(): Promise<MessageConnection> {
+         const connection = await options.connect();
+         connections.push(connection);
+         return connection;
+      },
+      reportError(error: unknown, context: string): void {
+         reported.push({ error, context });
+      },
+      fireDispose(): void {
+         disposeEmitter.fire(undefined);
+      },
+      dispose(): void {
+         disposeEmitter.dispose();
+      }
+   };
+}
+
+/** 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 function makeCapturingDataClient<
+   TTransfer extends TransferElement,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TProject extends Project = Project
+>(overrides: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>> = {}): CapturingDataClient<TTransfer, TDiagnostic, TProject> {
+   const updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[] = [];
+   const saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[] = [];
+   const projectsChanges: ProjectsChangedEvent<TProject>[] = [];
+   const client: DataClientProtocol<TTransfer, TDiagnostic, TProject> = {
+      onDocumentUpdated:
+         overrides.onDocumentUpdated ??
+         (event => {
+            updates.push(event);
+         }),
+      onDocumentSaved:
+         overrides.onDocumentSaved ??
+         (event => {
+            saves.push(event);
+         }),
+      onProjectsChanged:
+         overrides.onProjectsChanged ??
+         (event => {
+            projectsChanges.push(event);
+         })
+   };
+   return { client, updates, saves, projectsChanges };
+}

package/src/testing/fake-clock.ts

@@ -0,0 +1,106 @@
+/********************************************************************************
+ * 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 Clock, type Stopwatch, type Timed } from '../clock';
+import { Disposable } from '../util';
+
+/** A {@link Clock} whose time only moves when the test calls {@link FakeClock.advance}. */
+export interface FakeClock extends Clock {
+   /**
+    * Move virtual time forward by `ms`, firing every {@link Clock.setTimer}
+    * whose deadline falls within the window — in chronological order, each at
+    * its own deadline (so `now()` inside a callback reads the fire instant, not
+    * the advance target). Timers scheduled by a callback fire too if they fall
+    * within the same window.
+    */
+   advance(ms: number): void;
+}
+
+interface FakeTimer {
+   readonly at: number;
+   readonly callback: () => void;
+   disposed: boolean;
+   fired: boolean;
+}
+
+/**
+ * In-process {@link Clock} double for deterministic time. The real
+ * `SystemClock` has two underlying sources
+ * (`Date.now` for `now()`, `performance.now()` for the stopwatch); the fake
+ * collapses them onto ONE virtual time axis, so a single
+ * {@link FakeClock.advance} drives `now()`, every live stopwatch's elapsed, and
+ * any due timer together.
+ *
+ * Server-free and DI-free — lives in `@hydranium/protocol/testing` so every
+ * head can bind it without pulling in a server package.
+ */
+export function makeFakeClock(options: { now?: number } = {}): FakeClock {
+   let current = options.now ?? 0;
+   const timers: FakeTimer[] = [];
+
+   const makeStopwatch = (): Stopwatch => {
+      const start = current;
+      let lastLap = current;
+      let stopped: number | undefined;
+      return {
+         get elapsedMs(): number {
+            return (stopped ?? current) - start;
+         },
+         lap(): number {
+            const at = stopped ?? current;
+            const split = at - lastLap;
+            lastLap = at;
+            return split;
+         },
+         stop(): number {
+            if (stopped === undefined) {
+               stopped = current;
+            }
+            return stopped - start;
+         }
+      };
+   };
+
+   return {
+      now: () => current,
+      setTimer(callback: () => void, ms: number): Disposable {
+         const timer: FakeTimer = { at: current + ms, callback, disposed: false, fired: false };
+         timers.push(timer);
+         return Disposable.create(() => {
+            timer.disposed = true;
+         });
+      },
+      stopwatch: makeStopwatch,
+      measure: (<T>(callback: () => T | Promise<T>): Timed<T> | Promise<Timed<T>> => {
+         const stopwatch = makeStopwatch();
+         const result = callback();
+         if (result instanceof Promise) {
+            return (result as Promise<T>).then(value => ({ result: value, elapsedMs: stopwatch.elapsedMs }));
+         }
+         return { result: result as T, elapsedMs: stopwatch.elapsedMs };
+      }) as Clock['measure'],
+      advance(ms: number): void {
+         const target = current + ms;
+         // Fire due timers one at a time, re-scanning after each so a callback
+         // that schedules a nearer timer still fires within this window.
+         for (;;) {
+            const next = timers
+               .filter(timer => !timer.disposed && !timer.fired && timer.at <= target)
+               .sort((left, right) => left.at - right.at)[0];
+            if (!next) {
+               break;
+            }
+            current = next.at;
+            next.fired = true;
+            next.callback();
+         }
+         current = target;
+      }
+   };
+}

package/src/testing/harness.ts

@@ -0,0 +1,24 @@
+/********************************************************************************
+ * 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 uniform contract every framework test harness satisfies. A harness is
+ * a wired bundle around a system-under-test, driven through a seam; its full
+ * shape is `{ <subject>, <seam>, …captureArrays, dispose() }`. This marker
+ * pins the one member that is identical across every harness — `dispose()` —
+ * so teardown is always `harness.dispose()` regardless of which harness, and
+ * a `Harness` reference can release any of them without knowing its concrete
+ * type. Each concrete harness interface — per head, and per conformance driver
+ * port — `extends Harness` and adds its subject / seam / capture members on
+ * top.
+ */
+export interface Harness {
+   /** Release every resource the harness holds. Idempotent; the uniform teardown hook. */
+   dispose(): void;
+}

package/src/testing/index.ts

@@ -0,0 +1,26 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Subpath barrel for `@hydranium/protocol/testing` — the BROWSER-NEUTRAL shared
+// primitives: `makeFakeClock` (deterministic `Clock` double on one virtual time
+// axis), `waitFor` / `tick`, the client-side data-head doubles
+// (`makeFakeDataPort` / `makeCapturingDataClient`), and the `Harness` marker
+// interface every framework harness extends. Kept out of the main barrel so production bundles don't pull
+// the test scaffolding in by default; adopters opt in by importing from
+// `@hydranium/protocol/testing`.
+//
+// Neutrality is gated (`scripts/check-neutral-bundles.mjs`), which is why the
+// duplex transports are NOT here: a `PassThrough` pair is in their exported
+// type, so they cannot be made portable and live at `./testing/node` instead.
+// The same rule the package surface uses — the portable name is the short one.
+
+export * from './data-doubles';
+export * from './fake-clock';
+export * from './harness';
+export * from './wait-for';

package/src/testing/node/duplex-connection.ts

@@ -0,0 +1,50 @@
+/********************************************************************************
+ * 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 { StreamMessageReader, StreamMessageWriter, createMessageConnection, type MessageConnection } from 'vscode-jsonrpc/node';
+import { makeDuplexStreamPair } from './duplex-stream';
+
+/**
+ * Bidirectional in-process vscode-jsonrpc bridge — two MessageConnections
+ * crossed over a PassThrough pair, both already listening. The framework's
+ * standard in-process test transport.
+ *
+ * Typical use: wire a `DataServer` to `pair.left` and exercise it from a
+ * client proxy on `pair.right` (or vice versa). Call `dispose` at test
+ * teardown to release the underlying streams.
+ */
+export interface DuplexConnectionPair {
+   readonly left: MessageConnection;
+   readonly right: MessageConnection;
+   dispose(): void;
+}
+
+export function makeDuplexConnectionPair(): DuplexConnectionPair {
+   // `left` is the client side, `right` the server side: `clientToServer` is
+   // what `left` writes and `right` reads; `serverToClient` is what `right`
+   // writes and `left` reads.
+   const pair = makeDuplexStreamPair();
+   const { clientToServer, serverToClient } = pair;
+
+   const left = createMessageConnection(new StreamMessageReader(serverToClient), new StreamMessageWriter(clientToServer));
+   const right = createMessageConnection(new StreamMessageReader(clientToServer), new StreamMessageWriter(serverToClient));
+
+   left.listen();
+   right.listen();
+
+   return {
+      left,
+      right,
+      dispose(): void {
+         left.dispose();
+         right.dispose();
+         pair.dispose();
+      }
+   };
+}

package/src/testing/node/duplex-stream.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * 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 { PassThrough } from 'node:stream';
+
+/**
+ * A crossed pair of in-process `PassThrough` streams modelling one
+ * bidirectional client/server transport. Each `PassThrough` is itself both
+ * readable and writable: the side named first writes, the side named second
+ * reads off the same object. The shared substrate under the framework's
+ * in-process test transports — `makeDuplexConnectionPair` layers a
+ * `MessageConnection` pair on top.
+ */
+export interface DuplexStreamPair {
+   /** Client writes here; server reads here. */
+   readonly clientToServer: PassThrough;
+   /** Server writes here; client reads here. */
+   readonly serverToClient: PassThrough;
+   /** Destroy both streams. Idempotent. */
+   dispose(): void;
+}
+
+/**
+ * Build a fresh {@link DuplexStreamPair}. The two streams are independent;
+ * data written to one never appears on the other. Call `dispose` at test
+ * teardown to release them.
+ */
+export function makeDuplexStreamPair(): DuplexStreamPair {
+   const clientToServer = new PassThrough();
+   const serverToClient = new PassThrough();
+
+   let disposed = false;
+   return {
+      clientToServer,
+      serverToClient,
+      dispose(): void {
+         if (disposed) {
+            return;
+         }
+         disposed = true;
+         clientToServer.destroy();
+         serverToClient.destroy();
+      }
+   };
+}

package/src/testing/node/index.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Subpath barrel for `@hydranium/protocol/testing/node` — the test transports
+// that need a Node runtime: a crossed `PassThrough` pair and the in-process
+// `MessageConnection` bridge over it.
+//
+// Separate from `./testing` because a `PassThrough` is in `DuplexStreamPair`'s
+// exported type and `StreamMessageReader` comes from `vscode-jsonrpc/node`, so
+// neither can be made portable — and keeping them in the neutral barrel taints
+// every subpath that re-exports it, which is what made three of this repo's
+// `./testing` entries unbundleable for a browser while having no Node code of
+// their own.
+
+export * from './duplex-connection';
+export * from './duplex-stream';

package/src/testing/wait-for.ts

@@ -0,0 +1,94 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Two test primitives for awaiting in-process asynchrony (RPC notifications
+ * crossing the duplex wire, `DocumentBuilder` phase events, etc.) WITHOUT a
+ * flaky fixed sleep.
+ *
+ * Decision rule:
+ * - Asserting an effect **will** happen ("eventually N events / a build ran /
+ *   the doc reached a phase")? → {@link waitFor} with a predicate over the
+ *   observable. Non-racy: resolves the instant it is true, tolerates a slow CI.
+ * - Asserting an effect **did not / has not yet** happened ("no event for an
+ *   unsubscribed URI", "the gated call has not resolved")? → {@link tick}: a
+ *   negative cannot be polled, so yield the loop a bounded moment to give the
+ *   (unwanted) effect a chance, then assert its absence.
+ *
+ * Default to `waitFor`; reach for `tick` only when the assertion is an absence.
+ * A microtask flush (`await Promise.resolve()` / `queue-microtask`) is never the
+ * answer here — stream-delivered JSON-RPC notifications arrive on a macrotask/IO
+ * turn, after microtasks drain.
+ */
+
+/** Options for {@link waitFor}. */
+export interface WaitForOptions {
+   /** Reject after this many milliseconds if the predicate is still false. Default 2000. */
+   readonly timeoutMs?: number;
+   /** Poll the predicate every this-many milliseconds. Default 5. */
+   readonly intervalMs?: number;
+   /** Error message on timeout. Default a generic phrasing. */
+   readonly message?: string;
+}
+
+/**
+ * Resolve once `predicate()` returns true, polling at `intervalMs`; reject with
+ * `message` once `timeoutMs` elapses. The **non-racy** alternative to a fixed
+ * sleep for awaiting an asynchronous side effect that lands on an observable
+ * value.
+ *
+ * It resolves the instant the condition holds, so it is *faster* than a fixed
+ * delay on the happy path, and tolerates a slow event loop up to `timeoutMs`, so
+ * it does not flake under parallel CI where a fixed `setTimeout` can be starved
+ * past the test timeout.
+ *
+ * @example
+ * await proxy.updateModelDocument({ uri, clientId, model });
+ * await waitFor(() => harness.events.length === 1); // the notification crossed
+ * expect(harness.events[0].document.uri).toBe(uri);
+ */
+export function waitFor(predicate: () => boolean, options: WaitForOptions = {}): Promise<void> {
+   const timeoutMs = options.timeoutMs ?? 2000;
+   const intervalMs = options.intervalMs ?? 5;
+   const message = options.message ?? `Timed out after ${timeoutMs}ms waiting for a condition`;
+   if (predicate()) {
+      return Promise.resolve();
+   }
+   return new Promise<void>((resolve, reject) => {
+      const deadline = setTimeout(() => {
+         clearInterval(poll);
+         reject(new Error(message));
+      }, timeoutMs);
+      const poll = setInterval(() => {
+         if (predicate()) {
+            clearInterval(poll);
+            clearTimeout(deadline);
+            resolve();
+         }
+      }, intervalMs);
+   });
+}
+
+/**
+ * Yield the event loop for `ms` (default 10). The bounded counterpart to
+ * {@link waitFor}, for the rare assertion that something has NOT happened — a
+ * *negative* you cannot poll positively. Give async delivery a real chance to
+ * (wrongly) occur, then assert it did not.
+ *
+ * A fixed yield is unavoidable here, but the failure mode is a false-green, not
+ * the flaky-red a fixed delay causes on a positive wait.
+ *
+ * @example
+ * await proxy.saveModelDocument({ uri, clientId, model }); // no subscriber yet
+ * await tick();                  // give a (wrongly) fired event a chance to land
+ * expect(savedEvents).toHaveLength(0); // assert the ABSENCE
+ */
+export function tick(ms = 10): Promise<void> {
+   return new Promise<void>(resolve => setTimeout(resolve, ms));
+}