@hydranium/protocol 1.0.0-next.8 → 1.0.0-next.85

package/README.md

@@ -60,7 +60,7 @@ names, a worked example — is in
 @hydranium/protocol               # transfer documents, references, RPC machinery
 @hydranium/protocol/data          # DataServerProtocol / DataClientProtocol
 @hydranium/protocol/client        # the host-neutral client tier
-@hydranium/protocol/testing       # test doubles and waiters
+@hydranium/protocol/testing       # test doubles, waiters, catalogue audit
 @hydranium/protocol/testing/node  # the Node-only doubles
 ```
 
@@ -69,6 +69,40 @@ narrower surface rather than reach; `testing` is only reachable by its own
 specifier, which is what keeps the doubles out of a production bundle. The RPC
 machinery documents itself in [`src/rpc/README.md`](./src/rpc/README.md).
 
+### Auditing a translation catalogue
+
+An adopter with i18n has one failure mode nothing else catches: a catalogue key
+naming no declared code falls back to the English, which is byte-identical to
+the deliberately-partial behaviour every adopter relies on. So a typo is
+invisible at runtime, and `theia nls-extract` reports what the source declares
+rather than whether a catalogue matches it.
+
+`@hydranium/protocol/testing` ships the audit for it — call it from your own
+test, over your own barrels:
+
+<!-- snippet-preamble
+import { flattenCatalogue, findUndeclaredCodes, findSharedCodes } from '@hydranium/protocol/testing';
+import * as protocolMessages from '@hydranium/protocol';
+declare const readFileSync: (path: string, encoding: string) => string;
+declare const expect: (actual: unknown) => { toEqual(expected: unknown): void };
+-->
+
+```ts
+const keys = Object.keys(flattenCatalogue(JSON.parse(readFileSync('nls/de.json', 'utf-8'))));
+
+// Every key names a code some barrel declares. `exemptPrefixes` is for keys no
+// barrel CAN declare — a host mechanism taking its key as an inline literal.
+expect(findUndeclaredCodes(keys, [protocolMessages])).toEqual([]);
+```
+
+`flattenCatalogue` joins nested keys with `/` (the separator a code already
+uses, and what Theia does to a nested catalogue) and drops `_`-prefixed note
+keys, so a flat server-side catalogue and a nested host-side one both go through
+it. `findSharedCodes` covers the other half: exactly one side renders a given
+message, so two catalogues holding one code are two authorities over one
+sentence — assert both key sets non-empty first, since an empty one satisfies
+disjointness while proving nothing.
+
 ## Status
 
 Alpha — pre-v0. The package is being populated incrementally, and its API is

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

@@ -0,0 +1,114 @@
+/********************************************************************************
+ * 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, 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 declare 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: 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.
+     *
+     * 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.
+     *
+     * The check spans this connection only, so a head several connections reach
+     * can still be addressed twice under one id.
+     */
+    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;
+}
+/**
+ * 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 declare 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);
+    /** Disposes the fan-out it created, which no caller else holds. */
+    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;AAGlF,OAAO,EAGJ,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,SAAS,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,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,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,EACpG,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;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC;IAgBhE;;;;OAIG;IACM,OAAO,IAAI,IAAI;CAO1B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,wBAAwB,CAClC,SAAS,SAAS,eAAe,EACjC,OAAO,SAAS,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,kBAAkB,CAAC,SAAS,CAAC,CACrG,SAAQ,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3G,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;gBAEtE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,qBAAqB;IAQ3D,mEAAmE;IAC1D,OAAO,IAAI,IAAI;CAI1B"}

package/lib/client/data-connection.js

@@ -0,0 +1,128 @@
+"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.DataConnectionWithEvents = exports.DataConnection = void 0;
+const client_ids_1 = require("../client-ids");
+const data_1 = require("../data");
+const data_events_1 = require("./data-events");
+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.
+     *
+     * 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.
+     *
+     * The check spans this connection only, so a head several connections reach
+     * can still be addressed twice under one id.
+     */
+    createSession(clientId) {
+        this.assertLive();
+        if (client_ids_1.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`);
+        }
+        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;
+/**
+ * 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.
+ */
+class DataConnectionWithEvents extends DataConnection {
+    /** Server pushes, fanned out to as many local listeners as the host has. */
+    events;
+    constructor(port, options) {
+        // Built as a local because `this` is unavailable before `super`, then
+        // read back onto the field.
+        const events = new data_events_1.DataEvents();
+        super(port, events, options);
+        this.events = events;
+    }
+    /** Disposes the fan-out it created, which no caller else holds. */
+    dispose() {
+        super.dispose();
+        this.events.dispose();
+    }
+}
+exports.DataConnectionWithEvents = DataConnectionWithEvents;
+//# 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,8CAAqD;AACrD,kCAOiB;AAEjB,+CAA2C;AAE3C,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;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAAa,CAAC,QAAgB;QAC3B,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,iCAAoB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,aAAa,QAAQ,kEAAkE,CAAC,CAAC;QAC5G,CAAC;QACD,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,EAAE,CAAC;YACrE,MAAM,IAAI,KAAK,CAAC,aAAa,QAAQ,4DAA4D,CAAC,CAAC;QACtG,CAAC;QACD,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;AAvED,wCAuEC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAa,wBAGX,SAAQ,cAAoG;IAC3G,4EAA4E;IACnE,MAAM,CAAmE;IAElF,YAAY,IAAc,EAAE,OAA+B;QACxD,sEAAsE;QACtE,4BAA4B;QAC5B,MAAM,MAAM,GAAG,IAAI,wBAAU,EAAwD,CAAC;QACtF,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,mEAAmE;IAC1D,OAAO;QACb,KAAK,CAAC,OAAO,EAAE,CAAC;QAChB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;CACH;AApBD,4DAoBC"}

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

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 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';
@@ -34,15 +34,23 @@ import type { TransferElement } from '../transfer-element';
 export declare class DataEvents<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> implements DataClientProtocol<TTransfer, TDiagnostic, TProject> {
     protected readonly documentUpdatedEmitter: Emitter<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
     protected readonly documentSavedEmitter: Emitter<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>;
+    protected readonly documentDeletedEmitter: Emitter<TransferDocumentDeletedEvent>;
+    protected readonly documentsBuiltEmitter: Emitter<TransferDocumentsBuiltEvent>;
     protected readonly projectsChangedEmitter: Emitter<ProjectsChangedEvent<TProject>>;
     /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
     readonly onDidUpdateDocument: Event<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
     /** A watched document was persisted to disk. */
     readonly onDidSaveDocument: Event<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>;
+    /** A document's backing file was removed, watched or not. Any watch survives. */
+    readonly onDidDeleteDocument: Event<TransferDocumentDeletedEvent>;
+    /** Documents built that nobody watches — re-read anything derived from them. */
+    readonly onDidBuildDocuments: Event<TransferDocumentsBuiltEvent>;
     /** The project set changed. */
     readonly onDidChangeProjects: Event<ProjectsChangedEvent<TProject>>;
     onDocumentUpdated(event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>): void;
     onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+    onDocumentDeleted(event: TransferDocumentDeletedEvent): void;
+    onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void;
     onProjectsChanged(event: ProjectsChangedEvent<TProject>): void;
     dispose(): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"data-events.d.ts","sourceRoot":"","sources":["../../src/client/data-events.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAClI,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,UAAU,CACpB,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,CACnC,YAAW,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC;IAC9D,SAAS,CAAC,QAAQ,CAAC,sBAAsB,gEAAuE;IAChH,SAAS,CAAC,QAAQ,CAAC,oBAAoB,8DAAqE;IAC5G,SAAS,CAAC,QAAQ,CAAC,sBAAsB,0CAAiD;IAE1F,4FAA4F;IAC5F,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAqC;IAC9H,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,EAAE,KAAK,CAAC,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAmC;IACxH,+BAA+B;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAqC;IAIxG,iBAAiB,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI;IAIpF,eAAe,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI;IAIhF,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG,IAAI;IAI9D,OAAO,IAAI,IAAI;CAKjB"}
+{"version":3,"file":"data-events.d.ts","sourceRoot":"","sources":["../../src/client/data-events.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EACT,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,4BAA4B,EAC9B,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,UAAU,CACpB,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,CACnC,YAAW,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC;IAC9D,SAAS,CAAC,QAAQ,CAAC,sBAAsB,gEAAuE;IAChH,SAAS,CAAC,QAAQ,CAAC,oBAAoB,8DAAqE;IAC5G,SAAS,CAAC,QAAQ,CAAC,sBAAsB,wCAA+C;IACxF,SAAS,CAAC,QAAQ,CAAC,qBAAqB,uCAA8C;IACtF,SAAS,CAAC,QAAQ,CAAC,sBAAsB,0CAAiD;IAE1F,4FAA4F;IAC5F,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAqC;IAC9H,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,EAAE,KAAK,CAAC,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAmC;IACxH,iFAAiF;IACjF,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,CAAC,CAAqC;IACtG,gFAAgF;IAChF,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,2BAA2B,CAAC,CAAoC;IACpG,+BAA+B;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,KAAK,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAqC;IAIxG,iBAAiB,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI;IAIpF,eAAe,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,IAAI;IAIhF,iBAAiB,CAAC,KAAK,EAAE,4BAA4B,GAAG,IAAI;IAI5D,gBAAgB,CAAC,KAAK,EAAE,2BAA2B,GAAG,IAAI;IAI1D,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG,IAAI;IAI9D,OAAO,IAAI,IAAI;CAOjB"}

package/lib/client/data-events.js

@@ -33,11 +33,17 @@ const vscode_jsonrpc_1 = require("vscode-jsonrpc");
 class DataEvents {
     documentUpdatedEmitter = new vscode_jsonrpc_1.Emitter();
     documentSavedEmitter = new vscode_jsonrpc_1.Emitter();
+    documentDeletedEmitter = new vscode_jsonrpc_1.Emitter();
+    documentsBuiltEmitter = new vscode_jsonrpc_1.Emitter();
     projectsChangedEmitter = new vscode_jsonrpc_1.Emitter();
     /** A build-phase event for a watched document. Carries the originating `sourceClientId`. */
     onDidUpdateDocument = this.documentUpdatedEmitter.event;
     /** A watched document was persisted to disk. */
     onDidSaveDocument = this.documentSavedEmitter.event;
+    /** A document's backing file was removed, watched or not. Any watch survives. */
+    onDidDeleteDocument = this.documentDeletedEmitter.event;
+    /** Documents built that nobody watches — re-read anything derived from them. */
+    onDidBuildDocuments = this.documentsBuiltEmitter.event;
     /** The project set changed. */
     onDidChangeProjects = this.projectsChangedEmitter.event;
     // --- DataClientProtocol (wire names) ---
@@ -47,12 +53,20 @@ class DataEvents {
     onDocumentSaved(event) {
         this.documentSavedEmitter.fire(event);
     }
+    onDocumentDeleted(event) {
+        this.documentDeletedEmitter.fire(event);
+    }
+    onDocumentsBuilt(event) {
+        this.documentsBuiltEmitter.fire(event);
+    }
     onProjectsChanged(event) {
         this.projectsChangedEmitter.fire(event);
     }
     dispose() {
         this.documentUpdatedEmitter.dispose();
         this.documentSavedEmitter.dispose();
+        this.documentDeletedEmitter.dispose();
+        this.documentsBuiltEmitter.dispose();
         this.projectsChangedEmitter.dispose();
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"data-events.js","sourceRoot":"","sources":["../../src/client/data-events.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,mDAAqD;AAMrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,UAAU;IAKD,sBAAsB,GAAG,IAAI,wBAAO,EAAwD,CAAC;IAC7F,oBAAoB,GAAG,IAAI,wBAAO,EAAsD,CAAC;IACzF,sBAAsB,GAAG,IAAI,wBAAO,EAAkC,CAAC;IAE1F,4FAA4F;IACnF,mBAAmB,GAAgE,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;IAC9H,gDAAgD;IACvC,iBAAiB,GAA8D,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;IACxH,+BAA+B;IACtB,mBAAmB,GAA0C,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;IAExG,0CAA0C;IAE1C,iBAAiB,CAAC,KAA2D;QAC1E,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,eAAe,CAAC,KAAyD;QACtE,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,iBAAiB,CAAC,KAAqC;QACpD,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO;QACJ,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC;IACzC,CAAC;CACH;AAnCD,gCAmCC"}
+{"version":3,"file":"data-events.js","sourceRoot":"","sources":["../../src/client/data-events.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,mDAAqD;AAarD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,UAAU;IAKD,sBAAsB,GAAG,IAAI,wBAAO,EAAwD,CAAC;IAC7F,oBAAoB,GAAG,IAAI,wBAAO,EAAsD,CAAC;IACzF,sBAAsB,GAAG,IAAI,wBAAO,EAAgC,CAAC;IACrE,qBAAqB,GAAG,IAAI,wBAAO,EAA+B,CAAC;IACnE,sBAAsB,GAAG,IAAI,wBAAO,EAAkC,CAAC;IAE1F,4FAA4F;IACnF,mBAAmB,GAAgE,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;IAC9H,gDAAgD;IACvC,iBAAiB,GAA8D,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;IACxH,iFAAiF;IACxE,mBAAmB,GAAwC,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;IACtG,gFAAgF;IACvE,mBAAmB,GAAuC,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC;IACpG,+BAA+B;IACtB,mBAAmB,GAA0C,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;IAExG,0CAA0C;IAE1C,iBAAiB,CAAC,KAA2D;QAC1E,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,eAAe,CAAC,KAAyD;QACtE,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,iBAAiB,CAAC,KAAmC;QAClD,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,gBAAgB,CAAC,KAAkC;QAChD,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,iBAAiB,CAAC,KAAqC;QACpD,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO;QACJ,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,CAAC;QACrC,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC;IACzC,CAAC;CACH;AAnDD,gCAmDC"}

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

@@ -7,20 +7,24 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 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.
@@ -43,21 +47,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`.
      *
@@ -73,10 +62,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
      * is no longer usable — a language-server restart being the case that

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;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnD;;;;;;;;;;;;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"}