@hydranium/protocol 1.0.0-next.39 → 1.0.0-next.391

package/src/reconcile-write.ts

@@ -0,0 +1,131 @@
+/********************************************************************************
+ * 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 ConflictError, isConflictError } from './errors';
+import { type BaseVersion, type ModelVersion } from './model-service/base-version';
+import { type ConflictResolver } from './patch-merge';
+
+const DEFAULT_MAX_WRITES = 3;
+
+/** A model and the version of the text it was read from, which a write based on it names. */
+export interface VersionedModel<TModel> {
+   readonly model: TModel;
+   readonly baseVersion: ModelVersion;
+}
+
+/** The I/O and policy a {@link reconcileWrite} call needs. */
+export interface ReconcileWriteHooks<TModel> {
+   /**
+    * Write `model`. Called with the caller's own `baseVersion` first, with the
+    * refetch's on a merged write, and with `'any'` for a merge that refetched
+    * nothing, where the resolver has already decided to win.
+    */
+   persist(model: TModel, baseVersion: BaseVersion): Promise<void>;
+   /**
+    * Current server-side model, or `undefined` when unavailable. Its version is
+    * read in the tick its text is: a later one lets a merged write overwrite an
+    * edit the merge never saw.
+    */
+   refetch(): Promise<VersionedModel<TModel> | undefined>;
+   /** The last in-sync model the user's intent is measured against. */
+   readonly base: TModel;
+   /** Asked for each conflict while writes remain. Its refetch callback runs {@link refetch} only when called. */
+   readonly conflictResolver: ConflictResolver;
+   /** Writes, the first included, after which a still-conflicting edit is dropped; 3 when absent. */
+   readonly maxWrites?: number;
+   /** Runs when the refetch is unavailable; absent, the edit is left unwritten. */
+   onUnavailable?(model: TModel, conflict: ConflictError): Promise<void>;
+}
+
+/**
+ * What {@link reconcileWrite} did. Every status but `persisted` follows a
+ * conflict, and carries the last one and the writes made, the first included.
+ */
+export type ReconcileWriteOutcome =
+   /** The first write landed. */
+   | { readonly status: 'persisted' }
+   | {
+        /**
+         * `merged`: a merged write landed. `already-applied`: the refetch
+         * already held the edit, so nothing more was written. `unchanged`: the
+         * edit was empty, so the caller is behind the server. `conflict`: the
+         * resolver found a same-path collision. `dropped`: the writes ran out.
+         * `unavailable`: the refetch produced nothing and
+         * {@link ReconcileWriteHooks.onUnavailable} ran.
+         */
+        readonly status: 'merged' | 'already-applied' | 'unchanged' | 'conflict' | 'dropped' | 'unavailable';
+        /** The last conflict a write raised, which on `merged` is the one before the write that landed. */
+        readonly conflict: ConflictError;
+        /** Writes made, the first included. `dropped` is reported once they reach {@link ReconcileWriteHooks.maxWrites}. */
+        readonly writes: number;
+     };
+
+/**
+ * Persist `model`, and on a `ConflictError` reconcile the user's `base → model`
+ * intent onto the refetched server model and write the merge, gated on the
+ * refetch's version, again on each conflict up to `maxWrites` writes. A
+ * non-conflict error is re-thrown.
+ */
+export async function reconcileWrite<TModel extends object>(
+   model: TModel,
+   baseVersion: BaseVersion,
+   hooks: ReconcileWriteHooks<TModel>
+): Promise<ReconcileWriteOutcome> {
+   let candidate = model;
+   let candidateBaseVersion = baseVersion;
+   let previous: ConflictError | undefined;
+   const maxWrites = hooks.maxWrites ?? DEFAULT_MAX_WRITES;
+   for (let writes = 1; ; writes++) {
+      const conflict = await persistOrConflict(hooks, candidate, candidateBaseVersion);
+      if (!conflict) {
+         return previous ? { status: 'merged', conflict: previous, writes } : { status: 'persisted' };
+      }
+      previous = conflict;
+      if (writes >= maxWrites) {
+         return { status: 'dropped', conflict, writes };
+      }
+      let refetched: VersionedModel<TModel> | undefined;
+      const outcome = await hooks.conflictResolver.resolve(hooks.base, model, async () => {
+         refetched = await hooks.refetch();
+         return refetched?.model;
+      });
+      switch (outcome.status) {
+         case 'merged':
+            candidate = outcome.merged;
+            candidateBaseVersion = refetched?.baseVersion ?? 'any';
+            continue;
+         case 'already-applied':
+            return { status: 'already-applied', conflict, writes };
+         case 'no-op':
+            return { status: 'unchanged', conflict, writes };
+         case 'conflict':
+            return { status: 'conflict', conflict, writes };
+         case 'unavailable':
+            await hooks.onUnavailable?.(model, conflict);
+            return { status: 'unavailable', conflict, writes };
+      }
+   }
+}
+
+/** The `ConflictError` the write raised, or `undefined` when it landed. */
+async function persistOrConflict<TModel>(
+   hooks: ReconcileWriteHooks<TModel>,
+   model: TModel,
+   baseVersion: BaseVersion
+): Promise<ConflictError | undefined> {
+   try {
+      await hooks.persist(model, baseVersion);
+      return undefined;
+   } catch (err: unknown) {
+      if (!isConflictError(err)) {
+         throw err;
+      }
+      return err;
+   }
+}

package/src/rpc/README.md

@@ -1,9 +1,8 @@
 # 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`.
+`@hydranium/protocol/rpc` subpath: the package's `exports` map declares none,
+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
@@ -44,8 +43,8 @@ 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.
+A namespace ends in `/` or is empty: `bindRpcMethods` and `createRpcProxy`
+throw a `TypeError` for `'foo'`.
 
 ### Notification discrimination: `isNotification`
 
@@ -95,7 +94,8 @@ 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
+- `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

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

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { ResponseError, type MessageConnection } from 'vscode-jsonrpc';
+import { isResponseError } from '../errors';
 import type { LatencyCollector } from '../latency-collector';
 import { type Disposable, DisposableCollection } from '../util';
 import { defaultIsNotification } from './create-rpc-proxy';
@@ -97,9 +98,17 @@ export interface BindRpcMethodsOptions {
    readonly renderErrorMessage?: (error: ResponseError<unknown>) => string;
 }
 
-/** The rejection to throw in place of `err`, with its message rendered. */
-function renderRejection(err: unknown, render: (error: ResponseError<unknown>) => string): unknown {
-   return err instanceof ResponseError ? new ResponseError(err.code, render(err), err.data) : err;
+/**
+ * The rejection to throw in place of `err`. A `ResponseError` from another copy
+ * of `vscode-jsonrpc` is rebuilt on this package's, since a connection keeps the
+ * code only of its own copy's errors; one from this copy is thrown as is, so a
+ * subclass keeps its `toJson`, unless `render` rewrites its message.
+ */
+function renderRejection(err: unknown, render?: (error: ResponseError<unknown>) => string): unknown {
+   if (!isResponseError(err) || (!render && err instanceof ResponseError)) {
+      return err;
+   }
+   return new ResponseError(err.code, render ? render(err) : err.message, err.data);
 }
 
 /**
@@ -121,8 +130,12 @@ function renderRejection(err: unknown, render: (error: ResponseError<unknown>) =
  *
  * 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, with the message rendered when
- * {@link BindRpcMethodsOptions.renderErrorMessage} is supplied. Errors from a
+ * standard error envelope, its message rendered when
+ * {@link BindRpcMethodsOptions.renderErrorMessage} is supplied. A
+ * `ResponseError` from another copy of `vscode-jsonrpc` is rebuilt on this
+ * package's copy, so its code and data reach the caller when `connection` comes
+ * from that copy too, as the framework's own connections do; over a connection
+ * from another copy the caller receives a generic `InternalError`. Errors from a
  * notification handler cannot propagate, and are routed to
  * {@link BindRpcMethodsOptions.onNotificationError} instead.
  *
@@ -189,9 +202,6 @@ export function bindRpcMethods<T extends object>(
             const render = options.renderErrorMessage;
             disposables.push(
                resolved.onRequest(wireName, async (params: unknown) => {
-                  if (!render) {
-                     return dispatch(params);
-                  }
                   try {
                      // Awaited inside the try, or a rejected promise escapes it.
                      return await dispatch(params);

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

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { Emitter, type Event, type MessageConnection } from 'vscode-jsonrpc';
+import { reviveProtocolError } from '../errors';
 import { type BindRpcMethodsOptions, bindRpcMethods } from './bind-rpc-methods';
 import { assertValidMethodNamespace } from './wire-prefix';
 
@@ -198,6 +199,9 @@ function assertSingleArg(wireName: string, args: unknown[]): void {
  * params, results and errors, and a second layer here would double every
  * traced line.
  *
+ * A rejection whose code names one of the framework's typed errors is rethrown
+ * as that class, through {@link reviveProtocolError}.
+ *
  * 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
@@ -293,7 +297,8 @@ export function createRpcProxy<T extends object, TLocal extends object = never>(
             const capturedError = new Error(`RPC request '${wireName}' failed`);
             return resolvedConnection
                .then(connection => connection.sendRequest(wireName, args[0]))
-               .catch((err: unknown) => {
+               .catch((rejection: unknown) => {
+                  const err = reviveProtocolError(rejection);
                   if (err instanceof Error && capturedError.stack) {
                      err.stack = `${err.stack ?? err.message}\nCaused by request from:\n${capturedError.stack}`;
                   }

package/src/rpc/index.ts

@@ -13,4 +13,5 @@
 
 export * from './bind-rpc-methods';
 export * from './create-rpc-proxy';
+export * from './send-by-method-name';
 export * from './wire-prefix';

package/src/rpc/send-by-method-name.ts

@@ -0,0 +1,140 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { CancellationToken } from 'vscode-jsonrpc';
+
+/**
+ * `connection` with `sendRequest` and `sendNotification` sending a typed message
+ * by its method name, so it survives a message type built by another copy of
+ * `vscode-jsonrpc`. Wrap a connection wherever it is handed to code that sends
+ * another copy's typed messages, GLSP's clients and launchers in particular.
+ *
+ * **Why an install holds several copies.** Upstream pins exactly:
+ * - `@eclipse-glsp/*` 2.x pin `vscode-jsonrpc` `8.2.0`, and npm can nest a copy
+ *   under each GLSP package, so GLSP's packages can split from each other: a
+ *   connection one of them creates rejects the typed messages another builds.
+ *   GLSP's upgrade to 9.x, which could let it share the framework's copy, is
+ *   open as https://github.com/eclipse-glsp/glsp/issues/1720.
+ * - `vscode-languageserver@10.0.1` pins `vscode-languageserver-protocol`
+ *   `3.18.1`, which pins `vscode-jsonrpc` `9.0.0`.
+ * - Theia brings protocol `3.17.5` and with it `vscode-jsonrpc` 8.
+ *
+ * npm hoists one version per name and nests the rest. `overrides` are read from
+ * the root manifest alone and never ship with a package, so the framework cannot
+ * collapse an adopter's tree.
+ *
+ * **What breaks across copies.**
+ * - Sending: a connection compares a typed message's parameter structure with
+ *   its own copy's `ParameterStructures.auto` singleton by identity, so a
+ *   `RequestType` or `NotificationType` built by another copy throws
+ *   `Unknown parameter structure auto`. GLSP sends typed messages, in
+ *   `BaseJsonrpcGLSPClient` and in `JsonrpcClientProxy.process`.
+ *   `vscode-languageserver`'s connection resends by method name already, which
+ *   is why LSP sends are unaffected.
+ * - Types: `ParameterStructures` has a private member, so TypeScript treats each
+ *   copy's `MessageConnection` as a different type.
+ * - Errors: a connection keeps a thrown `ResponseError`'s code and data only
+ *   when the error is an instance of its own copy's class, and sends a returned
+ *   one of another copy as a successful result.
+ *
+ * **What is copy-safe.** Receiving a typed message from another copy, since the
+ * receive path compares only against its own `byName` and `byPosition`. With
+ * sends by method name, the LSP, data and GLSP heads run over a tree whose GLSP
+ * packages keep `vscode-jsonrpc` `8.2.0`.
+ *
+ * **How it works.** A `Proxy` whose `sendRequest` and `sendNotification` pass the
+ * typed message's `method` string; every other member is the connection's own.
+ * The parameters go out as the typed send packs them: the first
+ * `numberOfParams`, missing ones `null`, and a request's cancellation token
+ * from the position after them. Sent by method name, a single parameter goes by
+ * name when it is an object and by position otherwise, which matches `auto` and
+ * `byName` with an object, as `vscode-languageserver-protocol`'s types use it. A
+ * `byPosition` object or a `byName` non-object throws rather than going out in
+ * another shape, the packing read from the type's `toString()` since it cannot
+ * be compared by identity. So wrapping narrows what a connection accepts: its
+ * own copy sends such a type unwrapped. The result is typed as whichever copy's
+ * connection its context expects, or as `connection`'s own type without one.
+ * That type is the caller's assertion: it holds for the members both copies
+ * share, since the sends go by name and the receives are copy-safe.
+ *
+ * **Where it stops.** Errors: a rejection it produces is still its own copy's
+ * `ResponseError`, so recognise errors with `isResponseError`, and build a
+ * connection whose errors must keep their code from the framework's copy.
+ *
+ * See https://github.com/eclipse-emfcloud/hydranium/issues/279.
+ */
+export function sendByMethodName<
+   In extends {
+      sendRequest<R>(method: string, ...params: unknown[]): Promise<R>;
+      sendNotification(method: string, ...params: unknown[]): Promise<void>;
+   },
+   Out extends {
+      sendRequest<R>(method: string, ...params: unknown[]): Promise<R>;
+      sendNotification(method: string, ...params: unknown[]): Promise<void>;
+   } = In
+>(connection: In): Out {
+   const sendRequest = (type: string | TypedMessage, ...params: unknown[]) =>
+      typeof type === 'string'
+         ? connection.sendRequest(type, ...params)
+         : connection.sendRequest(type.method, ...argsOf(type, params, true));
+   const sendNotification = (type: string | TypedMessage, ...params: unknown[]) =>
+      typeof type === 'string'
+         ? connection.sendNotification(type, ...params)
+         : connection.sendNotification(type.method, ...argsOf(type, params, false));
+   const wrapped: Pick<In, 'sendRequest' | 'sendNotification'> = new Proxy(connection, {
+      get(target, property, receiver) {
+         if (property === 'sendRequest') {
+            return sendRequest;
+         }
+         if (property === 'sendNotification') {
+            return sendNotification;
+         }
+         return Reflect.get(target, property, receiver);
+      }
+   });
+   // Typed as the connection its context expects, which the doc above justifies.
+   return wrapped as Out;
+}
+
+/** A typed message as any copy of `vscode-jsonrpc` builds it, read by shape rather than identity. */
+interface TypedMessage {
+   readonly method: string;
+   readonly numberOfParams: number;
+   readonly parameterStructures: { toString(): string };
+}
+
+/** Whether `vscode-jsonrpc` sends `param` by name under `auto`. */
+function isNamedParam(param: unknown): boolean {
+   return param !== undefined && param !== null && !Array.isArray(param) && typeof param === 'object';
+}
+
+/**
+ * The arguments that send `type` by method name with the typed send's params:
+ * the first `numberOfParams` of `params`, missing ones `null`, then a request's
+ * cancellation token, which the typed send takes from that position. A request
+ * always ends in a token, `CancellationToken.None` when it has none, since a
+ * send by method name takes a token-shaped last argument for its token. Throws
+ * for the one-parameter packing a send by method name cannot express.
+ */
+function argsOf(type: TypedMessage, params: unknown[], isRequest: boolean): unknown[] {
+   const args = Array.from({ length: type.numberOfParams }, (_, i) => (i < params.length ? params[i] : null));
+   if (type.numberOfParams === 1) {
+      const packing = String(type.parameterStructures);
+      if ((packing === 'byPosition' && isNamedParam(args[0])) || (packing === 'byName' && !isNamedParam(args[0]))) {
+         throw new Error(
+            `sendByMethodName cannot send '${type.method}' ${packing}: by method name, a single object goes by name and anything else by position.`
+         );
+      }
+   }
+   if (!isRequest) {
+      return args;
+   }
+   const token = params[type.numberOfParams];
+   return [...args, CancellationToken.is(token) ? token : CancellationToken.None];
+}

package/src/save-text-document.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { RequestType } from 'vscode-jsonrpc';
+
+/**
+ * LSP's `VersionedTextDocumentIdentifier`, declared field by field: this
+ * package carries no LSP dependency, and the fields are LSP's own.
+ */
+export interface SaveTextDocumentParams {
+   readonly textDocument: { readonly uri: string; readonly version: number };
+}
+
+/**
+ * Ask the LSP head to persist the text it holds for a document, which it
+ * answers with `null` once the text is written. LSP itself has none: its
+ * `didSave` reports a write the editor made, so a host whose files only the
+ * server holds saves through this.
+ *
+ * It travels the connection the `didChange`s travel, so it arrives after
+ * them. The server refuses it with a `ConflictError` unless the version is the
+ * one the editor last declared and its buffer holds the server's current
+ * text, which a `workspace/applyEdit` still in flight breaks.
+ *
+ * A server that answers it advertises it as
+ * `ServerCapabilities.experimental[SaveTextDocumentRequest.method] = true`;
+ * a client checks that before sending, since a server without a handler
+ * answers `MethodNotFound`.
+ */
+export namespace SaveTextDocumentRequest {
+   export const method = 'hydranium/saveTextDocument';
+   export const type = new RequestType<SaveTextDocumentParams, null, void>(method);
+}

package/src/testing/data-doubles.ts

@@ -33,15 +33,19 @@
 
 import { Emitter, type MessageConnection } from 'vscode-jsonrpc';
 import type { DataPort } from '../client/data-port';
+import { DATA_CLIENT_PROTOCOL_METHODS } from '../data/data-protocol-methods';
 import type { DataClientProtocol } from '../data/data-server-protocol';
 import type {
    ProjectsChangedEvent,
    TransferDocumentDeletedEvent,
+   TransferDocumentDirtyChangedEvent,
    TransferDocumentSavedEvent,
    TransferDocumentsBuiltEvent,
    TransferDocumentUpdatedEvent
 } from '../data/events';
+import type { Logger } from '../logger';
 import type { ResolvedMessage } from '../messages/primitives';
+import type { RpcProxyLifecycle } from '../rpc/create-rpc-proxy';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -56,15 +60,14 @@ export interface FakeDataPortOptions {
     *
     * Throwing (or rejecting) here is the transport-construction failure path,
     * which the consumer surfaces through {@link FakeDataPort.reported}.
+    *
+    * The double disposes none of these connections and goes on connecting
+    * after its dispose, where a real port releases its connection and refuses:
+    * the test owns them.
     */
    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;
+   /** The port's {@link DataPort.logger}. */
+   logger?: Logger;
 }
 
 /** A {@link DataPort} that records what passed through it. */
@@ -107,9 +110,9 @@ export function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort {
    const reported: { error: unknown; message: ResolvedMessage }[] = [];
    const disposeEmitter = new Emitter<void>();
    return {
-      clientId: options.clientId ?? 'fake-data-port',
       connections,
       reported,
+      logger: options.logger,
       onDispose: disposeEmitter.event,
       async connect(): Promise<MessageConnection> {
          const connection = await options.connect();
@@ -128,24 +131,72 @@ export function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort {
    };
 }
 
+type UpperLetter =
+   | 'A'
+   | 'B'
+   | 'C'
+   | 'D'
+   | 'E'
+   | 'F'
+   | 'G'
+   | 'H'
+   | 'I'
+   | 'J'
+   | 'K'
+   | 'L'
+   | 'M'
+   | 'N'
+   | 'O'
+   | 'P'
+   | 'Q'
+   | 'R'
+   | 'S'
+   | 'T'
+   | 'U'
+   | 'V'
+   | 'W'
+   | 'X'
+   | 'Y'
+   | 'Z';
+
+/**
+ * A notification name `TClient` adds to {@link DataClientProtocol}. Limited to
+ * `on` plus a letter A–Z, the names the proxy sends as notifications; any other
+ * name would be bound as a request. The {@link RpcProxyLifecycle} names are
+ * excluded too: the proxy returns its own events for them and sends nothing.
+ */
+export type AdditionalClientMethod<TClient> = Exclude<keyof TClient, keyof DataClientProtocol<TransferElement> | keyof RpcProxyLifecycle> &
+   `on${UpperLetter}${string}`;
+
 /** A {@link DataClientProtocol} plus the arrays it records into. */
 export interface CapturingDataClient<
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TClient extends DataClientProtocol<TTransfer, TDiagnostic, TProject> = DataClientProtocol<TTransfer, TDiagnostic, TProject>
 > {
    /** The client to hand to a `DataSession` or bind as an RPC `localTarget`. */
-   readonly client: DataClientProtocol<TTransfer, TDiagnostic, TProject>;
+   readonly client: TClient;
    /** Every `onDocumentUpdated` event, in arrival order. */
    readonly updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[];
    /** Every `onDocumentSaved` event, in arrival order. */
    readonly saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[];
+   /** Every `onDocumentDirtyChanged` event, in arrival order. */
+   readonly dirtyChanges: TransferDocumentDirtyChangedEvent[];
    /** Every `onDocumentDeleted` event, in arrival order. */
    readonly deletions: TransferDocumentDeletedEvent[];
    /** Every `onDocumentsBuilt` event, in arrival order. */
    readonly builds: TransferDocumentsBuiltEvent[];
    /** Every `onProjectsChanged` event, in arrival order. */
    readonly projectsChanges: ProjectsChangedEvent<TProject>[];
+   /**
+    * Every event of each additional client method, keyed by method, in arrival
+    * order. A method of `TClient` left out of `additionalClientMethods` has no
+    * entry.
+    */
+   readonly additionalNotifications: {
+      readonly [K in AdditionalClientMethod<TClient>]: TClient[K] extends (event: infer TEvent) => void ? TEvent[] : never;
+   };
 }
 
 /**
@@ -160,43 +211,92 @@ export interface CapturingDataClient<
  * 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.
+ *
+ * `additionalClientMethods` names the notifications `TClient` adds to
+ * {@link DataClientProtocol}. Each is recorded and overridable the same way;
+ * one left out is not on the client at all, and overriding it throws, since
+ * nothing would call the override.
  */
 export function makeCapturingDataClient<
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
-   TProject extends Project = Project
->(overrides: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>> = {}): CapturingDataClient<TTransfer, TDiagnostic, TProject> {
+   TProject extends Project = Project,
+   TClient extends DataClientProtocol<TTransfer, TDiagnostic, TProject> = DataClientProtocol<TTransfer, TDiagnostic, TProject>
+>(
+   overrides: Partial<TClient> = {},
+   additionalClientMethods: readonly AdditionalClientMethod<TClient>[] = []
+): CapturingDataClient<TTransfer, TDiagnostic, TProject, TClient> {
+   const bound = new Set<string>([...DATA_CLIENT_PROTOCOL_METHODS, ...additionalClientMethods]);
+   for (const name of Object.keys(overrides)) {
+      if (!bound.has(name)) {
+         throw new Error(
+            `Override '${name}' is neither a DataClientProtocol method nor listed in additionalClientMethods, so nothing would call it.`
+         );
+      }
+   }
+   const frameworkOverrides: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>> = overrides;
    const updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[] = [];
    const saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[] = [];
+   const dirtyChanges: TransferDocumentDirtyChangedEvent[] = [];
    const deletions: TransferDocumentDeletedEvent[] = [];
    const builds: TransferDocumentsBuiltEvent[] = [];
    const projectsChanges: ProjectsChangedEvent<TProject>[] = [];
-   const client: DataClientProtocol<TTransfer, TDiagnostic, TProject> = {
+   const frameworkClient: DataClientProtocol<TTransfer, TDiagnostic, TProject> = {
       onDocumentUpdated:
-         overrides.onDocumentUpdated ??
+         frameworkOverrides.onDocumentUpdated ??
          (event => {
             updates.push(event);
          }),
       onDocumentSaved:
-         overrides.onDocumentSaved ??
+         frameworkOverrides.onDocumentSaved ??
          (event => {
             saves.push(event);
          }),
+      onDocumentDirtyChanged:
+         frameworkOverrides.onDocumentDirtyChanged ??
+         (event => {
+            dirtyChanges.push(event);
+         }),
       onDocumentDeleted:
-         overrides.onDocumentDeleted ??
+         frameworkOverrides.onDocumentDeleted ??
          (event => {
             deletions.push(event);
          }),
       onDocumentsBuilt:
-         overrides.onDocumentsBuilt ??
+         frameworkOverrides.onDocumentsBuilt ??
          (event => {
             builds.push(event);
          }),
       onProjectsChanged:
-         overrides.onProjectsChanged ??
+         frameworkOverrides.onProjectsChanged ??
          (event => {
             projectsChanges.push(event);
          })
    };
-   return { client, updates, saves, deletions, builds, projectsChanges };
+   const additionalNotifications: Record<string, unknown[]> = {};
+   const additionalHandlers: Record<string, unknown> = {};
+   for (const method of additionalClientMethods) {
+      const events: unknown[] = [];
+      additionalNotifications[method] = events;
+      additionalHandlers[method] =
+         overrides[method] ??
+         ((event: unknown) => {
+            events.push(event);
+         });
+   }
+   return {
+      client: { ...frameworkClient, ...additionalHandlers } as unknown as TClient,
+      updates,
+      saves,
+      dirtyChanges,
+      deletions,
+      builds,
+      projectsChanges,
+      additionalNotifications: additionalNotifications as CapturingDataClient<
+         TTransfer,
+         TDiagnostic,
+         TProject,
+         TClient
+      >['additionalNotifications']
+   };
 }