@hydranium/protocol 1.0.0-next.123 → 1.0.0-next.127

package/src/client/data-session.ts

@@ -7,7 +7,10 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { DataServerProtocol, DiagnosticOf } from '../data';
+import { type Disposable, Emitter, type Event } from 'vscode-jsonrpc';
+import { type Clock, SystemClock } from '../clock';
+import type { DataServerProtocol, DiagnosticOf, TransferDocumentDirtyChangedEvent } from '../data';
+import { SessionClosedError } from '../errors';
 import type { SnapshotVersion } from '../model-service/based-on';
 import { type ResolvedMessage, defineMessage, describeError, resolve } from '../messages/primitives';
 import type { OpenModelArgs } from '../model-server';
@@ -104,9 +107,20 @@ export type DataSessionDocument<
 export interface DataSessionHost<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>>> {
    /** The connected, READY proxy of the current connection; a new object after each reconnect. */
    connected(): Promise<RpcProxy<TServer>>;
-   releaseSession(session: DataSession<TTransfer, TServer>): void;
    /** Surface a failure no caller is waiting on, such as restoring a document after a reconnect. */
    reportError?(error: unknown, reported: ResolvedMessage): void;
+   /**
+    * Tell the connection's client the dirty state a restore read, unless it
+    * is what the client was last told of the URI since the URI's last open.
+    */
+   restoreDirty?(event: TransferDocumentDirtyChangedEvent): void;
+   /**
+    * Forget what the client was told of `uri`'s dirty state: an open just
+    * made answered its caller afresh, and the client heard none of it, or a
+    * close leaves nothing to restore. Forgetting a URI another session still
+    * has open costs at most one repeat of a state the client already has.
+    */
+   forgetDirty?(uri: string): void;
 }
 
 /**
@@ -139,8 +153,9 @@ export type DataSessionFactory<TTransfer extends TransferElement, TServer extend
  * otherwise reach the server after it, and fail as not open.
  *
  * After the connection drops, the session registers again under the same id,
- * re-opens and re-watches what it had open, and reports the documents whose
- * unsaved edits did not survive; see {@link restore}. The connection does this at
+ * re-opens and re-watches what it had open, tells the client of their dirty
+ * state where it changed, and reports the documents whose unsaved edits did
+ * not survive; see {@link restore}. The connection does this at
  * once for a session with documents open, and any session's next call does it
  * too.
  *
@@ -156,7 +171,7 @@ export type DataSessionFactory<TTransfer extends TransferElement, TServer extend
 export class DataSession<
    TTransfer extends TransferElement,
    TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
-> {
+> implements Disposable {
    /**
     * How long {@link closeDocument} and {@link dispose} wait for this session's
     * calls in flight before closing anyway. Long, because the wait only runs
@@ -164,8 +179,20 @@ export class DataSession<
     * fails that save.
     */
    protected readonly settleBeforeCloseMs: number = 10_000;
+   /**
+    * The clock {@link settleBeforeCloseMs} runs on. {@link DataSessionHost}
+    * carries no {@link Clock}, so a subclass replaces this field as it
+    * replaces the bound.
+    */
+   protected readonly clock: Clock = new SystemClock();
    /** URIs this session has open, re-opened after a reconnect. */
    protected readonly openUris = new Set<string>();
+   /**
+    * Per URI in {@link openUris}, the URI the server's last answer to its open
+    * or re-open named. The server keys its notifications by it, and so does
+    * the host's record of what its client was told.
+    */
+   protected readonly serverUris = new Map<string, string>();
    /**
     * Per URI, how many opens of it this session has under way. Such a URI
     * counts as open for {@link withOpenDocument}, which would otherwise close
@@ -179,6 +206,21 @@ export class DataSession<
    protected readonly unsavedWrites = new Map<string, SnapshotVersion>();
    /** Per URI, this session's calls still in flight on it, which a close waits for. */
    protected readonly inFlight = new Map<string, Set<Promise<unknown>>>();
+   /** This session's saves still in flight, which a host's exit waits for; see {@link hasSavesInFlight}. */
+   protected readonly savesInFlight = new Set<Promise<unknown>>();
+   protected readonly disposeEmitter = new Emitter<void>();
+   /**
+    * Fires once when the session ends, by {@link dispose} or {@link detach}, as
+    * soon as it rejects further calls and before any close is sent. For a
+    * session its connection created, the connection's listener runs first, so
+    * the id is free again on that connection by the time any other listener
+    * runs; the server still holds it until the close arrives, and refuses a new
+    * session under it until then.
+    *
+    * A listener subscribed once the session has ended is never called, so a
+    * late subscriber checks {@link isDisposed} first.
+    */
+   readonly onDidDispose: Event<void> = this.disposeEmitter.event;
    /**
     * Sent with every registration, so the server lets this session register
     * its id again while the dropped connection's session is still live there:
@@ -280,6 +322,10 @@ export class DataSession<
          throw error;
       }
       this.openUris.add(uri);
+      this.serverUris.set(uri, document.uri);
+      // Keyed as the server keys its notifications, which may not be how the
+      // caller spelled the URI.
+      this.host.forgetDirty?.(document.uri);
       return document;
    }
 
@@ -294,8 +340,11 @@ export class DataSession<
       // Forgotten before the close is sent, so a reconnect in between does not
       // re-open a document the caller has closed; after the wait, so an open
       // of it that was still in flight does not record it again.
+      const serverUri = this.serverUris.get(args.uri) ?? args.uri;
       this.openUris.delete(args.uri);
+      this.serverUris.delete(args.uri);
       this.unsavedWrites.delete(args.uri);
+      this.host.forgetDirty?.(serverUri);
       const server = await this.connected();
       await server.closeModelDocument({ ...args, clientId: this.clientId });
    }
@@ -350,12 +399,39 @@ export class DataSession<
 
    /** Persist `args.model` to disk as this session. The session must have `args.uri` open. */
    saveDocument(args: DataSessionSaveArgs<TTransfer, TServer>): Promise<DataSessionDocument<TTransfer, TServer>> {
-      return this.track([args.uri], async () => {
+      const saving = this.track([args.uri], async () => {
          const server = await this.connected();
          const document = await server.saveModelDocument({ ...args, clientId: this.clientId });
          this.unsavedWrites.delete(args.uri);
          return document;
       });
+      this.savesInFlight.add(saving);
+      const done = (): boolean => this.savesInFlight.delete(saving);
+      saving.then(done, done);
+      return saving;
+   }
+
+   /** Whether the session has ended, by {@link dispose} or {@link detach}. */
+   get isDisposed(): boolean {
+      return this.disposed;
+   }
+
+   /**
+    * Whether a save of this session has not answered yet. Synchronous, for a
+    * host whose exit veto must decide within the tick, such as Theia's
+    * `onWillStop`.
+    */
+   get hasSavesInFlight(): boolean {
+      return this.savesInFlight.size > 0;
+   }
+
+   /**
+    * Resolves once the saves in flight now have answered, or
+    * {@link settleBeforeCloseMs} has passed. Never rejects: a failed save has
+    * answered too.
+    */
+   whenSavesSettled(): Promise<void> {
+      return this.settle(this.savesInFlight);
    }
 
    /**
@@ -375,16 +451,17 @@ export class DataSession<
     * end it on the server, which closes everything it has open. Idempotent,
     * and leaves the connection usable by its other sessions.
     *
-    * Every later call rejects. The server close is not awaited, because a
-    * `Disposable` cannot be; a close that fails leaves the session to the
-    * server's connection-close cleanup.
+    * Every later call rejects, and so does a call made earlier in the same
+    * tick, which has not reached the wire yet and is never sent. The server
+    * close is not awaited, because a `Disposable` cannot be; a close that fails
+    * leaves the session to the server's connection-close cleanup.
     */
    dispose(): void {
       if (this.disposed) {
          return;
       }
       this.disposed = true;
-      this.host.releaseSession(this);
+      this.fireDispose();
       const pending = [...this.inFlight.values()].flatMap(calls => [...calls]);
       void (async () => {
          await this.settle(pending);
@@ -403,12 +480,27 @@ export class DataSession<
     * Sends nothing, unlike {@link dispose}: the server ends every session on a
     * connection it sees close, and the close would travel over the very
     * connection being disposed.
+    *
+    * Public because the connection calls it; anyone else ends a session with
+    * {@link dispose}. It fires {@link onDidDispose} only if the session has not
+    * already ended, and after {@link dispose} it still cancels the close that
+    * dispose has not sent yet.
     */
    detach(): void {
-      this.disposed = true;
       this.detached = true;
       this.openUris.clear();
+      this.serverUris.clear();
       this.unsavedWrites.clear();
+      if (!this.disposed) {
+         this.disposed = true;
+         this.fireDispose();
+      }
+   }
+
+   /** Fire {@link onDidDispose} and dispose its emitter, so a second call fires nothing. */
+   protected fireDispose(): void {
+      this.disposeEmitter.fire(undefined);
+      this.disposeEmitter.dispose();
    }
 
    /**
@@ -452,6 +544,11 @@ export class DataSession<
     * naming every document whose unsaved text is gone, whose record is then
     * dropped, and one per document that could not be re-opened, which is
     * forgotten.
+    *
+    * Each document's dirty state goes to the host too, read once the watch is
+    * in place: a flip while the connection was down, or between the re-open
+    * and the watch, reached no one, and the re-open's own answer misses the
+    * second.
     */
    protected async restore(server: RpcProxy<TServer>): Promise<void> {
       const lost: string[] = [];
@@ -459,6 +556,20 @@ export class DataSession<
          try {
             const document = await server.openModelDocument({ uri, clientId: this.clientId });
             await server.watchModelDocument({ uri, clientId: this.clientId });
+            if (this.openUris.has(uri)) {
+               this.serverUris.set(uri, document.uri);
+            }
+            // A failed read leaves the client's dirty state as it was; the
+            // document is restored all the same.
+            const current = await server.getModelDocument({ uri }).catch(() => undefined);
+            if (current?.dirty !== undefined) {
+               try {
+                  this.host.restoreDirty?.({ uri: current.uri, dirty: current.dirty });
+               } catch {
+                  // The client's listener failed, not the restore: the server
+                  // has the document open and watched, so it stays restored.
+               }
+            }
             const written = this.unsavedWrites.get(uri);
             if (written !== undefined && written !== document.version) {
                lost.push(uri);
@@ -466,6 +577,7 @@ export class DataSession<
             }
          } catch (error: unknown) {
             this.openUris.delete(uri);
+            this.serverUris.delete(uri);
             this.unsavedWrites.delete(uri);
             this.host.reportError?.(error, resolve(DATA_SESSION_RESTORE_FAILED, { uri, detail: describeError(error) }));
          }
@@ -509,20 +621,12 @@ export class DataSession<
       if (pending.length === 0) {
          return;
       }
-      let timer: ReturnType<typeof setTimeout> | undefined;
-      const bound = new Promise<void>(resolveBound => {
-         timer = setTimeout(resolveBound, this.settleBeforeCloseMs);
-      });
-      try {
-         await Promise.race([Promise.allSettled(pending), bound]);
-      } finally {
-         clearTimeout(timer);
-      }
+      await this.clock.raceTimer(Promise.allSettled(pending), this.settleBeforeCloseMs);
    }
 
    protected assertLive(): void {
       if (this.disposed) {
-         throw new Error('DataSession is disposed');
+         throw new SessionClosedError(this.clientId);
       }
    }
 }

package/src/client/index.ts

@@ -18,7 +18,9 @@
  * identity, open/watch ordering, echo recognition), the inbound
  * fan-out (`DataEvents`), and the two halves of the hop for hosts whose
  * client cannot hold a socket — `createPostMessageTransport` on the client
- * side and `relayToPostMessageChannel` on the side that does hold it.
+ * side and `relayToPostMessageChannel` on the side that does hold it, and
+ * `createMessagePortTransport` for a head's worker `MessagePort`, at either
+ * end, which the GLSP worker head uses too.
  *
  * **Neutral, and gate-enforced so.** Nothing here imports a host package or a
  * Node builtin, which is what lets one client tier serve a Theia frontend, a VS

package/src/client/message-relay.ts

@@ -110,7 +110,7 @@ export interface MessageRelay extends Disposable {
  * imports the entrypoint that frames its own transport (`vscode-jsonrpc/node`
  * for a socket) and the RAL that comes with it; this tier stays neutral and is
  * gated so by `npm run check:neutral`. Contrast
- * `@hydranium/data-client-theia`'s `SocketChannelForwarder`, which does build a
+ * `@hydranium/client-theia`'s `SocketChannelForwarder`, which does build a
  * connection only to borrow its `onClose`, and pays a Theia dependency for the
  * byte coding this shape does not need.
  *

package/src/client/post-message-transport.ts

@@ -11,6 +11,7 @@ import {
    AbstractMessageReader,
    AbstractMessageWriter,
    Emitter,
+   RAL,
    type DataCallback,
    type Disposable,
    type Message,
@@ -36,7 +37,8 @@ export interface PostMessageChannel {
    /**
     * Hand one JSON-RPC message to the other side. Fire-and-forget: delivery
     * failures surface through {@link onClose}, never as a rejection, because
-    * `postMessage` has no completion to report.
+    * `postMessage` has no completion to report. A value the pipe refuses may
+    * throw, and the writer turns that into a rejected write and a writer error.
     */
    post(message: Message): void;
 
@@ -67,12 +69,18 @@ export interface PostMessageChannel {
  *
  * Keeping the factory out of this module is also what lets the module stay
  * browser-neutral: it touches only `AbstractMessageReader` /
- * `AbstractMessageWriter` / `Emitter`, none of which need a RAL.
+ * `AbstractMessageWriter` / `Emitter`, none of which need a RAL, and the RAL's
+ * timer, which {@link createMessagePortTransport} reads only once a message
+ * arrives, by when the host that built the connection has installed one in
+ * the same copy of `vscode-jsonrpc`.
  */
 export interface PostMessageTransport {
    readonly reader: MessageReader;
    readonly writer: MessageWriter;
-   /** Release the channel subscriptions. */
+   /**
+    * Release the channel subscriptions. A {@link createMessagePortTransport}
+    * transport also signals its end to the other side.
+    */
    dispose(): void;
 }
 
@@ -112,6 +120,7 @@ class PostMessageReader extends AbstractMessageReader implements MessageReader {
 /** The dual of {@link PostMessageReader} — one `post` per JSON-RPC message. */
 class PostMessageWriter extends AbstractMessageWriter implements MessageWriter {
    protected readonly subscriptions: Disposable[] = [];
+   protected errorCount = 0;
 
    constructor(protected readonly channel: PostMessageChannel) {
       super();
@@ -122,7 +131,17 @@ class PostMessageWriter extends AbstractMessageWriter implements MessageWriter {
    }
 
    write(message: Message): Promise<void> {
-      this.channel.post(message);
+      try {
+         this.channel.post(message);
+      } catch (error: unknown) {
+         // `postMessage` throws synchronously on a value structured clone
+         // refuses. Thrown on, it would escape from the caller's
+         // `sendNotification` rather than reject it, and the connection would
+         // never see a write error.
+         this.errorCount++;
+         this.fireError(error, message, this.errorCount);
+         return Promise.reject(error);
+      }
       // `postMessage` reports no completion, so the resolved promise means
       // "handed over", not "delivered". vscode-jsonrpc only needs the former.
       return Promise.resolve();
@@ -165,3 +184,199 @@ export function createPostMessageTransport(channel: PostMessageChannel): PostMes
       }
    };
 }
+
+/**
+ * A `MessagePort` the host transferred into or out of a worker, described
+ * structurally.
+ *
+ * This package compiles without the DOM lib, so `MessagePort` has no name here
+ * and the contract has to be spelled out.
+ *
+ * **The member set admits a `MessagePort` and REJECTS a `Worker` or the worker
+ * global**, both of which would otherwise fit a `postMessage` pipe. Only a port
+ * needs starting, so `start` is what tells the three apart, and naming it here
+ * turns "never bind a head to the global" into a compile error at the call
+ * site. A head on the global receives every other head's traffic.
+ *
+ * **That compile error happens at the ADOPTER, not here.** This package
+ * resolves neither `MessagePort` nor `Worker` as a type, so nothing here can
+ * demonstrate the rejection; a host compiling its worker against
+ * `lib.webworker` (or a page against `lib.dom`) is where the names resolve and
+ * the guard bites. Measured there: passing the worker global fails with
+ * `Property 'start' is missing in type 'DedicatedWorkerGlobalScope'`.
+ */
+export interface TransferredMessagePort {
+   postMessage(message: unknown): void;
+   addEventListener(type: 'message', listener: (event: unknown) => void, options?: unknown): void;
+   removeEventListener(type: 'message', listener: (event: unknown) => void, options?: unknown): void;
+   start(): void;
+}
+
+/**
+ * The value {@link createMessagePortTransport} posts in place of a JSON-RPC
+ * message to say its end is going away. A string, so no JSON-RPC message can
+ * be mistaken for it.
+ */
+const MESSAGE_PORT_CLOSE_SIGNAL = 'hydranium/message-port-closed';
+
+/**
+ * A {@link PostMessageChannel} over a {@link TransferredMessagePort}, whose
+ * {@link close} posts {@link MESSAGE_PORT_CLOSE_SIGNAL}.
+ *
+ * **A port reports nothing when its peer goes away**: Chromium ships no `close`
+ * event on `MessagePort`, Firefox and WebKit have not committed to one, and
+ * `messageerror` fires only for a message that cannot be deserialized. So the
+ * end is signalled in band.
+ *
+ * The port is never `close()`d. A later transport can still be built on it, at
+ * both ends, and whether messages posted just before a `close()` are delivered
+ * is not something the platform settles.
+ */
+class MessagePortChannel implements PostMessageChannel {
+   protected readonly messageEmitter = new Emitter<Message>();
+   protected readonly closeEmitter = new Emitter<void>();
+   /** Set once either end has signalled; this end then delivers nothing more and never signals again. */
+   protected closed = false;
+   /** Set when the peer's signal has arrived and its close waits on {@link backlog}. */
+   protected closePending = false;
+   /** Messages handed to the connection that its queue may not have dispatched yet. */
+   protected backlog = 0;
+   // A `MessageEvent`, which the listener's type cannot name without the DOM lib.
+   protected readonly listener = (event: unknown): void => this.receive((event as { readonly data: unknown }).data);
+
+   constructor(protected readonly port: TransferredMessagePort) {
+      port.addEventListener('message', this.listener);
+   }
+
+   post(message: Message): void {
+      if (!this.closed) {
+         this.port.postMessage(message);
+      }
+   }
+
+   onMessage(listener: (message: Message) => void): Disposable {
+      return this.messageEmitter.event(listener);
+   }
+
+   onClose(listener: () => void): Disposable {
+      return this.closeEmitter.event(listener);
+   }
+
+   /** Signal this end's close to the peer, once, after everything posted before it. */
+   close(): void {
+      if (this.closed) {
+         return;
+      }
+      this.end();
+      this.port.postMessage(MESSAGE_PORT_CLOSE_SIGNAL);
+   }
+
+   protected end(): void {
+      this.closed = true;
+      this.port.removeEventListener('message', this.listener);
+   }
+
+   /**
+    * Deliver one inbound value, or take the peer's signal.
+    *
+    * **The close waits until the connection has dispatched every message that
+    * came before it.** Firing it at once is safe under `vscode-jsonrpc`'s
+    * browser runtime, which drains the connection's queue on microtasks before
+    * the signal's own task runs. Under its Node runtime the queue gives out one
+    * message per `setImmediate` turn, so a close fired at once would overtake a
+    * `closeSession` still queued, and end that session as lost. So each
+    * delivered message is counted down on the same RAL timer, one per turn,
+    * scheduled after the connection's own, and the close fires when the count
+    * reaches zero: under either runtime, after the last dispatch.
+    */
+   protected receive(data: unknown): void {
+      if (this.closed) {
+         return;
+      }
+      if (data === MESSAGE_PORT_CLOSE_SIGNAL) {
+         this.end();
+         this.closePending = true;
+         if (this.backlog === 0) {
+            this.closeEmitter.fire();
+         }
+         return;
+      }
+      this.messageEmitter.fire(data as Message);
+      this.backlog++;
+      if (this.backlog === 1) {
+         this.countDownBacklog();
+      }
+   }
+
+   // Mirrors the connection's queue at its default of one message per turn. A
+   // connection built with a `maxParallelism`, or with a `messageStrategy` that
+   // defers `next`, can hold messages longer than this counts, and its close
+   // can then overtake them.
+   protected countDownBacklog(): void {
+      RAL().timer.setImmediate(() => {
+         this.backlog--;
+         if (this.backlog > 0) {
+            this.countDownBacklog();
+         } else if (this.closePending) {
+            this.closeEmitter.fire();
+         }
+      });
+   }
+}
+
+/**
+ * A {@link PostMessageWriter} whose dispose, which a `MessageConnection`'s
+ * `dispose` and `end` both reach, signals this end's close to the peer.
+ */
+class MessagePortWriter extends PostMessageWriter {
+   constructor(protected override readonly channel: MessagePortChannel) {
+      super(channel);
+   }
+
+   override dispose(): void {
+      this.channel.close();
+      super.dispose();
+   }
+}
+
+/**
+ * Build the reader/writer pair for a head's `MessagePort`, at either end.
+ *
+ * Disposing the writer (which the connection's own `dispose` does) posts a
+ * close signal after everything it wrote, and the other end's reader and writer
+ * then fire close, so a head tears down on its client's dispose as it does on a
+ * socket's close. For a connection at its default parallelism and message
+ * strategy, the close fires only once that end's connection has dispatched
+ * every message sent before the signal, under either `vscode-jsonrpc` runtime,
+ * so a `closeSession` sent just before the dispose still ends its session as
+ * closed. Nothing reports a page or a worker that dies, because the port
+ * cannot.
+ *
+ * **The transport and the connection must come from the same copy of
+ * `vscode-jsonrpc`.** The close is scheduled through the runtime abstraction
+ * layer of the copy this package imports. If the host builds its connection
+ * from another copy, that layer was never installed: the first message it
+ * delivers throws, and the peer's close never fires.
+ *
+ * **Both ends must use this.** A plain `BrowserMessageReader` peer hands the
+ * signal to its connection as a message it does not understand, and its own
+ * dispose posts nothing, so this end never learns that it went.
+ *
+ * Starts the port, because a listener added with `addEventListener` does not.
+ * From then on a message that arrives before the connection listens is dropped,
+ * so listen in the same task.
+ */
+export function createMessagePortTransport(port: TransferredMessagePort): PostMessageTransport {
+   const channel = new MessagePortChannel(port);
+   const reader = new PostMessageReader(channel);
+   const writer = new MessagePortWriter(channel);
+   port.start();
+   return {
+      reader,
+      writer,
+      dispose(): void {
+         reader.dispose();
+         writer.dispose();
+      }
+   };
+}

package/src/client/rpc-connection.ts

@@ -189,13 +189,22 @@ export class RpcConnection<TServer extends ReadyServer, TClient extends object>
       );
       const server = createRpcProxy<TServer, TClient>(connection, {
          methodNamespace: this.methodNamespace,
-         localTarget: this.client,
+         localTarget: this.localTarget(),
          localMethods: this.clientMethods
       });
       this.generation = { connection, server };
       return this.generation;
    }
 
+   /**
+    * The object whose {@link clientMethods} answer the server on each new
+    * generation: {@link client} itself. A subclass that must see a call before
+    * the client does returns an object that forwards each of them to it.
+    */
+   protected localTarget(): TClient {
+      return this.client;
+   }
+
    /** Await the connection and the server's startup gate for one generation. */
    protected async awaitReady(generation: RpcConnectionGeneration<TServer>): Promise<void> {
       try {

package/src/clock.ts

@@ -76,8 +76,30 @@ export interface Clock {
     */
    measure<T>(callback: () => Promise<T>): Promise<Timed<T>>;
    measure<T>(callback: () => T): Timed<T>;
+   /**
+    * Settle with `promise`, or with {@link TIMED_OUT} once `ms` have elapsed
+    * first. A promise that rejects first rejects this one; one that rejects
+    * after the timer is ignored. The timer is disposed the moment `promise`
+    * settles, so a won race leaves nothing scheduled, but `promise` itself
+    * runs on: nothing here can cancel it.
+    *
+    * Unlike VS Code's `raceTimeout`, this settles with a sentinel rather than
+    * `undefined`, so a promise resolving to `undefined` is not taken for a
+    * timeout; the caller branches on the result instead of passing an
+    * `onTimeout`.
+    *
+    * A custom implementation extends {@link SystemClock}, whose race runs over
+    * the subclass's {@link setTimer}.
+    */
+   raceTimer<T>(promise: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT>;
 }
 
+/**
+ * What {@link Clock.raceTimer} settles with when its timer fires first.
+ * Registered under a global key, so two copies of this package agree on it.
+ */
+export const TIMED_OUT = Symbol.for('hydranium/protocol/timed-out');
+
 /**
  * The result of {@link Clock.measure}: a callback's return value paired with
  * its elapsed wall-time in milliseconds. A plain value object — no methods, no
@@ -144,6 +166,10 @@ function unrefTimer(handle: { unref?: () => void }): void {
  * Default {@link Clock}: delegates to the platform's `Date.now`,
  * `performance.now`, and `setTimeout`/`clearTimeout`. Bound everywhere in
  * production; swapped for `makeFakeClock` in tests.
+ *
+ * {@link measure} and {@link raceTimer} run over {@link stopwatch} and
+ * {@link setTimer}, so a clock that extends this one and replaces those
+ * measures and races on its own time, as the test clock does.
  */
 export class SystemClock implements Clock {
    now(): number {
@@ -170,4 +196,34 @@ export class SystemClock implements Clock {
       }
       return { result: result as T, elapsedMs: stopwatch.elapsedMs };
    }
+
+   /**
+    * The timer settles the race one microtask after it fires. A real timer
+    * runs only once pending resolutions are delivered, while a fake one fires
+    * inside its `advance`, so settling at once would let a promise already
+    * resolved when `advance` runs lose to a timer it beats in production. The
+    * deferral covers only that promise: one that settles through further
+    * chained reactions, such as a `.then` chain, an async function or
+    * `Promise.allSettled`, can still lose to an `advance` in the same turn,
+    * while it wins on the platform's timer. The handlers go on `promise`
+    * before {@link setTimer} runs, so a `setTimer` that throws still leaves
+    * `promise` observed.
+    */
+   raceTimer<T>(promise: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> {
+      return new Promise<T | typeof TIMED_OUT>((resolve, reject) => {
+         // eslint-disable-next-line prefer-const -- with a `const`, a `setTimer` that throws leaves it uninitialised, and the handlers' later read of it is an unhandled ReferenceError
+         let timer: Disposable | undefined;
+         promise.then(
+            value => {
+               timer?.dispose();
+               resolve(value);
+            },
+            (err: unknown) => {
+               timer?.dispose();
+               reject(err);
+            }
+         );
+         timer = this.setTimer(() => void Promise.resolve().then(() => resolve(TIMED_OUT)), ms);
+      });
+   }
 }

package/src/data/data-protocol-methods.ts

@@ -66,6 +66,7 @@ export const REFERENCE_SERVER_PROTOCOL_METHODS = [
 export const DOCUMENT_CLIENT_PROTOCOL_METHODS = [
    'onDocumentUpdated',
    'onDocumentSaved',
+   'onDocumentDirtyChanged',
    'onDocumentDeleted',
    'onDocumentsBuilt'
 ] as const satisfies ReadonlyArray<keyof DocumentClientProtocol<TransferElement> & string>;