@hydranium/protocol 1.0.0-next.60 → 1.0.0-next.61

package/lib/client/data-connection.d.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * 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 DataClientProtocol, type DataServerProtocol } from '../data';
+import type { TransferElement } from '../transfer-element';
+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 declare class DataConnection<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer> = DataServerProtocol<TTransfer>, TClient extends object = DataClientProtocol<TTransfer>> extends RpcConnection<TServer, TClient> {
+    protected readonly sessions: Set<DataSession<TTransfer, TServer>>;
+    constructor(port: DataPort, client: TClient, ...rest: DataConnectionArgs<TTransfer, TClient>);
+    /**
+     * 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. Avoid the
+     * three values the framework uses as sentinels — `'language-client'`,
+     * `'unknown'` and `'revert-on-close'`.
+     */
+    createSession(clientId: string): DataSession<TTransfer, TServer>;
+    /**
+     * 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.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=data-connection.d.ts.map

package/lib/client/data-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-connection.d.ts","sourceRoot":"","sources":["../../src/client/data-connection.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAyD,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClI,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,0CAA0C;AAC1C,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IAClE;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,iGAAiG;AACjG,MAAM,WAAW,gCAAgC,CAAC,OAAO,SAAS,MAAM,CAAE,SAAQ,qBAAqB;IACpG;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;CAC9D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,CAAC,SAAS,SAAS,eAAe,EAAE,OAAO,SAAS,MAAM,IACrF,OAAO,SAAS,kBAAkB,CAAC,SAAS,CAAC,GACxC,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,gCAAgC,CAAC,OAAO,CAAC,CAAC,CAAC,GACtF,CAAC,OAAO,EAAE,gCAAgC,CAAC,OAAO,CAAC,CAAC,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc,CACxB,SAAS,SAAS,eAAe,EACjC,OAAO,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,EAC7E,OAAO,SAAS,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CACvD,SAAQ,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC;IACtC,SAAS,CAAC,QAAQ,CAAC,QAAQ,uCAA8C;gBAE7D,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC;IAY5F;;;;;;;;OAQG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC;IAUhE;;;;OAIG;IACM,OAAO,IAAI,IAAI;CAO1B"}

package/lib/client/data-connection.js

@@ -0,0 +1,73 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataConnection = void 0;
+const data_1 = require("../data");
+const data_session_1 = require("./data-session");
+const rpc_connection_1 = require("./rpc-connection");
+/**
+ * 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.
+ */
+class DataConnection extends rpc_connection_1.RpcConnection {
+    sessions = new Set();
+    constructor(port, client, ...rest) {
+        const [options = {}] = rest;
+        super(port, client, {
+            methodNamespace: options.methodNamespace ?? data_1.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_1.DATA_CLIENT_PROTOCOL_METHODS,
+            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. Avoid the
+     * three values the framework uses as sentinels — `'language-client'`,
+     * `'unknown'` and `'revert-on-close'`.
+     */
+    createSession(clientId) {
+        this.assertLive();
+        const session = new data_session_1.DataSession(clientId, {
+            connected: () => this.connected(),
+            releaseSession: released => this.sessions.delete(released)
+        });
+        this.sessions.add(session);
+        return session;
+    }
+    /**
+     * 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.
+     */
+    dispose() {
+        for (const session of [...this.sessions]) {
+            session.detach();
+        }
+        this.sessions.clear();
+        super.dispose();
+    }
+}
+exports.DataConnection = DataConnection;
+//# sourceMappingURL=data-connection.js.map

package/lib/client/data-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-connection.js","sourceRoot":"","sources":["../../src/client/data-connection.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,kCAAkI;AAGlI,iDAA6C;AAC7C,qDAA8E;AAqC9E;;;;;;;;;;;;GAYG;AACH,MAAa,cAIX,SAAQ,8BAA+B;IACnB,QAAQ,GAAG,IAAI,GAAG,EAAmC,CAAC;IAEzE,YAAY,IAAc,EAAE,MAAe,EAAE,GAAG,IAA4C;QACzF,MAAM,CAAC,OAAO,GAAG,EAAE,CAAC,GAAG,IAAuF,CAAC;QAC/G,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE;YACjB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,8BAAuB;YACnE,0DAA0D;YAC1D,sEAAsE;YACtE,mEAAmE;YACnE,aAAa,EAAE,OAAO,CAAC,aAAa,IAAK,mCAA+E;YACxH,SAAS,EAAE,OAAO;SACpB,CAAC,CAAC;IACN,CAAC;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,QAAgB;QAC3B,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,IAAI,0BAAW,CAAqB,QAAQ,EAAE;YAC3D,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE;YACjC,cAAc,EAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC;SAC5D,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,OAAO,OAAO,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACM,OAAO;QACb,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC;CACH;AAlDD,wCAkDC"}

package/lib/client/data-port.d.ts

@@ -10,12 +10,15 @@ 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
@@ -44,21 +47,6 @@ import type { ResolvedMessage } from '../messages/primitives';
  *   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`.
      *

package/lib/client/data-port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-port.d.ts","sourceRoot":"","sources":["../../src/client/data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,QAAQ;IACtB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAE7D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CAClC"}
+{"version":3,"file":"data-port.d.ts","sourceRoot":"","sources":["../../src/client/data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,QAAQ;IACtB;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAE7D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CAClC"}

package/lib/client/data-session.d.ts

@@ -6,89 +6,52 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import type { MessageConnection } from 'vscode-jsonrpc';
-import { type DataClientProtocol, type DataServerProtocol } from '../data';
-import { type RpcProxy } from '../rpc';
+import type { DataServerProtocol, TransferSaveDocumentArgs, TransferUpdateDocumentArgs } from '../data';
+import type { RpcProxy } from '../rpc';
 import type { TransferDocument } from '../transfer-document';
 import type { TransferElement } from '../transfer-element';
-import type { DataPort } from './data-port';
+/** Update a document through a session; the session supplies `clientId`. */
+export type DataSessionUpdateArgs<TTransfer> = Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>;
+/** Persist a document through a session; the session supplies `clientId`. */
+export type DataSessionSaveArgs<TTransfer> = Omit<TransferSaveDocumentArgs<TTransfer>, 'clientId'>;
 /**
- * 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.
+ * What a {@link DataSession} needs from the connection that minted it.
+ *
+ * Narrower than the connection itself so the dependency points one way:
+ * `DataConnection` constructs sessions, and nothing here imports it back.
  */
-export declare const DATA_SERVER_CONNECT_FAILED: import("../messages/primitives").MessageDefinition<"Could not connect to the data server: {detail}">;
-export declare const DATA_SERVER_NOT_READY: import("../messages/primitives").MessageDefinition<"The data server did not become ready: {detail}">;
-/** Options for {@link DataSession}. */
-export interface DataSessionOptions {
-    /**
-     * 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;
-}
-/** One connection generation: its connection, its proxy, and its readiness. */
-interface Generation<TTransfer extends TransferElement> {
-    readonly connection: Promise<MessageConnection>;
-    readonly server: RpcProxy<DataServerProtocol<TTransfer>>;
-    /** Set on first use; the shared readiness gate for this generation. */
-    ready?: Promise<void>;
+export interface DataSessionHost<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer>> {
+    connected(): Promise<RpcProxy<TServer>>;
+    releaseSession(session: DataSession<TTransfer, TServer>): void;
 }
 /**
- * The host-invariant half of talking to the data head: everything above
- * {@link DataPort} that would otherwise be re-derived by every host
- * adapter.
- *
- * Three jobs, and deliberately no fourth:
+ * One participant on a data connection: a properties panel, a tree, a
+ * form editor.
  *
- * 1. **Build the typed proxy** over the port's connection, with the framework's
- *    wire prefix and its drift-proof client-method allowlist.
- * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
- *    across concurrent callers. A socket 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 connection generation when
- *    the port disposes and building a fresh one on the next request.
+ * The server keys every hold and watch per `(uri, clientId)`, so the identity
+ * belongs to the participant rather than to the wire — several sessions share
+ * one connection, and two participants forced to share one identity cannot
+ * distinguish each other's writes from their own echoes.
  *
- * It does **not** wrap the protocol methods; callers reach them through
- * {@link connected}. The one exception is {@link openDocument}, which exists
- * because the open/watch *order* is silently wrong the other way round — see
- * its own doc.
+ * Every document operation stamps {@link clientId} itself. A caller that
+ * passed its own could pass another participant's, and the server would
+ * attribute the write and release the hold accordingly.
  *
- * 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.
+ * Generic over the transfer root so this file names no grammar.
  */
-export declare class DataSession<TTransfer extends TransferElement> {
-    protected readonly port: DataPort;
-    protected readonly client: DataClientProtocol<TTransfer>;
-    protected readonly methodNamespace: string;
-    /** The current generation, or `undefined` before the first request / after a teardown. */
-    protected generation?: Generation<TTransfer>;
+export declare class DataSession<TTransfer extends TransferElement, TServer extends DataServerProtocol<TTransfer> = DataServerProtocol<TTransfer>> {
+    readonly clientId: string;
+    protected readonly host: DataSessionHost<TTransfer, TServer>;
+    /** URIs this session holds open, so {@link dispose} can release exactly those. */
+    protected readonly openUris: Set<string>;
     protected disposed: boolean;
-    protected readonly portDisposeListener: {
-        dispose(): void;
-    };
-    constructor(port: DataPort, client: DataClientProtocol<TTransfer>, options?: DataSessionOptions);
-    /** The identity every request is made under — the port's, not a second one. */
-    get clientId(): string;
+    constructor(clientId: string, host: DataSessionHost<TTransfer, TServer>);
     /**
-     * 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.
+     * The connected, READY server proxy, for protocol methods this session does
+     * not wrap — the ones carrying no `clientId`, so no identity can be got
+     * wrong through them.
      */
-    connected(): Promise<RpcProxy<DataServerProtocol<TTransfer>>>;
+    connected(): Promise<RpcProxy<TServer>>;
     /**
      * Open `uri` for editing and start watching it, in that order, returning
      * the opened snapshot.
@@ -113,25 +76,36 @@ export declare class DataSession<TTransfer extends TransferElement> {
      * {@link openDocument} and needs no separate unwatch.
      */
     closeDocument(uri: string): Promise<void>;
+    /** Write `args.model` back as this session. */
+    updateDocument(args: DataSessionUpdateArgs<TTransfer>): Promise<TransferDocument<TTransfer>>;
+    /** Persist `args.model` to disk as this session. */
+    saveDocument(args: DataSessionSaveArgs<TTransfer>): Promise<TransferDocument<TTransfer>>;
     /**
-     * Whether `event.sourceClientId` identifies this session's own write.
+     * Whether `sourceClientId` identifies this session's own write.
      *
      * Every watcher needs this and the check is one comparison, so getting it
      * wrong is cheap to do and expensive to find: an unfiltered echo looks
      * exactly like a concurrent third-party edit.
      */
     isOwnEcho(sourceClientId: string): boolean;
-    /** Tear down the current connection and stop tracking the port. Idempotent. */
+    /**
+     * Release this session's holds and detach it from the connection.
+     * Idempotent, and leaves the connection usable by its other sessions.
+     *
+     * The closes are fired without being awaited, because a `Disposable` cannot
+     * be: a host disposing a widget has nowhere to put the promise. A close
+     * that fails is no worse than the leak this exists to prevent, so the
+     * rejection is swallowed rather than surfaced from a teardown.
+     */
     dispose(): void;
-    /** The live generation, building one if there is none. */
-    protected currentGeneration(): Generation<TTransfer>;
-    /** Await the connection and the server's startup gate for one generation. */
-    protected awaitReady(generation: Generation<TTransfer>): Promise<void>;
     /**
-     * Discard the current generation, disposing its connection if it opened.
-     * The next {@link connected} builds a fresh one.
+     * Come off the connection because it is going away.
+     *
+     * Sends no close, unlike {@link dispose}: the server releases every hold on
+     * a connection it sees close, and the close would travel over the very
+     * connection being disposed.
      */
-    protected dropGeneration(): void;
+    detach(): void;
+    protected assertLive(): void;
 }
-export {};
 //# sourceMappingURL=data-session.d.ts.map

package/lib/client/data-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-session.d.ts","sourceRoot":"","sources":["../../src/client/data-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAyD,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElI,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,QAAQ,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,sGAGtC,CAAC;AAEF,eAAO,MAAM,qBAAqB,sGAGjC,CAAC;AAEF,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,+EAA+E;AAC/E,UAAU,UAAU,CAAC,SAAS,SAAS,eAAe;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IACzD,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,WAAW,CAAC,SAAS,SAAS,eAAe;IAQpD,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ;IACjC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC;IAR3D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAC3C,0FAA0F;IAC1F,SAAS,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC7C,SAAS,CAAC,QAAQ,UAAS;IAC3B,SAAS,CAAC,QAAQ,CAAC,mBAAmB,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;gBAGtC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC,EACxD,OAAO,GAAE,kBAAuB;IAMnC,+EAA+E;IAC/E,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;;;;;OAUG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IAYnE;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAOrE;;;OAGG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI1C,+EAA+E;IAC/E,OAAO,IAAI,IAAI;IASf,0DAA0D;IAC1D,SAAS,CAAC,iBAAiB,IAAI,UAAU,CAAC,SAAS,CAAC;IAoBpD,6EAA6E;cAC7D,UAAU,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5E;;;OAGG;IACH,SAAS,CAAC,cAAc,IAAI,IAAI;CAQlC"}
+{"version":3,"file":"data-session.d.ts","sourceRoot":"","sources":["../../src/client/data-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AACxG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,MAAM,qBAAqB,CAAC,SAAS,IAAI,IAAI,CAAC,0BAA0B,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC;AAEvG,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,CAAC,SAAS,IAAI,IAAI,CAAC,wBAAwB,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC;AAEnG;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,eAAe,EAAE,OAAO,SAAS,kBAAkB,CAAC,SAAS,CAAC;IAC9G,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,cAAc,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACjE;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAW,CAAC,SAAS,SAAS,eAAe,EAAE,OAAO,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC;IAMnI,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC;IAN/D,kFAAkF;IAClF,SAAS,CAAC,QAAQ,CAAC,QAAQ,cAAqB;IAChD,SAAS,CAAC,QAAQ,UAAS;gBAGf,QAAQ,EAAE,MAAM,EACN,IAAI,EAAE,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC;IAG/D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAQ7C;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAQrE;;;OAGG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C,+CAA+C;IACzC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAKlG,oDAAoD;IAC9C,YAAY,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAK9F;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAgBf;;;;;;OAMG;IACH,MAAM,IAAI,IAAI;IAKd,SAAS,CAAC,UAAU,IAAI,IAAI;CAK9B"}

package/lib/client/data-session.js

@@ -8,83 +8,43 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataSession = exports.DATA_SERVER_NOT_READY = exports.DATA_SERVER_CONNECT_FAILED = void 0;
-const data_1 = require("../data");
-const primitives_1 = require("../messages/primitives");
-const rpc_1 = require("../rpc");
+exports.DataSession = void 0;
 /**
- * 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.
- */
-exports.DATA_SERVER_CONNECT_FAILED = (0, primitives_1.defineMessage)('hydranium/protocol/data-server-connect-failed', 'Could not connect to the data server: {detail}');
-exports.DATA_SERVER_NOT_READY = (0, primitives_1.defineMessage)('hydranium/protocol/data-server-not-ready', 'The data server did not become ready: {detail}');
-/**
- * The host-invariant half of talking to the data head: everything above
- * {@link DataPort} that would otherwise be re-derived by every host
- * adapter.
+ * One participant on a data connection: a properties panel, a tree, a
+ * form editor.
  *
- * Three jobs, and deliberately no fourth:
+ * The server keys every hold and watch per `(uri, clientId)`, so the identity
+ * belongs to the participant rather than to the wire — several sessions share
+ * one connection, and two participants forced to share one identity cannot
+ * distinguish each other's writes from their own echoes.
  *
- * 1. **Build the typed proxy** over the port's connection, with the framework's
- *    wire prefix and its drift-proof client-method allowlist.
- * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
- *    across concurrent callers. A socket 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 connection generation when
- *    the port disposes and building a fresh one on the next request.
+ * Every document operation stamps {@link clientId} itself. A caller that
+ * passed its own could pass another participant's, and the server would
+ * attribute the write and release the hold accordingly.
  *
- * It does **not** wrap the protocol methods; callers reach them through
- * {@link connected}. The one exception is {@link openDocument}, which exists
- * because the open/watch *order* is silently wrong the other way round — see
- * its own doc.
- *
- * 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.
+ * Generic over the transfer root so this file names no grammar.
  */
 class DataSession {
-    port;
-    client;
-    methodNamespace;
-    /** The current generation, or `undefined` before the first request / after a teardown. */
-    generation;
+    clientId;
+    host;
+    /** URIs this session holds open, so {@link dispose} can release exactly those. */
+    openUris = new Set();
     disposed = false;
-    portDisposeListener;
-    constructor(port, client, options = {}) {
-        this.port = port;
-        this.client = client;
-        this.methodNamespace = options.methodNamespace ?? data_1.DATA_SERVER_WIRE_PREFIX;
-        this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
-    }
-    /** The identity every request is made under — the port's, not a second one. */
-    get clientId() {
-        return this.port.clientId;
+    constructor(clientId, host) {
+        this.clientId = clientId;
+        this.host = host;
     }
     /**
-     * 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.
+     * The connected, READY server proxy, for protocol methods this session does
+     * not wrap — the ones carrying no `clientId`, so no identity can be got
+     * wrong through them.
      */
     async connected() {
-        if (this.disposed) {
-            throw new Error('DataSession is disposed');
-        }
-        const generation = this.currentGeneration();
-        if (!generation.ready) {
-            generation.ready = this.awaitReady(generation);
-        }
-        await generation.ready;
-        return generation.server;
+        // `async` so a disposed session REJECTS rather than throwing
+        // synchronously: the connection's own `connected` rejects, and a caller
+        // reaching for `.catch` on one of them would not catch the other.
+        this.assertLive();
+        return this.host.connected();
     }
     /**
      * Open `uri` for editing and start watching it, in that order, returning
@@ -108,6 +68,7 @@ class DataSession {
         const server = await this.connected();
         const document = await server.openModelDocument({ uri, clientId: this.clientId });
         await server.watchModelDocument({ uri, clientId: this.clientId });
+        this.openUris.add(uri);
         return document;
     }
     /**
@@ -116,10 +77,21 @@ class DataSession {
      */
     async closeDocument(uri) {
         const server = await this.connected();
+        this.openUris.delete(uri);
         await server.closeModelDocument({ uri, clientId: this.clientId });
     }
+    /** Write `args.model` back as this session. */
+    async updateDocument(args) {
+        const server = await this.connected();
+        return server.updateModelDocument({ ...args, clientId: this.clientId });
+    }
+    /** Persist `args.model` to disk as this session. */
+    async saveDocument(args) {
+        const server = await this.connected();
+        return server.saveModelDocument({ ...args, clientId: this.clientId });
+    }
     /**
-     * Whether `event.sourceClientId` identifies this session's own write.
+     * Whether `sourceClientId` identifies this session's own write.
      *
      * Every watcher needs this and the check is one comparison, so getting it
      * wrong is cheap to do and expensive to find: an unfiltered echo looks
@@ -128,60 +100,45 @@ class DataSession {
     isOwnEcho(sourceClientId) {
         return sourceClientId === this.clientId;
     }
-    /** Tear down the current connection and stop tracking the port. Idempotent. */
+    /**
+     * Release this session's holds and detach it from the connection.
+     * Idempotent, and leaves the connection usable by its other sessions.
+     *
+     * The closes are fired without being awaited, because a `Disposable` cannot
+     * be: a host disposing a widget has nowhere to put the promise. A close
+     * that fails is no worse than the leak this exists to prevent, so the
+     * rejection is swallowed rather than surfaced from a teardown.
+     */
     dispose() {
         if (this.disposed) {
             return;
         }
         this.disposed = true;
-        this.portDisposeListener.dispose();
-        this.dropGeneration();
-    }
-    /** The live generation, building one if there is none. */
-    currentGeneration() {
-        if (this.generation) {
-            return this.generation;
-        }
-        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) => this.port.reportError(error, (0, primitives_1.resolve)(exports.DATA_SERVER_CONNECT_FAILED, { detail: (0, primitives_1.describeError)(error) })));
-        const server = (0, rpc_1.createRpcProxy)(connection, {
-            methodNamespace: this.methodNamespace,
-            localTarget: this.client,
-            localMethods: data_1.DATA_CLIENT_PROTOCOL_METHODS
-        });
-        this.generation = { connection, server };
-        return this.generation;
-    }
-    /** Await the connection and the server's startup gate for one generation. */
-    async awaitReady(generation) {
-        try {
-            await generation.connection;
-            await generation.server.waitForReady();
-        }
-        catch (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, (0, primitives_1.resolve)(exports.DATA_SERVER_NOT_READY, { detail: (0, primitives_1.describeError)(error) }));
-            throw error;
+        const uris = [...this.openUris];
+        this.openUris.clear();
+        this.host.releaseSession(this);
+        for (const uri of uris) {
+            void this.host
+                .connected()
+                .then(server => server.closeModelDocument({ uri, clientId: this.clientId }))
+                .catch(() => undefined);
         }
     }
     /**
-     * Discard the current generation, disposing its connection if it opened.
-     * The next {@link connected} builds a fresh one.
+     * Come off the connection because it is going away.
+     *
+     * Sends no close, unlike {@link dispose}: the server releases every hold on
+     * a connection it sees close, and the close would travel over the very
+     * connection being disposed.
      */
-    dropGeneration() {
-        const generation = this.generation;
-        this.generation = undefined;
-        if (!generation) {
-            return;
+    detach() {
+        this.disposed = true;
+        this.openUris.clear();
+    }
+    assertLive() {
+        if (this.disposed) {
+            throw new Error('DataSession is disposed');
         }
-        generation.connection.then(connection => connection.dispose()).catch(() => undefined);
     }
 }
 exports.DataSession = DataSession;