@hydranium/protocol 1.0.0-next.23 → 1.0.0-next.230

package/src/client/index.ts

@@ -13,28 +13,33 @@
  *
  * Where `./data` is the wire *contract* and `./rpc` is the machinery that lowers
  * it onto a connection, this is what a client wraps around both: the seam a host
- * fills in (`DataPort`), the lifecycle above it (`DataSession` —
- * readiness gate, open/watch ordering, echo recognition, reconnect), the inbound
+ * fills in (`DataPort`), the connection above it (`DataConnection` — readiness
+ * gate and reconnect), the participants on that connection (`DataSession` —
+ * 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
  * Code extension host, a VS Code webview and a plain browser app. `npm run
- * check:neutral` bundles these modules for the browser; `scripts/check-neutral-bundles.mjs`
+ * check:neutral` bundles these modules for the browser; `scripts/check-neutral-bundles.mts`
  * carries the entries.
  *
  * The Theia-specific mounting of the same contract lives in
- * `@hydranium/data-client-theia`: its `AbstractDataServiceFrontend` solves the
- * same problem against Theia's channel transport, and its `EmitterDataClient`
- * is the Theia-bound counterpart of `DataEvents`. Prefer this tier for
- * anything new, and reach for the Theia package only for what genuinely needs
- * Theia DI.
+ * `@hydranium/data-client-theia`, and is now only the TRANSPORT: its
+ * `ChannelDataPort` fills the `DataPort` seam over a Theia channel, and its
+ * `EmitterDataClient` is the Theia-bound counterpart of `DataEvents`.
+ * Everything above the port is here, so a Theia frontend and a browser page
+ * differ by which port they construct and nothing else.
  */
 
+export * from './data-connection';
 export * from './data-events';
 export * from './data-port';
 export * from './data-session';
 export * from './message-relay';
 export * from './post-message-transport';
+export * from './rpc-connection';

package/src/client/message-relay.ts

@@ -8,8 +8,29 @@
  ********************************************************************************/
 
 import { Emitter, type Disposable, type Event, type Message, type MessageReader, type MessageWriter } from 'vscode-jsonrpc';
+import { defineMessage, describeError, resolve, type ResolvedMessage } from '../messages/primitives';
 import type { PostMessageChannel } from './post-message-transport';
 
+export const RELAY_TRANSPORT_OPEN_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-open-failed',
+   'Could not open the transport to relay: {detail}'
+);
+
+export const RELAY_TRANSPORT_READ_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-read-failed',
+   'Could not read from the relayed transport: {detail}'
+);
+
+export const RELAY_TRANSPORT_WRITE_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-write-failed',
+   'Could not write to the relayed transport: {detail}'
+);
+
+export const RELAY_REPLAY_FAILED = defineMessage(
+   'hydranium/protocol/relay-replay-failed',
+   'Could not replay a buffered message to the relayed transport: {detail}'
+);
+
 /**
  * The framed side of a relay: the reader/writer pair over whatever transport the
  * host actually holds — a TCP socket to the data-server, a child process' stdio,
@@ -30,13 +51,14 @@ export interface RelayTransport {
 export interface MessageRelayOptions {
    /**
     * Surface a failure the way the host does. Same contract as
-    * `DataPort.reportError`: `context` names what was being attempted.
+    * `DataPort.reportError`: `reported` is a complete sentence plus the identity
+    * needed to render it in another language.
     *
     * A relay has no other way to report — it sits between two transports and
     * owns neither, so a swallowed error here presents as a form that never
     * populates.
     */
-   readonly reportError?: (error: unknown, context: string) => void;
+   readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
 }
 
 /** A live relay. Dispose to tear both directions down. */
@@ -88,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.
  *
@@ -143,7 +165,7 @@ export function relayToPostMessageChannel(
          bufferSubscription?.dispose();
          bufferSubscription = undefined;
          buffered.length = 0;
-         options.reportError?.(error, 'opening the transport to relay');
+         options.reportError?.(error, resolve(RELAY_TRANSPORT_OPEN_FAILED, { detail: describeError(error) }));
          closeFramedSide();
          return false;
       }
@@ -166,12 +188,12 @@ export function relayToPostMessageChannel(
          opened.reader.listen(message => channel.post(message)),
          opened.reader.onClose(() => closeFramedSide()),
          opened.reader.onError(error => {
-            options.reportError?.(error, 'reading from the relayed transport');
+            options.reportError?.(error, resolve(RELAY_TRANSPORT_READ_FAILED, { detail: describeError(error) }));
             closeFramedSide();
          }),
          channel.onMessage(message => {
             void opened.writer.write(message).catch((error: unknown) => {
-               options.reportError?.(error, 'writing to the relayed transport');
+               options.reportError?.(error, resolve(RELAY_TRANSPORT_WRITE_FAILED, { detail: describeError(error) }));
             });
          })
       );
@@ -183,7 +205,7 @@ export function relayToPostMessageChannel(
 
       for (const message of buffered) {
          void opened.writer.write(message).catch((error: unknown) => {
-            options.reportError?.(error, 'replaying a buffered message to the relayed transport');
+            options.reportError?.(error, resolve(RELAY_REPLAY_FAILED, { detail: describeError(error) }));
          });
       }
       buffered.length = 0;

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

@@ -0,0 +1,281 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import type { MessageConnection } from 'vscode-jsonrpc';
+import { type ResolvedMessage, defineMessage, describeError, resolve } from '../messages/primitives';
+import { type RpcProxy, createRpcProxy } from '../rpc';
+import type { DataPort } from './data-port';
+
+/**
+ * The transport never opened. A complete sentence rather than a fragment: a
+ * fragment is nested inside a sentence the framework does not own, so no
+ * translator controls the whole and the composition cannot be made to read
+ * correctly in every language.
+ */
+export const DATA_SERVER_CONNECT_FAILED = defineMessage(
+   'hydranium/protocol/data-server-connect-failed',
+   'Could not connect to the data server: {detail}'
+);
+
+export const DATA_SERVER_NOT_READY = defineMessage(
+   'hydranium/protocol/data-server-not-ready',
+   'The data server did not become ready: {detail}'
+);
+
+/** The one method a connection needs of any server: its startup gate. */
+export interface ReadyServer {
+   waitForReady(): Promise<void>;
+}
+
+/**
+ * Lifecycle reporting, for a host that raises warm-up UI around the two waits.
+ *
+ * Nothing fires until something asks for the connection — the generation is
+ * built on the first {@link RpcConnection.connected}. A host that wants the
+ * sequence at startup drives that call itself, or a workspace where nobody
+ * opens a document reports neither the connect nor the readiness its UI waits
+ * on.
+ */
+export interface RpcConnectionLifecycle {
+   /** A generation is opening its transport, including on each reconnect. */
+   readonly onConnecting?: () => void;
+   /** The server's readiness gate has settled for a generation. */
+   readonly onReady?: () => void;
+   /**
+    * A generation failed to connect or to become ready. The failure is still
+    * reported through {@link DataPort.reportError} and still rejects the
+    * awaiting caller; this is for a host that also drives its own UI.
+    */
+   readonly onFailed?: (error: unknown) => void;
+}
+
+/** Calls each distinct lifecycle's hooks in order; one passed twice is called once. */
+function composeLifecycles(...lifecycles: (RpcConnectionLifecycle | undefined)[]): RpcConnectionLifecycle {
+   const present = [...new Set(lifecycles)].filter((lifecycle): lifecycle is RpcConnectionLifecycle => lifecycle !== undefined);
+   return {
+      onConnecting: () => present.forEach(lifecycle => lifecycle.onConnecting?.()),
+      onReady: () => present.forEach(lifecycle => lifecycle.onReady?.()),
+      onFailed: error => present.forEach(lifecycle => lifecycle.onFailed?.(error))
+   };
+}
+
+/** Everything {@link RpcConnection} needs once a subclass has resolved its defaults. */
+export interface ResolvedRpcConnectionOptions<TClient extends object> {
+   readonly methodNamespace: string;
+   readonly clientMethods: readonly (keyof TClient & string)[];
+   readonly lifecycle: RpcConnectionLifecycle;
+}
+
+/**
+ * One connection generation: its connection, its proxy, and its readiness.
+ *
+ * Named by the `protected` reconnect seams {@link RpcConnection.currentGeneration}
+ * and {@link RpcConnection.awaitReady}, so an override has to name it too.
+ */
+export interface RpcConnectionGeneration<TServer extends object> {
+   readonly connection: Promise<MessageConnection>;
+   readonly server: RpcProxy<TServer>;
+   /** Set on first use; the shared readiness gate for this generation. */
+   ready?: Promise<void>;
+}
+
+/**
+ * One JSON-RPC connection to a head, with the three jobs every host adapter
+ * would otherwise re-derive above {@link DataPort}:
+ *
+ * 1. **Build the typed proxy** over the port's connection, with the caller's
+ *    wire prefix and client-method allowlist.
+ * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
+ *    across concurrent callers. A client can connect before the workspace walk
+ *    finishes, and an early request is then answered correctly from an empty
+ *    registry, which reads as a broken project tier rather than as a race.
+ * 3. **Own the reconnect policy**, by dropping its generation when the port
+ *    disposes and building a fresh one on the next request.
+ *
+ * Bounded only by {@link ReadyServer}, so a head serving a slice of the data
+ * protocol — diagnostics alone, or one with methods excluded — is still a
+ * legal server here. `DataConnection` narrows the bound because its sessions
+ * call the document methods; nothing at this layer does.
+ */
+export class RpcConnection<TServer extends ReadyServer, TClient extends object> {
+   protected readonly methodNamespace: string;
+   protected readonly clientMethods: readonly (keyof TClient & string)[];
+   protected readonly lifecycle: RpcConnectionLifecycle;
+   /** The current generation, or `undefined` before the first request / after a teardown. */
+   protected generation?: RpcConnectionGeneration<TServer>;
+   protected disposed = false;
+   protected readonly portDisposeListener: { dispose(): void };
+
+   constructor(
+      protected readonly port: DataPort,
+      protected readonly client: TClient,
+      options: ResolvedRpcConnectionOptions<TClient>
+   ) {
+      this.methodNamespace = options.methodNamespace;
+      this.clientMethods = options.clientMethods;
+      this.lifecycle = composeLifecycles(port.connectionLifecycle, options.lifecycle);
+      this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
+   }
+
+   /**
+    * The connected, READY server proxy.
+    *
+    * Returns the proxy rather than `void` on purpose. A reconnect replaces the
+    * proxy, so a caller that cached one from an earlier call would go on
+    * addressing a dead connection with no error — handing it back per call
+    * makes the stale reference unrepresentable.
+    *
+    * Concurrent callers share one readiness promise, so `waitForReady` is
+    * awaited once per generation and not once per caller.
+    */
+   async connected(): Promise<RpcProxy<TServer>> {
+      this.assertLive();
+      const generation = this.currentGeneration();
+      if (!generation.ready) {
+         generation.ready = this.awaitReady(generation);
+      }
+      await generation.ready;
+      // Dropped while it opened: its transport is gone, so the call goes to the
+      // next generation, or rejects once this connection is disposed.
+      if (this.generation !== generation) {
+         return this.connected();
+      }
+      return generation.server;
+   }
+
+   /**
+    * The current generation's proxy WITHOUT awaiting readiness — calls queue
+    * against the connection promise.
+    *
+    * **Protected, and that is the point.** An early request is answered
+    * correctly from a registry the workspace walk has not filled yet, which
+    * reads as a broken project tier rather than as a race — so every caller has
+    * to interpose the gate, and every caller forgetting to is a silent bug.
+    * {@link connected} is the public route and returns this same proxy once the
+    * gate has settled, which leaves nothing to forget. The one caller that
+    * cannot use it is {@link awaitReady}, whose whole job is running the gate.
+    *
+    * Read per access, never cached: a reconnect replaces the generation, and a
+    * held reference would address the dead one.
+    */
+   protected get server(): RpcProxy<TServer> {
+      this.assertLive();
+      return this.currentGeneration().server;
+   }
+
+   /**
+    * Surface a failure the way this host does, through the port's sink.
+    *
+    * Here rather than only on the port so every participant sharing the
+    * connection reports through one route without being handed the transport.
+    */
+   reportError(error: unknown, reported: ResolvedMessage): void {
+      this.port.reportError(error, reported);
+   }
+
+   /** Tear down the current connection and stop tracking the port. Idempotent. */
+   dispose(): void {
+      if (this.disposed) {
+         return;
+      }
+      this.disposed = true;
+      this.portDisposeListener.dispose();
+      this.dropGeneration();
+   }
+
+   /** The live generation, building one if there is none. */
+   protected currentGeneration(): RpcConnectionGeneration<TServer> {
+      if (this.generation) {
+         return this.generation;
+      }
+      this.lifecycle.onConnecting?.();
+      const connection = this.port.connect();
+      // Rejection is reported here rather than left to float: an unhandled
+      // rejection on a connection promise is the failure mode that reads as
+      // "the model is empty" instead of "the transport never opened".
+      connection.catch((error: unknown) =>
+         this.port.reportError(error, resolve(DATA_SERVER_CONNECT_FAILED, { detail: describeError(error) }))
+      );
+      const server = createRpcProxy<TServer, TClient>(connection, {
+         methodNamespace: this.methodNamespace,
+         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 {
+         await generation.connection;
+         // Dropped meanwhile: writing the request would hit a closed transport.
+         if (this.generation !== generation) {
+            return;
+         }
+         await generation.server.waitForReady();
+         // Before `onReady`, so a failing restore reports a failure alone.
+         this.generationReady(generation);
+         this.lifecycle.onReady?.();
+      } catch (error: unknown) {
+         // A dropped generation's request fails with its transport, which says
+         // nothing about whether the server is ready.
+         if (this.generation !== generation) {
+            return;
+         }
+         this.lifecycle.onFailed?.(error);
+         // Drop the generation so the next request retries rather than
+         // re-awaiting a settled rejection forever.
+         if (this.generation === generation) {
+            this.generation = undefined;
+         }
+         this.port.reportError(error, resolve(DATA_SERVER_NOT_READY, { detail: describeError(error) }));
+         throw error;
+      }
+   }
+
+   /**
+    * Called once `generation` has passed its readiness gate, whichever request
+    * brought it up. A generation can replace one that failed at readiness
+    * without {@link dropGeneration}, so this, not a drop, is where state kept
+    * on the server is put back. It runs inside the readiness gate, so a throw
+    * from an override fails the generation as a refused gate would.
+    */
+   protected generationReady(_generation: RpcConnectionGeneration<TServer>): void {
+      // Nothing to put back at this layer.
+   }
+
+   /**
+    * Discard the current generation, disposing its connection if it opened.
+    * The next {@link connected} builds a fresh one.
+    */
+   protected dropGeneration(): void {
+      const generation = this.generation;
+      this.generation = undefined;
+      if (!generation) {
+         return;
+      }
+      generation.connection.then(connection => connection.dispose()).catch(() => undefined);
+   }
+
+   protected assertLive(): void {
+      if (this.disposed) {
+         throw new Error(`${this.constructor.name} is disposed`);
+      }
+   }
+}