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

package/src/client/index.ts

@@ -13,8 +13,9 @@
  *
  * 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.
@@ -26,15 +27,17 @@
  * 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. */
@@ -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/rpc-connection.ts

@@ -0,0 +1,235 @@
+/********************************************************************************
+ * 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;
+}
+
+/** 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 = 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;
+      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.client,
+         localMethods: this.clientMethods
+      });
+      this.generation = { connection, server };
+      return this.generation;
+   }
+
+   /** Await the connection and the server's startup gate for one generation. */
+   protected async awaitReady(generation: RpcConnectionGeneration<TServer>): Promise<void> {
+      try {
+         await generation.connection;
+         await generation.server.waitForReady();
+         this.lifecycle.onReady?.();
+      } catch (error: unknown) {
+         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;
+      }
+   }
+
+   /**
+    * 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`);
+      }
+   }
+}

package/src/client-ids.ts

@@ -0,0 +1,45 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Well-known values of the wire's `clientId` / `sourceClientId` field.
+ *
+ * The framework tracks each document as belonging to one or more "clients" —
+ * typically an LSP-text client (Monaco, VS Code, …), a GLSP diagram client,
+ * and/or a structured-form client — and keys its holds and watches per
+ * `(uri, clientId)`. These three values are not real participants, so a client
+ * minting its own id must avoid them.
+ *
+ * **Here rather than in the server package, because the side that has to
+ * RECOGNISE them is the client.** An inbound `onDocumentUpdated` carries
+ * `sourceClientId`, and a consumer deciding what to do with it is asking which
+ * of these it is — so a frontend would otherwise have to depend on the server
+ * tier to name three strings, and in practice retypes the literal instead.
+ */
+
+/** Identifier for an LSP-text client (Monaco, VS Code, …). */
+export const LANGUAGE_CLIENT_ID = 'language-client';
+
+/** Fallback identifier when a document's author is unknown (e.g. cold workspace-init load). */
+export const UNKNOWN_CLIENT_ID = 'unknown';
+
+/**
+ * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
+ * emits after the LAST client closed a document and the framework rebuilt it
+ * from its disk content (discarding unsaved in-session edits). Not a real
+ * client: it lets consumers distinguish the revert broadcast from
+ * client-authored updates.
+ */
+export const REVERT_ON_CLOSE_CLIENT_ID = 'revert-on-close';
+
+/**
+ * Every id the framework reserves, for a client checking that the identity it
+ * is about to mint collides with none of them.
+ */
+export const FRAMEWORK_CLIENT_IDS: readonly string[] = [LANGUAGE_CLIENT_ID, UNKNOWN_CLIENT_ID, REVERT_ON_CLOSE_CLIENT_ID];

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

@@ -20,6 +20,10 @@ import type {
 
 /** Request-method names on {@link DocumentServerProtocol}. */
 export const DOCUMENT_SERVER_PROTOCOL_METHODS = [
+   'createSession',
+   'closeSession',
+   'createModelDocument',
+   'updateModelDocuments',
    'openModelDocument',
    'closeModelDocument',
    'getModelDocument',
@@ -59,9 +63,12 @@ export const REFERENCE_SERVER_PROTOCOL_METHODS = [
 ] as const satisfies ReadonlyArray<keyof ReferenceServerProtocol<TransferElement> & string>;
 
 /** Notification-method names on {@link DocumentClientProtocol}. */
-export const DOCUMENT_CLIENT_PROTOCOL_METHODS = ['onDocumentUpdated', 'onDocumentSaved'] as const satisfies ReadonlyArray<
-   keyof DocumentClientProtocol<TransferElement> & string
->;
+export const DOCUMENT_CLIENT_PROTOCOL_METHODS = [
+   'onDocumentUpdated',
+   'onDocumentSaved',
+   'onDocumentDeleted',
+   'onDocumentsBuilt'
+] as const satisfies ReadonlyArray<keyof DocumentClientProtocol<TransferElement> & string>;
 
 /** Notification-method names on {@link ProjectClientProtocol}. */
 export const PROJECT_CLIENT_PROTOCOL_METHODS = ['onProjectsChanged'] as const satisfies ReadonlyArray<keyof ProjectClientProtocol & string>;

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

@@ -13,13 +13,23 @@ import type { Project } from '../project';
 import type { TransferDocument } from '../transfer-document';
 import type { CloseModelArgs, FindNextNameArgs, OpenModelArgs, ReferenceContext, ReferenceRequest } from '../model-server';
 import type { ReferenceCandidate, ReferenceTarget } from '../model-service/reference-candidate';
-import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from './events';
 import type {
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from './events';
+import type {
+   CloseSessionArgs,
+   CreateModelDocumentArgs,
+   CreateSessionArgs,
    GetModelDocumentArgs,
    GetProjectForUriArgs,
    TransferSaveDocumentArgs,
    WatchModelDocumentArgs,
-   TransferUpdateDocumentArgs
+   TransferUpdateDocumentArgs,
+   TransferUpdateDocumentsArgs
 } from './requests';
 
 /**
@@ -40,35 +50,74 @@ import type {
  */
 export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
    /**
-    * Open a document for an editor session and return its current state.
-    * Registers `(uri, clientId)` with the multi-client document manager
-    * (so concurrent editors share one built document) and returns the
-    * document at the server's configured target phase — the same shape
-    * {@link getModelDocument} returns, except that `version` is taken from
-    * the text-document store so the caller's first `baseVersion` write
-    * cannot self-conflict. Idempotent in registration terms: opening an
-    * already-open document refreshes the client registration. Note it does
-    * NOT avoid a rebuild — a second client attaching triggers
-    * `refreshContent`, which fires a change event, so mounting a form on a
-    * document already open in a text editor rebuilds it.
+    * Register `args.clientId` as a client session owned by this connection.
+    * Rejects with a `DuplicateClientIdError` code when the id is live anywhere
+    * in the server process or reserved by the framework.
+    *
+    * A request carrying a registered id acts as that session: it writes only
+    * what the session has open, failing with a `DocumentNotOpenError` code
+    * otherwise, and opens nothing implicitly; its open reads the file and takes
+    * no `languageId`, `version` or `text` seed. The session ends with
+    * {@link closeSession} or when the connection closes, and either closes
+    * every document it has open.
     *
-    * The default `DataServer` impl delegates to `ModelService.open` then
-    * reads the built state. Pair with {@link watchModelDocument} to receive
-    * subsequent build-phase events (open returns a one-shot snapshot;
-    * later validation diagnostics arrive on the watch channel).
+    * A registration carrying the `resumeToken` an earlier registration of the
+    * same id carried ends that session first, from any connection, so a client
+    * whose connection dropped can register again before the server notices.
+    */
+   createSession(args: CreateSessionArgs): Promise<void>;
+
+   /**
+    * End a session this connection registered: close every document it has
+    * open, drop its watches, and free its id. A no-op for an id this
+    * connection did not register.
+    */
+   closeSession(args: CloseSessionArgs): Promise<void>;
+
+   /**
+    * Create a document with `args.text`, open for the session, and return it
+    * as {@link openModelDocument} does. It reaches disk with the first save.
+    * Fails when the file exists or any client has the URI open, and with a
+    * `SessionClosedError` code when `args.clientId` is not a session
+    * registered on this connection.
     */
-   openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+   createModelDocument(args: CreateModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Close an editor session for `(uri, clientId)`. Counterpart to
-    * {@link openModelDocument}; the underlying document stays built until
-    * every registered client has closed. The default `DataServer` impl
-    * delegates to `ModelService.close` and ALSO releases any watch for the
-    * same `(uri, clientId)` (closing a session frees its own watch — a
-    * forgotten {@link unwatchModelDocument} would otherwise leak dispatch;
-    * the implicit unwatch is idempotent). `watchModelDocument` is NOT
-    * coupled the other way: opening does not force a watch, so a snapshot
-    * reader can open without streaming.
+    * Write several documents the session has open, all or none: a conflict or
+    * a document not open fails the whole set before any text applies.
+    * Resolves to the documents in the order given. Only for a session
+    * registered on this connection.
+    */
+   updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>[]>;
+
+   /**
+    * Open a document for the client session `clientId` and return its current
+    * state. `clientId` must be a session this connection registered with
+    * {@link createSession}; any other id fails with the closed-session code,
+    * as every document request here does. The document is read from disk
+    * unless a client has it open already, so the request carries no
+    * `languageId`, `version` or `text` seed. Returns the document at
+    * the server's configured target phase — the same shape
+    * {@link getModelDocument} returns, except that `version` is taken from the
+    * text-document store so the caller's first `basedOn` write cannot
+    * self-conflict. A repeat open changes nothing.
+    *
+    * Pair with {@link watchModelDocument} to receive subsequent build-phase
+    * events (open returns a one-shot snapshot; later validation diagnostics
+    * arrive on the watch channel).
+    */
+   openModelDocument(args: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Close the session's open of `uri`. Counterpart to
+    * {@link openModelDocument}; the document stays open until every client
+    * has closed it, and the last close reverts it to disk. The default
+    * `DataServer` impl ALSO releases any watch for the same
+    * `(uri, clientId)` (a forgotten {@link unwatchModelDocument} would
+    * otherwise leak dispatch; the implicit unwatch is idempotent).
+    * `watchModelDocument` is NOT coupled the other way: opening does not force
+    * a watch, so a snapshot reader can open without streaming.
     */
    closeModelDocument(args: CloseModelArgs): Promise<void>;
 
@@ -81,14 +130,15 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
    getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Update a document's content. The response carries the latest built
-    * state including diagnostics; callers observe convergence via that
-    * response.
+    * Update a document's content as the session `clientId`, which must have
+    * it open. The response carries the latest built state including
+    * diagnostics; callers observe convergence via that response.
     */
    updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Persist a document to disk. The response is the post-save document
+    * Write a document as the session `clientId`, which must have it open, and
+    * persist it to disk. The response is the post-save document
     * state (matches the file on disk). Save semantics depend on the
     * filesystem-provider wiring; rejection paths surface as awaited
     * promise rejections.
@@ -194,6 +244,22 @@ export interface DataServerProtocol<
 >
    extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {}
 
+/**
+ * The diagnostic shape a server answers with, read back off its own
+ * declaration.
+ *
+ * This is what lets a client tier stay generic over the server alone and still
+ * describe what it hands back. Both parameters must be inferred: naming
+ * {@link TransferElement} for the transfer instead fails to match while that
+ * parameter is still generic, and a default declared against the constraint
+ * then stops satisfying it.
+ */
+export type DiagnosticOf<TServer> =
+   TServer extends DocumentServerProtocol<infer _TTransfer, infer TDiagnostic> ? TDiagnostic : TransferDiagnostic;
+
+/** The project shape a server answers with, read back off its own declaration. */
+export type ProjectOf<TServer> = TServer extends ProjectServerProtocol<infer TProject> ? TProject : Project;
+
 /**
  * Cross-reference / naming slice of the server surface — scope-aware
  * queries that resolve against the language's reference services. NOT part
@@ -262,6 +328,28 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
     * codepath, not a subscription codepath).
     */
    onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+
+   /**
+    * Delivered when a document's backing file was removed. Separate from
+    * {@link onDocumentUpdated} for the same reason as {@link onDocumentSaved},
+    * and more strongly: there is no built state to deliver, and the build-phase
+    * path cannot report a deletion at all.
+    *
+    * Ungated, because on a browser host — where the workspace lives behind the
+    * head — no other source can observe a file disappearing. Recipients that
+    * only care about their own documents filter by URI.
+    */
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void;
+
+   /**
+    * Delivered once per build, naming the documents that reached the
+    * subscription phase and that
+    * nobody on this connection watches — chiefly the ones rebuilt as a cascade
+    * from a dependency's change, which no filesystem watcher can see because
+    * their own files did not change. The complement of
+    * {@link onDocumentUpdated}; carries URIs and no documents.
+    */
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void;
 }
 
 /**