@hydranium/protocol 1.0.0-next.11 → 1.0.0-next.111

package/lib/transfer-document.d.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 import type { TransferDiagnostic } from './transfer-diagnostic';
 import type { TransferElement } from './transfer-element';
+import { type SnapshotVersion } from './model-service/based-on';
 /**
  * Wire envelope exchanged between the model-server's data-server head and
  * its clients. Carries a transfer-shaped root — never an AST root — plus
@@ -25,14 +26,14 @@ export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic
     uri: string;
     /**
      * The document version this snapshot was taken at — sourced from the
-     * server's text-document version counter. Callers that mutate the
-     * document subsequently pass this value back as `TransferUpdateArgs.baseVersion`
-     * (or `TransferSaveArgs.baseVersion`) so the server can detect stale-based
-     * updates and reject them with `ConflictError`.
+     * server's text-document version counter. A caller that mutates the document
+     * subsequently sends this straight back as `TransferUpdateArgs.basedOn` (or
+     * `TransferSaveArgs.basedOn`), and the server rejects a stale-based update
+     * with `ConflictError`.
      *
      * See `@hydranium/protocol#errors` for the conflict-detection contract.
      */
-    version: number;
+    version: SnapshotVersion;
     /**
      * Absent when the document does not exist — the server answers an unknown URI
      * with a shaped envelope rather than an error, so absence is an ordinary
@@ -62,6 +63,15 @@ export declare namespace TransferDocument {
      * with it.
      */
     function assertLoaded<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(document: TransferDocument<TTransfer, TDiagnostic>): LoadedTransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * The envelope for a document the server does not have — `root` absent, and
+     * the version a read of a URI the store never saw reports.
+     *
+     * Exists so the absent branch is built the same way the present one is: both
+     * doors mark the version as coming from a read, and neither asks a caller to
+     * do it.
+     */
+    function absent<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic>(uri: string, diagnostics?: TDiagnostic[]): TransferDocument<TTransfer, TDiagnostic>;
     /**
      * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
      * to `[]` so test fixtures, fake protocol implementations, and the

package/lib/transfer-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-document.d.ts","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IAClG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACvH,SAAS,EACT,WAAW,CACb,GAAG;IACD,IAAI,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,yBAAiB,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,SAAgB,QAAQ,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACzF,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,QAAQ,IAAI,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE5D;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EAC7F,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAKhD;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,WAAW,GAAE,WAAW,EAAO,GAC/B,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;CACH"}
+{"version":3,"file":"transfer-document.d.ts","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEnF;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IAClG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,OAAO,EAAE,eAAe,CAAC;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACvH,SAAS,EACT,WAAW,CACb,GAAG;IACD,IAAI,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,yBAAiB,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,SAAgB,QAAQ,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACzF,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,QAAQ,IAAI,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE5D;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EAC7F,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAKhD;IAED;;;;;;;OAOG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,WAAW,GAAE,WAAW,EAAO,GAC/B,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,WAAW,GAAE,WAAW,EAAO,GAC/B,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;CACH"}

package/lib/transfer-document.js

@@ -9,6 +9,7 @@
  ********************************************************************************/
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TransferDocument = void 0;
+const based_on_1 = require("./model-service/based-on");
 var TransferDocument;
 (function (TransferDocument) {
     /**
@@ -32,6 +33,18 @@ var TransferDocument;
         return document;
     }
     TransferDocument.assertLoaded = assertLoaded;
+    /**
+     * The envelope for a document the server does not have — `root` absent, and
+     * the version a read of a URI the store never saw reports.
+     *
+     * Exists so the absent branch is built the same way the present one is: both
+     * doors mark the version as coming from a read, and neither asks a caller to
+     * do it.
+     */
+    function absent(uri, diagnostics = []) {
+        return { uri, version: (0, based_on_1.asSnapshotVersion)(0), root: undefined, diagnostics };
+    }
+    TransferDocument.absent = absent;
     /**
      * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
      * to `[]` so test fixtures, fake protocol implementations, and the
@@ -39,7 +52,7 @@ var TransferDocument;
      * at every call site.
      */
     function create(uri, version, root, diagnostics = []) {
-        return { uri, version, root, diagnostics };
+        return { uri, version: (0, based_on_1.asSnapshotVersion)(version), root, diagnostics };
     }
     TransferDocument.create = create;
 })(TransferDocument || (exports.TransferDocument = TransferDocument = {}));

package/lib/transfer-document.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-document.js","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAmDlF,IAAiB,gBAAgB,CAwChC;AAxCD,WAAiB,gBAAgB;IAC9B;;;OAGG;IACH,SAAgB,QAAQ,CACrB,QAAkD;QAElD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;IACtC,CAAC;IAJe,yBAAQ,WAIvB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CACzB,QAAkD;QAElD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IAPe,6BAAY,eAO3B,CAAA;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,OAAe,EACf,IAAe,EACf,cAA6B,EAAE;QAE/B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC9C,CAAC;IAPe,uBAAM,SAOrB,CAAA;AACJ,CAAC,EAxCgB,gBAAgB,gCAAhB,gBAAgB,QAwChC"}
+{"version":3,"file":"transfer-document.js","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAIlF,uDAAmF;AAgDnF,IAAiB,gBAAgB,CAuDhC;AAvDD,WAAiB,gBAAgB;IAC9B;;;OAGG;IACH,SAAgB,QAAQ,CACrB,QAAkD;QAElD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;IACtC,CAAC;IAJe,yBAAQ,WAIvB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CACzB,QAAkD;QAElD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IAPe,6BAAY,eAO3B,CAAA;IAED;;;;;;;OAOG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,cAA6B,EAAE;QAE/B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAA,4BAAiB,EAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IAC/E,CAAC;IALe,uBAAM,SAKrB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,OAAe,EACf,IAAe,EACf,cAA6B,EAAE;QAE/B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAA,4BAAiB,EAAC,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC1E,CAAC;IAPe,uBAAM,SAOrB,CAAA;AACJ,CAAC,EAvDgB,gBAAgB,gCAAhB,gBAAgB,QAuDhC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.11",
+  "version": "1.0.0-next.111",
   "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
   "keywords": [
     "hydranium",
@@ -41,6 +41,14 @@
       "types": "./lib/data/index.d.ts",
       "default": "./lib/data/index.js"
     },
+    "./messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
+    "./lib/messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
     "./testing": {
       "types": "./lib/testing/index.d.ts",
       "default": "./lib/testing/index.js"
@@ -88,7 +96,7 @@
     "vscode-jsonrpc": "9.0.1"
   },
   "peerDependencies": {
-    "vscode-jsonrpc": "^8.0.0 || ^9.0.0"
+    "vscode-jsonrpc": "9.0.1"
   },
   "engines": {
     "node": ">=22.13"
@@ -96,5 +104,6 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest, and docs/adopting/requirements.md carries the block to paste.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error."
 }

package/src/client/data-connection.ts

@@ -0,0 +1,266 @@
+/********************************************************************************
+ * 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 { FRAMEWORK_CLIENT_IDS } from '../client-ids';
+import {
+   DATA_CLIENT_PROTOCOL_METHODS,
+   DATA_SERVER_WIRE_PREFIX,
+   type DataClientProtocol,
+   type DataServerProtocol,
+   type DiagnosticOf,
+   type ProjectOf
+} from '../data';
+import type { TransferElement } from '../transfer-element';
+import { DataEvents } from './data-events';
+import type { DataPort } from './data-port';
+import { DataSession } from './data-session';
+import { RpcConnection, type RpcConnectionLifecycle } from './rpc-connection';
+
+/** Options for {@link DataConnection}. */
+export interface DataConnectionOptions extends RpcConnectionLifecycle {
+   /**
+    * Wire namespace the server is addressed under. Defaults to the
+    * framework's {@link DATA_SERVER_WIRE_PREFIX}, which is what an unmodified
+    * `DataServer` binds. Override only alongside the server's own
+    * `methodNamespace` option — a mismatch turns every request into
+    * "Unhandled method" rather than failing at wire-up.
+    */
+   readonly methodNamespace?: string;
+}
+
+/** {@link DataConnectionOptions} for a client that does not speak {@link DataClientProtocol}. */
+export interface DataConnectionOptionsWithMethods<TClient extends object> extends DataConnectionOptions {
+   /**
+    * Method names of the client to bind as inbound handlers. Declare it
+    * `as const satisfies ReadonlyArray<keyof YourClient & string>` so the list
+    * cannot drift from the interface.
+    */
+   readonly clientMethods: readonly (keyof TClient & string)[];
+}
+
+/**
+ * Trailing constructor arguments, required only when the client cannot take
+ * the framework's default method list.
+ *
+ * `bindRpcMethods` throws for a name the target does not implement, so a
+ * request/response-only client binding the default list fails at wire-up. The
+ * conditional turns that into a compile error.
+ */
+export type DataConnectionArgs<TTransfer extends TransferElement, TClient extends object> =
+   TClient extends DataClientProtocol<TTransfer>
+      ? [options?: DataConnectionOptions & Partial<DataConnectionOptionsWithMethods<TClient>>]
+      : [options: DataConnectionOptionsWithMethods<TClient>];
+
+/**
+ * A {@link RpcConnection} to the data head, carrying as many participants as
+ * the host has interested parties.
+ *
+ * Document operations live on the participants rather than here: they carry a
+ * `clientId`, which identifies a participant rather than a wire, and the server
+ * keys its holds and watches per `(uri, clientId)`. Two parties sharing one
+ * identity cannot tell each other's writes from their own echoes.
+ *
+ * Generic over the transfer root so this file names no grammar. An adopter
+ * binds the concrete root (or the union of them, for a multi-grammar head) at
+ * its own edge.
+ */
+export class DataConnection<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>,
+   TClient extends object = DataClientProtocol<TTransfer>
+> extends RpcConnection<TServer, TClient> {
+   protected readonly sessions = new Set<DataSession<TTransfer, TServer>>();
+   /**
+    * Holds a disposed session could not release, keyed `clientId` + `uri` so a
+    * repeated handover does not queue the same close twice.
+    *
+    * Retried on this connection's own activity rather than on a timer: every
+    * session operation asks for the proxy, so a shared connection with anything
+    * else going on supplies the occasions, and one with nothing going on has
+    * nobody whose documents the stale hold could affect.
+    */
+   protected readonly orphanedHolds = new Map<string, { readonly uri: string; readonly clientId: string }>();
+   /** Guards {@link releaseOrphanedHolds} against re-entering through its own proxy lookup. */
+   protected releasingOrphans = false;
+
+   constructor(port: DataPort, client: TClient, ...rest: DataConnectionArgs<TTransfer, TClient>) {
+      const [options = {}] = rest as [(DataConnectionOptions & Partial<DataConnectionOptionsWithMethods<TClient>>)?];
+      super(port, client, {
+         methodNamespace: options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
+         // The default is reachable only where `TClient` satisfies
+         // `DataClientProtocol`, which the constructor's conditional enforces;
+         // the compiler cannot carry that through to the generic parameter.
+         clientMethods: options.clientMethods ?? (DATA_CLIENT_PROTOCOL_METHODS as unknown as readonly (keyof TClient & string)[]),
+         lifecycle: options
+      });
+   }
+
+   /**
+    * Mint a participant on this connection under `clientId`.
+    *
+    * `clientId` must be distinct per participant and stable for its lifetime:
+    * it keys the server's per-`(uri, clientId)` hold and watch, and it is the
+    * echo key an inbound `onDocumentUpdated` is matched against.
+    *
+    * Throws for an id in {@link FRAMEWORK_CLIENT_IDS} — those are authors the
+    * SERVER emits rather than participants, so a session holding one would read
+    * the framework's own broadcasts as its own echoes and drop them. Nothing
+    * about that fails on its own: the document simply stops following, which
+    * looks like a dead connection.
+    *
+    * Throws, too, for an id a LIVE session on this connection already holds.
+    * Per-document membership is a set of client ids, so two participants
+    * sharing one collapse to a single hold and the first close releases it
+    * under the survivor, which then stops receiving updates for a document it
+    * is still showing. A constant bound once per participant KIND — one per
+    * widget class rather than per instance — satisfies the type and violates
+    * this.
+    *
+    * And throws for an id whose previous session left a hold this connection is
+    * still trying to release. That release closes `(uri, clientId)`, so an id
+    * reissued while it is outstanding can have the new participant's hold closed
+    * out from under it. The id frees itself as soon as the release lands.
+    *
+    * The checks span this connection only, so a head several connections reach
+    * can still be addressed twice under one id.
+    */
+   createSession(clientId: string): DataSession<TTransfer, TServer> {
+      this.assertLive();
+      if (FRAMEWORK_CLIENT_IDS.includes(clientId)) {
+         throw new Error(`clientId '${clientId}' is reserved by the framework and cannot identify a participant`);
+      }
+      if ([...this.sessions].some(session => session.clientId === clientId)) {
+         throw new Error(`clientId '${clientId}' already identifies a live participant on this connection`);
+      }
+      if ([...this.orphanedHolds.values()].some(hold => hold.clientId === clientId)) {
+         // A retry is still outstanding for this id, and it closes
+         // `(uri, clientId)` — which the server keys one hold per. Handing the
+         // id over now lets that close land on the NEW participant's hold
+         // instead, taking a document away from a session that opened it
+         // successfully. Nothing about that fails on its own: the document
+         // simply stops following, and the close that did it was issued for a
+         // participant already gone.
+         //
+         // Attempted first, so an id whose release has become possible is free
+         // by the next call rather than waiting for other traffic.
+         void this.releaseOrphanedHolds();
+         throw new Error(`clientId '${clientId}' has an unreleased hold on this connection and cannot identify a new participant yet`);
+      }
+      const session = new DataSession<TTransfer, TServer>(clientId, {
+         connected: async () => {
+            const server = await this.connected();
+            // Unawaited: a session's own operation must not wait on, or fail
+            // for, the release of a hold another participant abandoned.
+            void this.releaseOrphanedHolds();
+            return server;
+         },
+         releaseSession: released => this.sessions.delete(released),
+         orphanHold: (uri, holder) => this.orphanHold(uri, holder)
+      });
+      this.sessions.add(session);
+      return session;
+   }
+
+   /**
+    * Take over a `(uri, clientId)` hold a disposed session could not release.
+    *
+    * One attempt is made straight away, since whatever refused the session's
+    * close may already be over; a refusal leaves the entry for the next
+    * operation on this connection to retry.
+    */
+   protected orphanHold(uri: string, clientId: string): void {
+      this.orphanedHolds.set(`${clientId}\u0000${uri}`, { uri, clientId });
+      void this.releaseOrphanedHolds();
+   }
+
+   /**
+    * Try to close every hold handed over by a disposed session, keeping the ones
+    * the server still refuses.
+    *
+    * Errors are swallowed per entry: this runs off another participant's
+    * operation, which has no interest in an unrelated release and no caller to
+    * surface it to. A hold that survives every attempt is released by the
+    * server's connection-close cleanup.
+    */
+   protected async releaseOrphanedHolds(): Promise<void> {
+      if (this.releasingOrphans || this.orphanedHolds.size === 0 || this.disposed) {
+         return;
+      }
+      this.releasingOrphans = true;
+      try {
+         const server = await this.connected();
+         for (const [key, hold] of [...this.orphanedHolds]) {
+            try {
+               await server.closeModelDocument({ uri: hold.uri, clientId: hold.clientId });
+               this.orphanedHolds.delete(key);
+            } catch {
+               // Kept for the next occasion.
+            }
+         }
+      } catch {
+         // No proxy to release through; the entries wait for one.
+      } finally {
+         this.releasingOrphans = false;
+      }
+   }
+
+   /**
+    * Sessions are detached rather than disposed: the server releases every hold
+    * on a connection it sees close, so closing each document first sends
+    * requests over a connection this call is about to dispose.
+    */
+   override dispose(): void {
+      for (const session of [...this.sessions]) {
+         session.detach();
+      }
+      this.sessions.clear();
+      // Dropped rather than closed, for the same reason the sessions detach: the
+      // server releases every hold on a connection it sees close, and the close
+      // would travel over the connection being disposed.
+      this.orphanedHolds.clear();
+      super.dispose();
+   }
+}
+
+/**
+ * A {@link DataConnection} that brings its own {@link DataEvents}, so a host
+ * with several interested parties does not have to supply one.
+ *
+ * **The client slot holds exactly one object, and that is why this exists.**
+ * `createRpcProxy` binds a single `localTarget`, and underneath a method name
+ * maps to one handler — a second registration replaces the first silently. So a
+ * properties panel and a tree cannot both be the client; one fan-out sits in the
+ * slot and both subscribe to it.
+ *
+ * Use {@link DataConnection} directly instead when the client is yours: an
+ * adopter service that implements the protocol plus its own methods, a single
+ * consumer that IS the client, or a request/response-only client that binds
+ * nothing.
+ */
+export class DataConnectionWithEvents<
+   TTransfer extends TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> extends DataConnection<TTransfer, TServer, DataEvents<TTransfer, DiagnosticOf<TServer>, ProjectOf<TServer>>> {
+   /** Server pushes, fanned out to as many local listeners as the host has. */
+   readonly events: DataEvents<TTransfer, DiagnosticOf<TServer>, ProjectOf<TServer>>;
+
+   constructor(port: DataPort, options?: DataConnectionOptions) {
+      // Built as a local because `this` is unavailable before `super`, then
+      // read back onto the field.
+      const events = new DataEvents<TTransfer, DiagnosticOf<TServer>, ProjectOf<TServer>>();
+      super(port, events, options);
+      this.events = events;
+   }
+
+   /** Disposes the fan-out it created, which no caller else holds. */
+   override dispose(): void {
+      super.dispose();
+      this.events.dispose();
+   }
+}

package/src/client/data-events.ts

@@ -8,7 +8,14 @@
  ********************************************************************************/
 
 import { Emitter, type Event } from 'vscode-jsonrpc';
-import type { DataClientProtocol, ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from '../data';
+import type {
+   DataClientProtocol,
+   ProjectsChangedEvent,
+   TransferDocumentDeletedEvent,
+   TransferDocumentSavedEvent,
+   TransferDocumentsBuiltEvent,
+   TransferDocumentUpdatedEvent
+} from '../data';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -40,12 +47,18 @@ export class DataEvents<
 > implements DataClientProtocol<TTransfer, TDiagnostic, TProject> {
    protected readonly documentUpdatedEmitter = new Emitter<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>();
    protected readonly documentSavedEmitter = new Emitter<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>();
+   protected readonly documentDeletedEmitter = new Emitter<TransferDocumentDeletedEvent>();
+   protected readonly documentsBuiltEmitter = new Emitter<TransferDocumentsBuiltEvent>();
    protected readonly projectsChangedEmitter = new Emitter<ProjectsChangedEvent<TProject>>();
 
    /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
    readonly onDidUpdateDocument: Event<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>> = this.documentUpdatedEmitter.event;
    /** A watched document was persisted to disk. */
    readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>> = this.documentSavedEmitter.event;
+   /** A document's backing file was removed, watched or not. Any watch survives. */
+   readonly onDidDeleteDocument: Event<TransferDocumentDeletedEvent> = this.documentDeletedEmitter.event;
+   /** Documents built that nobody watches — re-read anything derived from them. */
+   readonly onDidBuildDocuments: Event<TransferDocumentsBuiltEvent> = this.documentsBuiltEmitter.event;
    /** The project set changed. */
    readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>> = this.projectsChangedEmitter.event;
 
@@ -59,6 +72,14 @@ export class DataEvents<
       this.documentSavedEmitter.fire(event);
    }
 
+   onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
+      this.documentDeletedEmitter.fire(event);
+   }
+
+   onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void {
+      this.documentsBuiltEmitter.fire(event);
+   }
+
    onProjectsChanged(event: ProjectsChangedEvent<TProject>): void {
       this.projectsChangedEmitter.fire(event);
    }
@@ -66,6 +87,8 @@ export class DataEvents<
    dispose(): void {
       this.documentUpdatedEmitter.dispose();
       this.documentSavedEmitter.dispose();
+      this.documentDeletedEmitter.dispose();
+      this.documentsBuiltEmitter.dispose();
       this.projectsChangedEmitter.dispose();
    }
 }

package/src/client/data-port.ts

@@ -8,21 +8,25 @@
  ********************************************************************************/
 
 import type { Event, MessageConnection } from 'vscode-jsonrpc';
+import type { ResolvedMessage } from '../messages/primitives';
 
 /**
  * The one thing a host has to supply for the data head: a live JSON-RPC
- * connection to the data server, plus the identity and failure sink that go
- * with it.
+ * connection to the data server, plus the failure sink that goes with it.
  *
- * "Port" in the hexagonal sense — the host implements it, `DataSession`
+ * "Port" in the hexagonal sense — the host implements it, `DataConnection`
  * consumes it, and nothing on either side of the boundary imports the other.
  *
+ * Carries no identity. A `clientId` names a participant, and one transport
+ * serves as many as the host has; binding an identity here is what makes two
+ * of them share one, so it lives on `DataSession` instead.
+ *
  * **This deliberately does NOT wrap the protocol methods.** `createRpcProxy`
  * already takes a promise of a connection and produces the whole typed
  * `DataServerProtocol` surface, so wrapping it would re-derive the framework's
  * pass-throughs in a second place and lose the `as const satisfies keyof`
  * method allowlists, which cannot drift. Everything a form or a tree actually
- * does — the wire contract, the open/watch/update/close sequence, `baseVersion`
+ * does — the wire contract, the open/watch/update/close sequence, `basedOn`
  * conflict handling, echo filtering by `sourceClientId` — is host-invariant and
  * lives above this interface. What varies between hosts is exactly the four
  * members below.
@@ -45,22 +49,6 @@ import type { Event, MessageConnection } from 'vscode-jsonrpc';
  *   calls on the promise but never calls `listen` itself.
  */
 export interface DataPort {
-   /**
-    * Stable identity of this client on the data server, passed as `clientId`
-    * on every document request.
-    *
-    * It has to be stable for the session because it is the echo key: an
-    * inbound `onDocumentUpdated` carries the originating mutation's
-    * `clientId` as `sourceClientId`, and a client that cannot recognise its
-    * own echo treats its own write as a concurrent third-party one. It also
-    * has to be distinct per client, since it keys the server's per-
-    * `(uri, clientId)` watch bucket.
-    *
-    * Avoid the three values the framework itself uses as sentinels —
-    * `'language-client'`, `'unknown'` and `'revert-on-close'`.
-    */
-   readonly clientId: string;
-
    /**
     * Open the transport and hand back a listening `MessageConnection`.
     *
@@ -77,10 +65,16 @@ export interface DataPort {
     *
     * It exists because the alternative is worse in both directions: this tier
     * cannot import a host's UI, and swallowing the error makes a dead
-    * connection look like an empty model. `context` names what was being
-    * attempted, not where in the code it happened.
+    * connection look like an empty model.
+    *
+    * `reported` is a complete sentence plus the identity needed to render it in
+    * another language. It carries a value rather than using a protocol field
+    * because this tier does not know whether a process hop intervenes — in a
+    * webview host the render happens across one — and a `ResolvedMessage` is
+    * structured-clone safe either way. Render it with `renderFrameworkMessage`;
+    * passing no translation map yields the English.
     */
-   reportError(error: unknown, context: string): void;
+   reportError(error: unknown, reported: ResolvedMessage): void;
 
    /**
     * Fires when the host tears the transport down and the current connection