@hydranium/protocol 1.0.0-next.18 → 1.0.0-next.181

package/src/patch-merge.ts

@@ -7,34 +7,43 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { applyPatch, compare, deepClone, getValueByPointer, type Operation as JsonPatchOperation } from 'fast-json-patch';
+import {
+   _areEquals,
+   applyPatch,
+   compare,
+   deepClone,
+   getValueByPointer,
+   type Operation as JsonPatchOperation,
+   unescapePathComponent
+} from 'fast-json-patch';
 
 /**
- * Augment a user-intent JSON patch (computed `baseline → attempted`) with
+ * Augment a user-intent JSON patch (computed `base → ours`) with
  * `test` ops so a strict `applyPatch` against freshly-fetched server state
  * fails loudly when a foreign writer changed a path the user also changed.
  *
  * `fast-json-patch`'s `validateOperation: true` validates op structure and
  * path resolvability but NOT the pre-existing value — a plain `replace` /
  * `remove` silently overwrites whatever the foreign writer put there. For each
- * `replace` / `remove` op we prepend a `test` op carrying the baseline value at
+ * `replace` / `remove` op we prepend a `test` op carrying the base value at
  * that path, so a same-path divergence becomes a `TEST_OPERATION_FAILED` throw.
  * The caller treats that as a real field-level conflict (drop + refetch) rather
  * than silently clobbering the foreign edit.
  *
- * `add` ops are left unguarded: the path is new, so there is no baseline value
- * to test against, and add-vs-add overlaps are out of scope for this floor.
+ * `add` ops get no `test` op: the path is new, so there is no base value
+ * to test. {@link reconcileByPatchReplay} checks them against theirs
+ * instead; a caller applying this patch itself does not get that check.
  *
  * Used behind the framework's `ConflictError` contract by every reconcile
  * path — the GLSP recording command's undo/redo and forward-write, via
  * {@link ReconcilingConflictResolver}, and an adopter's form-widget save — so
  * they share one collision-detection rule.
  */
-export function augmentWithTestOps(baseline: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[] {
+export function augmentWithTestOps(base: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[] {
    const augmented: JsonPatchOperation[] = [];
    for (const op of userPatch) {
       if (op.op === 'replace' || op.op === 'remove') {
-         augmented.push({ op: 'test', path: op.path, value: getValueByPointer(baseline, op.path) });
+         augmented.push({ op: 'test', path: op.path, value: getValueByPointer(base, op.path) });
       }
       augmented.push(op);
    }
@@ -42,39 +51,38 @@ export function augmentWithTestOps(baseline: object, userPatch: ReadonlyArray<Js
 }
 
 /**
- * Outcome of {@link reconcileByPatchReplay}. The caller persists / re-baselines
- * on `merged`, drops + surfaces the `fresh` root on `conflict`, and decides its
- * own fallback (e.g. force-retry) on `no-op` / `unavailable`.
+ * Outcome of {@link reconcileByPatchReplay}. The caller persists `merged` and
+ * takes it as the new base, drops + surfaces the `theirs` root on `conflict`, and
+ * decides its own fallback (e.g. force-retry) on `no-op` / `unavailable`.
  */
 export type ReconcileOutcome<T> =
    | {
         /** The replay succeeded: the foreign writer touched no path the user did. */
         status: 'merged';
         /**
-         * A fresh root built on the refetched server state, carrying both
-         * intents. It is NOT the caller's `attempted` root — re-baseline on
-         * this value, or the next write diffs against state the server never
-         * had.
+         * A new root built on theirs, carrying both intents. It is NOT the
+         * caller's `ours` root — take this value as the new base, or the next
+         * write diffs against state the server never had.
          */
         merged: T;
      }
    | {
         /**
-         * The user's root already equalled the baseline, so the version gate
+         * The user's root already equalled the base, so the version gate
          * fired on drift that changed nothing. No refetch was performed and
          * there is nothing to persist — retrying the same write reproduces it.
          */
         status: 'no-op';
      }
    | {
-        /** A guarded `test` op tripped: user and foreign writer touched one path. */
+        /** User and foreign writer changed one path, or both added the same element or key. */
         status: 'conflict';
         /**
          * The server's current root, refetched and unmodified — the user's
          * intent was NOT applied to it. Surface it and drop the write; treating
          * it as a merge result silently discards what the user typed.
          */
-        fresh: T;
+        theirs: T;
      }
    | {
         /**
@@ -87,39 +95,84 @@ export type ReconcileOutcome<T> =
 
 /**
  * Shared three-way reconcile for a `ConflictError`: diff the user's intent
- * (`baseline → attempted`), refetch the server's current root, and replay the
+ * (`base → ours`), refetch the server's current root (theirs), and replay the
  * intent on top under strict, {@link augmentWithTestOps}-guarded `applyPatch`.
  *
- * - `no-op` — the user's root equals the baseline, so the gate fired on a
+ * - `no-op` — the user's root equals the base, so the gate fired on a
  *   benign version drift; nothing to replay (refetch is skipped).
  * - `unavailable` — the refetch produced nothing; caller falls back.
  * - `merged` — the foreign writer touched only paths the user did not; the
  *   merged root carries both intents.
- * - `conflict` — a same-path divergence tripped a `test` op; caller drops the
- *   write and surfaces `fresh`.
+ * - `conflict` — a same-path divergence tripped a `test` op, or an `add`
+ *   collides with one the foreign writer made; caller drops the write and
+ *   surfaces `theirs`.
  *
  * I/O is the caller's: `refetch` supplies the current root, and applying the
- * `merged` result (update vs save, re-baseline, UI refresh) stays at the call
+ * `merged` result (update vs save, new base, UI refresh) stays at the call
  * site so form and GLSP paths keep their own persistence semantics.
  */
 export async function reconcileByPatchReplay<T extends object>(
-   baseline: T,
-   attempted: T,
+   base: T,
+   ours: T,
    refetch: () => Promise<T | undefined>
 ): Promise<ReconcileOutcome<T>> {
-   const userPatch = compare(baseline, attempted);
+   const userPatch = compare(base, ours);
    if (userPatch.length === 0) {
       return { status: 'no-op' };
    }
-   const fresh = await refetch();
-   if (!fresh) {
+   const theirs = await refetch();
+   if (!theirs) {
       return { status: 'unavailable' };
    }
+   if (addsCollide(base, theirs, userPatch)) {
+      return { status: 'conflict', theirs };
+   }
    try {
-      const merged = applyPatch(deepClone(fresh), augmentWithTestOps(baseline, userPatch), true).newDocument;
+      const merged = applyPatch(deepClone(theirs), augmentWithTestOps(base, userPatch), true).newDocument;
       return { status: 'merged', merged };
    } catch {
-      return { status: 'conflict', fresh };
+      return { status: 'conflict', theirs };
+   }
+}
+
+/**
+ * Whether an `add` of `userPatch` collides with one the foreign writer made:
+ * it inserts a value into an array that `theirs` holds more often than
+ * `base` did, or it adds an object key that `theirs` already holds.
+ *
+ * Replayed, the first inserts the value a second time and the second replaces
+ * the foreign value. Identical values conflict rather than being skipped:
+ * skipping drops one of two additions that merely happen to be equal.
+ */
+function addsCollide(base: object, theirs: object, userPatch: readonly JsonPatchOperation[]): boolean {
+   // Through JSON, as `compare` clones the add values: an undefined-valued key
+   // in `theirs` would otherwise make an equal element count as another.
+   const comparable = JSON.parse(JSON.stringify(theirs)) as object;
+   return userPatch.some(op => {
+      if (op.op !== 'add') {
+         return false;
+      }
+      const cut = op.path.lastIndexOf('/');
+      const before = valueAt(base, op.path.slice(0, cut));
+      const now = valueAt(comparable, op.path.slice(0, cut));
+      if (Array.isArray(before)) {
+         return Array.isArray(now) && occurrences(now, op.value) > occurrences(before, op.value);
+      }
+      return typeof now === 'object' && now !== null && Object.hasOwn(now, unescapePathComponent(op.path.slice(cut + 1)));
+   });
+}
+
+/** How many elements of `array` deeply equal `value`, whatever their key order. */
+function occurrences(array: readonly unknown[], value: unknown): number {
+   return array.filter(element => _areEquals(element, value)).length;
+}
+
+/** The value at `pointer`, or `undefined` when a step of it is missing. */
+function valueAt(document: object, pointer: string): unknown {
+   try {
+      return getValueByPointer(document, pointer);
+   } catch {
+      return undefined;
    }
 }
 
@@ -132,12 +185,12 @@ export async function reconcileByPatchReplay<T extends object>(
  */
 export interface ConflictResolver {
    /**
-    * Reconcile the user's `baseline → attempted` intent against the current
-    * server state (`refetch`), returning a {@link ReconcileOutcome} the caller
+    * Reconcile the user's `base → ours` intent against the current
+    * server state (theirs, from `refetch`), returning a {@link ReconcileOutcome} the caller
     * acts on (persist `merged`, drop on `conflict`, fall back on `no-op` /
     * `unavailable`).
     */
-   resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+   resolve<T extends object>(base: T, ours: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
 }
 
 /**
@@ -147,19 +200,19 @@ export interface ConflictResolver {
  * clobbered.
  */
 export class ReconcilingConflictResolver implements ConflictResolver {
-   resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
-      return reconcileByPatchReplay(baseline, attempted, refetch);
+   resolve<T extends object>(base: T, ours: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
+      return reconcileByPatchReplay(base, ours, refetch);
    }
 }
 
 /**
- * Last-writer-wins {@link ConflictResolver}: always reports the `attempted`
+ * Last-writer-wins {@link ConflictResolver}: always reports the `ours`
  * state as merged, without refetching or guarding. Suitable for single-client
  * tools or always-regenerated artifacts where a concurrent foreign edit may be
  * overwritten. A foreign edit to any field is clobbered.
  */
 export class ForceConflictResolver implements ConflictResolver {
-   async resolve<T extends object>(_baseline: T, attempted: T, _refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
-      return { status: 'merged', merged: attempted };
+   async resolve<T extends object>(_base: T, ours: T, _refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>> {
+      return { status: 'merged', merged: ours };
    }
 }

package/src/profile-session.ts

@@ -62,7 +62,12 @@ export interface ProfileSession {
    records(): readonly ProfileRecord[];
 }
 
-interface ScopeFrame {
+/**
+ * One in-flight {@link ProfileSession.scope} call. Held on the `protected`
+ * {@link DefaultProfileSession.stack} and named by
+ * {@link DefaultProfileSession.closeFrame}, so a subclass has to name it too.
+ */
+export interface ProfileScopeFrame {
    readonly id: string;
    /** Session-stopwatch reading when this scope began. */
    readonly start: number;
@@ -78,7 +83,7 @@ interface ScopeFrame {
 export class DefaultProfileSession implements ProfileSession {
    /** Single monotonic timeline for the whole session; per-scope readings are deltas off it. */
    protected readonly sessionStopwatch: Stopwatch;
-   protected readonly stack: ScopeFrame[] = [];
+   protected readonly stack: ProfileScopeFrame[] = [];
    protected readonly entries = new Map<string, number[]>();
 
    constructor(
@@ -92,7 +97,7 @@ export class DefaultProfileSession implements ProfileSession {
    scope<T>(id: string, fn: () => Promise<T>): Promise<T>;
    scope<T>(id: string, fn: () => T): T;
    scope<T>(id: string, fn: () => T | Promise<T>): T | Promise<T> {
-      const frame: ScopeFrame = { id, start: this.sessionStopwatch.elapsedMs, childMs: 0 };
+      const frame: ProfileScopeFrame = { id, start: this.sessionStopwatch.elapsedMs, childMs: 0 };
       this.stack.push(frame);
       let result: T | Promise<T>;
       try {
@@ -118,7 +123,7 @@ export class DefaultProfileSession implements ProfileSession {
    }
 
    /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
-   protected closeFrame(frame: ScopeFrame): void {
+   protected closeFrame(frame: ProfileScopeFrame): void {
       this.stack.pop();
       const duration = this.sessionStopwatch.elapsedMs - frame.start;
       const parent = this.stack[this.stack.length - 1];

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

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { MessageConnection } from 'vscode-jsonrpc';
+import { ResponseError, type MessageConnection } from 'vscode-jsonrpc';
 import type { LatencyCollector } from '../latency-collector';
 import { type Disposable, DisposableCollection } from '../util';
 import { defaultIsNotification } from './create-rpc-proxy';
@@ -70,6 +70,36 @@ export interface BindRpcMethodsOptions {
     * Requests and notifications are both timed. Absent by default (no overhead).
     */
    readonly latency?: LatencyCollector;
+
+   /**
+    * Produce the `message` an outgoing rejection carries, so a user-facing
+    * error is rendered by the side that knows the reading user's language.
+    * Applied at this one chokepoint, which is what covers a caller's
+    * additional methods as well as the framework's own.
+    *
+    * Only a `ResponseError` is routed through it — a plain `Error` carries no
+    * identity to render from, and rewriting its message would relabel a
+    * developer-facing failure as a translated one. The rejection is
+    * RECONSTRUCTED rather than mutated, because the thrown value may be a
+    * shared constant; nothing is lost, since only `code`, `message` and `data`
+    * cross the wire and `instanceof` does not survive reconstruction anyway.
+    *
+    * Notifications are not covered, and "they have no reply channel" is only
+    * half the reason — a notification's own PAYLOAD can carry prose. What makes
+    * this sound is where that prose comes from: the only user-facing text on
+    * the data head's client surface is the diagnostics riding the
+    * document-updated and document-saved events, and those are read off
+    * `LangiumDocument.diagnostics`, which the document builder has already
+    * rendered at `Validated`. So they arrive rendered rather than escaping
+    * unrendered. A notification that ever carries prose of its OWN needs its
+    * own render at the raise site, as GLSP's actions do.
+    */
+   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;
 }
 
 /**
@@ -91,8 +121,10 @@ export interface BindRpcMethodsOptions {
  *
  * 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.
+ * standard error envelope, with the message rendered when
+ * {@link BindRpcMethodsOptions.renderErrorMessage} is supplied. Errors from a
+ * notification handler cannot propagate, 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
@@ -154,7 +186,20 @@ export function bindRpcMethods<T extends object>(
                })
             );
          } else {
-            disposables.push(resolved.onRequest(wireName, async (params: unknown) => dispatch(params)));
+            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);
+                  } catch (err: unknown) {
+                     throw renderRejection(err, render);
+                  }
+               })
+            );
          }
       }
    };

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

@@ -136,6 +136,14 @@ export interface CreateRpcProxyOptions<TLocal extends object = never> {
     * `bindRpcMethods` call) still capture per-method latency. Absent by default.
     */
    readonly latency?: BindRpcMethodsOptions['latency'];
+
+   /**
+    * Forwarded to the inbound {@link localTarget} binding: renders the message
+    * an outgoing rejection carries. Only the inbound direction has rejections
+    * to render — the outbound proxy is this side making requests, and a
+    * rejection it receives was rendered by whoever answered.
+    */
+   readonly renderErrorMessage?: BindRpcMethodsOptions['renderErrorMessage'];
 }
 
 /**
@@ -225,7 +233,12 @@ export function createRpcProxy<T extends object, TLocal extends object = never>(
    // 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 });
+      const binding = bindRpcMethods(connection, localTarget, localMethods, {
+         methodNamespace,
+         isNotification,
+         latency: options.latency,
+         renderErrorMessage: options.renderErrorMessage
+      });
       resolvedConnection.then(conn => conn.onClose(() => binding.dispose())).catch(() => undefined);
    }
 

package/src/testing/catalogue-audit.ts

@@ -0,0 +1,111 @@
+/********************************************************************************
+ * 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 { collectMessages } from '../messages/primitives';
+
+/**
+ * Audit a translation catalogue against the codes that actually exist.
+ *
+ * **The one failure mode a catalogue has, and the only one nothing else
+ * catches.** A key naming no declared code falls back to the English — which is
+ * byte-identical to a deliberate omission, so a typo is invisible at runtime and
+ * indistinguishable from the partial-catalogue behaviour every adopter relies
+ * on. Nothing on the render path can tell them apart, `theia nls-extract`
+ * reports what the SOURCE declares rather than whether a catalogue matches it,
+ * and the framework's own gates see only the framework's own files.
+ *
+ * Shipped as test support rather than as a runtime check on purpose: an
+ * orphaned key is an authoring mistake, and failing a server boot over one would
+ * take a running product down for a cosmetic defect.
+ */
+
+/**
+ * Flatten a nested catalogue into the `/`-joined keys a message code is spelled
+ * with, dropping `_`-prefixed keys as notes to a human reader.
+ *
+ * Nesting is a HOST convention, not the framework's: Theia flattens a nested
+ * catalogue by joining keys with `/`, which is the separator a code already
+ * uses, so an adopter on that host writes the file nested and one handed
+ * straight to a `DefaultMessageRenderer` writes it flat. Both end up here.
+ *
+ * `_`-prefixed keys are dropped by PREFIX rather than by matching one literal
+ * name, so a second note added to a file cannot silently become a catalogue
+ * entry. A code is three `/`-separated segments, so no real entry can begin
+ * with `_`.
+ */
+export function flattenCatalogue(catalogue: Record<string, unknown>, prefix = ''): Record<string, string> {
+   const flat: Record<string, string> = {};
+   for (const [key, value] of Object.entries(catalogue)) {
+      if (key.startsWith('_')) {
+         continue;
+      }
+      const joined = prefix ? `${prefix}/${key}` : key;
+      if (typeof value === 'string') {
+         flat[joined] = value;
+      } else if (typeof value === 'object' && value !== null) {
+         Object.assign(flat, flattenCatalogue(value as Record<string, unknown>, joined));
+      }
+   }
+   return flat;
+}
+
+/** Options for {@link findUndeclaredCodes}. */
+export interface CatalogueAuditOptions {
+   /**
+    * Key prefixes to skip, for entries whose codes are NOT declared through a
+    * `defineMessage` barrel.
+    *
+    * The real case is a host's own mechanism: Theia's `nls.localize` takes its
+    * key as an inline literal at the call site, so those keys exist only in
+    * source text and no barrel can enumerate them. Keep this as narrow as the
+    * host layer actually is — exempting a namespace is exempting every typo in
+    * it, which is what this function exists to find.
+    */
+   readonly exemptPrefixes?: readonly string[];
+}
+
+/**
+ * Every catalogue key that names no code any of `barrels` declares.
+ *
+ * Barrels are taken as opaque objects and read with {@link collectMessages},
+ * which is what lets a caller pass a `import * as messages` namespace directly:
+ * a barrel's value type is a union of its declarations AND its functions, and
+ * filtering that union will not narrow to a `MessageDefinition`.
+ *
+ * Returns the offending keys rather than a boolean, so a failing assertion names
+ * WHICH key is wrong — a count says only that something is.
+ */
+export function findUndeclaredCodes(
+   catalogueKeys: readonly string[],
+   barrels: readonly object[],
+   options: CatalogueAuditOptions = {}
+): string[] {
+   const declared = new Set(barrels.flatMap(barrel => collectMessages(barrel).map(message => message.code)));
+   const exempt = options.exemptPrefixes ?? [];
+   return catalogueKeys.filter(key => !exempt.some(prefix => key.startsWith(prefix)) && !declared.has(key));
+}
+
+/**
+ * Keys present in more than one catalogue — the shape a split catalogue rots
+ * into.
+ *
+ * Exactly one side renders a given message, so two catalogues holding one code
+ * are two authorities over one sentence and they diverge on the first reword.
+ * Nothing at runtime notices: both sides render, and whichever ran last wins on
+ * its own surface.
+ *
+ * Takes the key sets rather than a boolean answer for the same reason as
+ * {@link findUndeclaredCodes}, and reports NOTHING when a set is empty — an
+ * empty catalogue shares no key with anything, so a caller must assert
+ * non-emptiness separately or a failed read passes this vacuously.
+ */
+export function findSharedCodes(first: readonly string[], second: readonly string[]): string[] {
+   const other = new Set(second);
+   return first.filter(key => other.has(key));
+}

package/src/testing/data-doubles.ts

@@ -34,7 +34,15 @@
 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 {
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentDirtyChangedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from '../data/events';
+import type { ResolvedMessage } from '../messages/primitives';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -51,13 +59,6 @@ export interface FakeDataPortOptions {
     * 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. */
@@ -73,10 +74,11 @@ export interface FakeDataPort extends DataPort {
    /**
     * 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.
+    * path asserts here rather than on a rejection the consumer may legitimately
+    * swallow. Prefer asserting on `message.code`, which is stable, over
+    * `message.text`, which is the English default and may be reworded.
     */
-   readonly reported: readonly { readonly error: unknown; readonly context: string }[];
+   readonly reported: readonly { readonly error: unknown; readonly message: ResolvedMessage }[];
    /**
     * Fire {@link DataPort.onDispose} — the host tearing the transport down, a
     * language-server restart being the case that forces the event to exist.
@@ -96,10 +98,9 @@ export interface FakeDataPort extends DataPort {
  */
 export function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort {
    const connections: MessageConnection[] = [];
-   const reported: { error: unknown; context: string }[] = [];
+   const reported: { error: unknown; message: ResolvedMessage }[] = [];
    const disposeEmitter = new Emitter<void>();
    return {
-      clientId: options.clientId ?? 'fake-data-port',
       connections,
       reported,
       onDispose: disposeEmitter.event,
@@ -108,8 +109,8 @@ export function makeFakeDataPort(options: FakeDataPortOptions): FakeDataPort {
          connections.push(connection);
          return connection;
       },
-      reportError(error: unknown, context: string): void {
-         reported.push({ error, context });
+      reportError(error: unknown, message: ResolvedMessage): void {
+         reported.push({ error, message });
       },
       fireDispose(): void {
          disposeEmitter.fire(undefined);
@@ -132,6 +133,12 @@ export interface CapturingDataClient<
    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>[];
 }
@@ -139,7 +146,7 @@ export interface CapturingDataClient<
 /**
  * A {@link DataClientProtocol} that records every notification it receives.
  *
- * Recording ALL THREE channels even when a suite reads one is deliberate: an
+ * Recording EVERY channel 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.
@@ -156,6 +163,9 @@ export function makeCapturingDataClient<
 >(overrides: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>> = {}): CapturingDataClient<TTransfer, TDiagnostic, TProject> {
    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> = {
       onDocumentUpdated:
@@ -168,11 +178,26 @@ export function makeCapturingDataClient<
          (event => {
             saves.push(event);
          }),
+      onDocumentDirtyChanged:
+         overrides.onDocumentDirtyChanged ??
+         (event => {
+            dirtyChanges.push(event);
+         }),
+      onDocumentDeleted:
+         overrides.onDocumentDeleted ??
+         (event => {
+            deletions.push(event);
+         }),
+      onDocumentsBuilt:
+         overrides.onDocumentsBuilt ??
+         (event => {
+            builds.push(event);
+         }),
       onProjectsChanged:
          overrides.onProjectsChanged ??
          (event => {
             projectsChanges.push(event);
          })
    };
-   return { client, updates, saves, projectsChanges };
+   return { client, updates, saves, dirtyChanges, deletions, builds, projectsChanges };
 }