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

package/lib/testing/data-doubles.d.ts

@@ -32,7 +32,8 @@
 import { type MessageConnection } from 'vscode-jsonrpc';
 import type { DataPort } from '../client/data-port';
 import type { DataClientProtocol } from '../data/data-server-protocol';
-import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from '../data/events';
+import type { ProjectsChangedEvent, TransferDocumentDeletedEvent, TransferDocumentSavedEvent, TransferDocumentsBuiltEvent, TransferDocumentUpdatedEvent } from '../data/events';
+import type { ResolvedMessage } from '../messages/primitives';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -48,13 +49,6 @@ export interface FakeDataPortOptions {
      * which the consumer surfaces through {@link FakeDataPort.reported}.
      */
     connect(): MessageConnection | Promise<MessageConnection>;
-    /**
-     * Stable client identity. Defaults to `'fake-data-port'`, which avoids the
-     * three sentinels the framework reserves (`'language-client'`, `'unknown'`,
-     * `'revert-on-close'`); override it when a test needs two distinguishable
-     * clients on one server.
-     */
-    clientId?: string;
 }
 /** A {@link DataPort} that records what passed through it. */
 export interface FakeDataPort extends DataPort {
@@ -69,12 +63,13 @@ export interface FakeDataPort extends DataPort {
     /**
      * Every {@link DataPort.reportError} call, in order. Read from outside: this
      * is the only place a transport failure surfaces, so a test for the failure
-     * path asserts on the `context` string here rather than on a rejection that
-     * the consumer may legitimately swallow.
+     * path asserts here rather than on a rejection the consumer may legitimately
+     * swallow. Prefer asserting on `message.code`, which is stable, over
+     * `message.text`, which is the English default and may be reworded.
      */
     readonly reported: readonly {
         readonly error: unknown;
-        readonly context: string;
+        readonly message: ResolvedMessage;
     }[];
     /**
      * Fire {@link DataPort.onDispose} — the host tearing the transport down, a
@@ -101,13 +96,17 @@ export interface CapturingDataClient<TTransfer extends TransferElement, TDiagnos
     readonly updates: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>[];
     /** Every `onDocumentSaved` event, in arrival order. */
     readonly saves: TransferDocumentSavedEvent<TTransfer, TDiagnostic>[];
+    /** Every `onDocumentDeleted` event, in arrival order. */
+    readonly deletions: TransferDocumentDeletedEvent[];
+    /** Every `onDocumentsBuilt` event, in arrival order. */
+    readonly builds: TransferDocumentsBuiltEvent[];
     /** Every `onProjectsChanged` event, in arrival order. */
     readonly projectsChanges: ProjectsChangedEvent<TProject>[];
 }
 /**
  * A {@link DataClientProtocol} that records every notification it receives.
  *
- * Recording ALL THREE channels even when a suite reads one is deliberate: an
+ * Recording EVERY channel even when a suite reads one is deliberate: an
  * event delivered on the wrong channel is a real defect of the data head, and a
  * double that drops the other two turns it into silence on the one being
  * watched.

package/lib/testing/data-doubles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-doubles.d.ts","sourceRoot":"","sources":["../../src/testing/data-doubles.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAW,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AACrH,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,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IACjC;;;;;;;;OAQG;IACH,OAAO,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpF;;;;OAIG;IACH,WAAW,IAAI,IAAI,CAAC;IACpB,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAwB3E;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB,CACjC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO;IAElC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IACtE,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;IACzE,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;IACrE,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC;CAC7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACpC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,EACnC,SAAS,GAAE,OAAO,CAAC,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAM,GAAG,mBAAmB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAsBtI"}
+{"version":3,"file":"data-doubles.d.ts","sourceRoot":"","sources":["../../src/testing/data-doubles.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAW,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EACT,oBAAoB,EACpB,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,4BAA4B,EAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,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,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IACjC;;;;;;;;OAQG;IACH,OAAO,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC5D;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;KAAE,EAAE,CAAC;IAC7F;;;;OAIG;IACH,WAAW,IAAI,IAAI,CAAC;IACpB,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAuB3E;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB,CACjC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO;IAElC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IACtE,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;IACzE,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;IACrE,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,4BAA4B,EAAE,CAAC;IACnD,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,2BAA2B,EAAE,CAAC;IAC/C,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EAAE,CAAC;CAC7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACpC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,EACnC,SAAS,GAAE,OAAO,CAAC,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAM,GAAG,mBAAmB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAkCtI"}

package/lib/testing/data-doubles.js

@@ -46,7 +46,6 @@ function makeFakeDataPort(options) {
     const reported = [];
     const disposeEmitter = new vscode_jsonrpc_1.Emitter();
     return {
-        clientId: options.clientId ?? 'fake-data-port',
         connections,
         reported,
         onDispose: disposeEmitter.event,
@@ -55,8 +54,8 @@ function makeFakeDataPort(options) {
             connections.push(connection);
             return connection;
         },
-        reportError(error, context) {
-            reported.push({ error, context });
+        reportError(error, message) {
+            reported.push({ error, message });
         },
         fireDispose() {
             disposeEmitter.fire(undefined);
@@ -69,7 +68,7 @@ function makeFakeDataPort(options) {
 /**
  * A {@link DataClientProtocol} that records every notification it receives.
  *
- * Recording ALL THREE channels even when a suite reads one is deliberate: an
+ * Recording EVERY channel even when a suite reads one is deliberate: an
  * event delivered on the wrong channel is a real defect of the data head, and a
  * double that drops the other two turns it into silence on the one being
  * watched.
@@ -82,6 +81,8 @@ function makeFakeDataPort(options) {
 function makeCapturingDataClient(overrides = {}) {
     const updates = [];
     const saves = [];
+    const deletions = [];
+    const builds = [];
     const projectsChanges = [];
     const client = {
         onDocumentUpdated: overrides.onDocumentUpdated ??
@@ -92,11 +93,19 @@ function makeCapturingDataClient(overrides = {}) {
             (event => {
                 saves.push(event);
             }),
+        onDocumentDeleted: overrides.onDocumentDeleted ??
+            (event => {
+                deletions.push(event);
+            }),
+        onDocumentsBuilt: overrides.onDocumentsBuilt ??
+            (event => {
+                builds.push(event);
+            }),
         onProjectsChanged: overrides.onProjectsChanged ??
             (event => {
                 projectsChanges.push(event);
             })
     };
-    return { client, updates, saves, projectsChanges };
+    return { client, updates, saves, deletions, builds, projectsChanges };
 }
 //# sourceMappingURL=data-doubles.js.map

package/lib/testing/data-doubles.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-doubles.js","sourceRoot":"","sources":["../../src/testing/data-doubles.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AAyFlF,4CAwBC;AA+BD,0DA0BC;AAxKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,mDAAiE;AAwDjE;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,OAA4B;IAC1D,MAAM,WAAW,GAAwB,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAA0C,EAAE,CAAC;IAC3D,MAAM,cAAc,GAAG,IAAI,wBAAO,EAAQ,CAAC;IAC3C,OAAO;QACJ,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,gBAAgB;QAC9C,WAAW;QACX,QAAQ;QACR,SAAS,EAAE,cAAc,CAAC,KAAK;QAC/B,KAAK,CAAC,OAAO;YACV,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YAC3C,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC7B,OAAO,UAAU,CAAC;QACrB,CAAC;QACD,WAAW,CAAC,KAAc,EAAE,OAAe;YACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACrC,CAAC;QACD,WAAW;YACR,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;QACD,OAAO;YACJ,cAAc,CAAC,OAAO,EAAE,CAAC;QAC5B,CAAC;KACH,CAAC;AACL,CAAC;AAkBD;;;;;;;;;;;;GAYG;AACH,SAAgB,uBAAuB,CAIrC,YAA2E,EAAE;IAC5E,MAAM,OAAO,GAA2D,EAAE,CAAC;IAC3E,MAAM,KAAK,GAAyD,EAAE,CAAC;IACvE,MAAM,eAAe,GAAqC,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAyD;QAClE,iBAAiB,EACd,SAAS,CAAC,iBAAiB;YAC3B,CAAC,KAAK,CAAC,EAAE;gBACN,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC,CAAC;QACL,eAAe,EACZ,SAAS,CAAC,eAAe;YACzB,CAAC,KAAK,CAAC,EAAE;gBACN,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC,CAAC;QACL,iBAAiB,EACd,SAAS,CAAC,iBAAiB;YAC3B,CAAC,KAAK,CAAC,EAAE;gBACN,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC,CAAC;KACP,CAAC;IACF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;AACtD,CAAC"}
+{"version":3,"file":"data-doubles.js","sourceRoot":"","sources":["../../src/testing/data-doubles.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AA0FlF,4CAuBC;AAmCD,0DAsCC;AAxLD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,mDAAiE;AAyDjE;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,OAA4B;IAC1D,MAAM,WAAW,GAAwB,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAmD,EAAE,CAAC;IACpE,MAAM,cAAc,GAAG,IAAI,wBAAO,EAAQ,CAAC;IAC3C,OAAO;QACJ,WAAW;QACX,QAAQ;QACR,SAAS,EAAE,cAAc,CAAC,KAAK;QAC/B,KAAK,CAAC,OAAO;YACV,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;YAC3C,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC7B,OAAO,UAAU,CAAC;QACrB,CAAC;QACD,WAAW,CAAC,KAAc,EAAE,OAAwB;YACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACrC,CAAC;QACD,WAAW;YACR,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;QACD,OAAO;YACJ,cAAc,CAAC,OAAO,EAAE,CAAC;QAC5B,CAAC;KACH,CAAC;AACL,CAAC;AAsBD;;;;;;;;;;;;GAYG;AACH,SAAgB,uBAAuB,CAIrC,YAA2E,EAAE;IAC5E,MAAM,OAAO,GAA2D,EAAE,CAAC;IAC3E,MAAM,KAAK,GAAyD,EAAE,CAAC;IACvE,MAAM,SAAS,GAAmC,EAAE,CAAC;IACrD,MAAM,MAAM,GAAkC,EAAE,CAAC;IACjD,MAAM,eAAe,GAAqC,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAyD;QAClE,iBAAiB,EACd,SAAS,CAAC,iBAAiB;YAC3B,CAAC,KAAK,CAAC,EAAE;gBACN,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC,CAAC;QACL,eAAe,EACZ,SAAS,CAAC,eAAe;YACzB,CAAC,KAAK,CAAC,EAAE;gBACN,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC,CAAC;QACL,iBAAiB,EACd,SAAS,CAAC,iBAAiB;YAC3B,CAAC,KAAK,CAAC,EAAE;gBACN,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC,CAAC;QACL,gBAAgB,EACb,SAAS,CAAC,gBAAgB;YAC1B,CAAC,KAAK,CAAC,EAAE;gBACN,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC,CAAC;QACL,iBAAiB,EACd,SAAS,CAAC,iBAAiB;YAC3B,CAAC,KAAK,CAAC,EAAE;gBACN,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC,CAAC;KACP,CAAC;IACF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;AACzE,CAAC"}

package/lib/testing/index.d.ts

@@ -6,6 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
+export * from './catalogue-audit';
 export * from './data-doubles';
 export * from './fake-clock';
 export * from './harness';

package/lib/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAelF,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAiBlF,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/lib/testing/index.js

@@ -25,7 +25,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // Subpath barrel for `@hydranium/protocol/testing` — the BROWSER-NEUTRAL shared
 // primitives: `makeFakeClock` (deterministic `Clock` double on one virtual time
 // axis), `waitFor` / `tick`, the client-side data-head doubles
-// (`makeFakeDataPort` / `makeCapturingDataClient`), and the `Harness` marker
+// (`makeFakeDataPort` / `makeCapturingDataClient`), the translation-catalogue
+// audit (`flattenCatalogue` / `findUndeclaredCodes` / `findSharedCodes`), and
+// the `Harness` marker
 // interface every framework harness extends. Kept out of the main barrel so production bundles don't pull
 // the test scaffolding in by default; adopters opt in by importing from
 // `@hydranium/protocol/testing`.
@@ -34,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // duplex transports are NOT here: a `PassThrough` pair is in their exported
 // type, so they cannot be made portable and live at `./testing/node` instead.
 // The same rule the package surface uses — the portable name is the short one.
+__exportStar(require("./catalogue-audit"), exports);
 __exportStar(require("./data-doubles"), exports);
 __exportStar(require("./fake-clock"), exports);
 __exportStar(require("./harness"), exports);

package/lib/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,6EAA6E;AAC7E,0GAA0G;AAC1G,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAE/E,iDAA+B;AAC/B,+CAA6B;AAC7B,4CAA0B;AAC1B,6CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,gFAAgF;AAChF,gFAAgF;AAChF,+DAA+D;AAC/D,8EAA8E;AAC9E,8EAA8E;AAC9E,uBAAuB;AACvB,0GAA0G;AAC1G,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAE/E,oDAAkC;AAClC,iDAA+B;AAC/B,+CAA6B;AAC7B,4CAA0B;AAC1B,6CAA2B"}

package/lib/transfer-diagnostic.d.ts

@@ -6,6 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
+import { type MessageParams, type ResolvedMessage } from './messages/primitives';
 /**
  * Generic, transport-friendly diagnostic shape used by the model-server protocol.
  *
@@ -55,6 +56,21 @@ export interface TransferDiagnostic {
      * is not usable as a rule identity on its own.
      */
     code?: number | string;
+    /**
+     * Substitutions for the placeholders in the message this {@link code} names,
+     * present only for a diagnostic raised from a framework message declaration.
+     *
+     * Without them a translated template renders with its `{name}` tokens left
+     * standing, because substitution leaves an unmatched token in place rather
+     * than raising — so a surface that translates from {@link code} alone is
+     * correct for a parameterless sentence and visibly wrong for a parameterised
+     * one. This is the field that makes the second case work; the LSP carrier has
+     * always moved the params, and no carrier below it did.
+     *
+     * Prefer {@link TransferDiagnostic.resolved} over reading this: it decides
+     * whether an identity is present at all, which a lone `params` cannot.
+     */
+    params?: MessageParams;
 }
 export declare namespace TransferDiagnostic {
     /** Path separator between AST nodes within an element location. */
@@ -65,6 +81,23 @@ export declare namespace TransferDiagnostic {
     const ELEMENT_PROPERTY_SEPARATOR = "^";
     function isError(diagnostic: TransferDiagnostic): boolean;
     function isParseError(diagnostic: TransferDiagnostic): boolean;
+    /**
+     * The diagnostic as a renderable message, for a surface that translates.
+     * `undefined` when it carries no framework identity — a syntactic error, an
+     * adopter's own check, a linker failure — which is the case a caller must
+     * distinguish rather than render.
+     *
+     * Hand the result to `renderFrameworkMessage` with whatever catalogue the
+     * host has loaded. The `text` is the server's English, so a code the
+     * catalogue does not carry still yields a complete sentence.
+     *
+     * `code` alone does not establish an identity: it also holds Langium's
+     * internal code and an adopter's own, and either would be looked up against a
+     * catalogue that cannot have it. Requiring `params` is what discriminates,
+     * and it is why a parameterless framework message still populates the field
+     * with an empty object rather than omitting it.
+     */
+    function resolved(diagnostic: TransferDiagnostic): ResolvedMessage | undefined;
     function getPath(diagnostic: TransferDiagnostic): string;
     function errors(diagnostics: TransferDiagnostic[]): TransferDiagnostic[];
     function hasErrors(diagnostics: TransferDiagnostic[]): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"transfer-diagnostic.d.ts","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,kBAAkB,CAAC;IAC5D;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,yBAAiB,kBAAkB,CAAC;IACjC,mEAAmE;IAC5D,MAAM,yBAAyB,MAAM,CAAC;IAC7C,wDAAwD;IACjD,MAAM,uBAAuB,MAAM,CAAC;IAC3C,sFAAsF;IAC/E,MAAM,0BAA0B,MAAM,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAE/D;IAED,SAAgB,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAEpE;IAED,SAAgB,OAAO,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAE9D;IAED,SAAgB,MAAM,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAE9E;IAED,SAAgB,SAAS,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAEpE;IAED,SAAgB,cAAc,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAEzE;CACH"}
+{"version":3,"file":"transfer-diagnostic.d.ts","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,kBAAkB,CAAC;IAC5D;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,yBAAiB,kBAAkB,CAAC;IACjC,mEAAmE;IAC5D,MAAM,yBAAyB,MAAM,CAAC;IAC7C,wDAAwD;IACjD,MAAM,uBAAuB,MAAM,CAAC;IAC3C,sFAAsF;IAC/E,MAAM,0BAA0B,MAAM,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAE/D;IAED,SAAgB,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAEpE;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,eAAe,GAAG,SAAS,CAKpF;IAED,SAAgB,OAAO,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAE9D;IAED,SAAgB,MAAM,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAE9E;IAED,SAAgB,SAAS,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAEpE;IAED,SAAgB,cAAc,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAEzE;CACH"}

package/lib/transfer-diagnostic.js

@@ -25,6 +25,29 @@ var TransferDiagnostic;
         return diagnostic.type === 'parsing-error';
     }
     TransferDiagnostic.isParseError = isParseError;
+    /**
+     * The diagnostic as a renderable message, for a surface that translates.
+     * `undefined` when it carries no framework identity — a syntactic error, an
+     * adopter's own check, a linker failure — which is the case a caller must
+     * distinguish rather than render.
+     *
+     * Hand the result to `renderFrameworkMessage` with whatever catalogue the
+     * host has loaded. The `text` is the server's English, so a code the
+     * catalogue does not carry still yields a complete sentence.
+     *
+     * `code` alone does not establish an identity: it also holds Langium's
+     * internal code and an adopter's own, and either would be looked up against a
+     * catalogue that cannot have it. Requiring `params` is what discriminates,
+     * and it is why a parameterless framework message still populates the field
+     * with an empty object rather than omitting it.
+     */
+    function resolved(diagnostic) {
+        if (typeof diagnostic.code !== 'string' || diagnostic.params === undefined) {
+            return undefined;
+        }
+        return { code: diagnostic.code, params: diagnostic.params, text: diagnostic.message };
+    }
+    TransferDiagnostic.resolved = resolved;
     function getPath(diagnostic) {
         return diagnostic.property ? `${diagnostic.element}${TransferDiagnostic.ELEMENT_PROPERTY_SEPARATOR}${diagnostic.property}` : diagnostic.element;
     }

package/lib/transfer-diagnostic.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-diagnostic.js","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAqDlF,IAAiB,kBAAkB,CA+BlC;AA/BD,WAAiB,kBAAkB;IAChC,mEAAmE;IACtD,4CAAyB,GAAG,GAAG,CAAC;IAC7C,wDAAwD;IAC3C,0CAAuB,GAAG,GAAG,CAAC;IAC3C,sFAAsF;IACzE,6CAA0B,GAAG,GAAG,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC1C,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,YAAY,CAAC,UAA8B;QACxD,OAAO,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC;IAC9C,CAAC;IAFe,+BAAY,eAE3B,CAAA;IAED,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,mBAAA,0BAA0B,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;IAChI,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,MAAM,CAAC,WAAiC;QACrD,OAAO,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAFe,yBAAM,SAErB,CAAA;IAED,SAAgB,SAAS,CAAC,WAAiC;QACxD,OAAO,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAFe,4BAAS,YAExB,CAAA;IAED,SAAgB,cAAc,CAAC,WAAiC;QAC7D,OAAO,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAFe,iCAAc,iBAE7B,CAAA;AACJ,CAAC,EA/BgB,kBAAkB,kCAAlB,kBAAkB,QA+BlC"}
+{"version":3,"file":"transfer-diagnostic.js","sourceRoot":"","sources":["../src/transfer-diagnostic.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAsElF,IAAiB,kBAAkB,CAsDlC;AAtDD,WAAiB,kBAAkB;IAChC,mEAAmE;IACtD,4CAAyB,GAAG,GAAG,CAAC;IAC7C,wDAAwD;IAC3C,0CAAuB,GAAG,GAAG,CAAC;IAC3C,sFAAsF;IACzE,6CAA0B,GAAG,GAAG,CAAC;IAE9C,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC1C,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,YAAY,CAAC,UAA8B;QACxD,OAAO,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC;IAC9C,CAAC;IAFe,+BAAY,eAE3B,CAAA;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAgB,QAAQ,CAAC,UAA8B;QACpD,IAAI,OAAO,UAAU,CAAC,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1E,OAAO,SAAS,CAAC;QACpB,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC;IACzF,CAAC;IALe,2BAAQ,WAKvB,CAAA;IAED,SAAgB,OAAO,CAAC,UAA8B;QACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,mBAAA,0BAA0B,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC;IAChI,CAAC;IAFe,0BAAO,UAEtB,CAAA;IAED,SAAgB,MAAM,CAAC,WAAiC;QACrD,OAAO,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAFe,yBAAM,SAErB,CAAA;IAED,SAAgB,SAAS,CAAC,WAAiC;QACxD,OAAO,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAFe,4BAAS,YAExB,CAAA;IAED,SAAgB,cAAc,CAAC,WAAiC;QAC7D,OAAO,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAFe,iCAAc,iBAE7B,CAAA;AACJ,CAAC,EAtDgB,kBAAkB,kCAAlB,kBAAkB,QAsDlC"}

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,13 @@ 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 `TransferUpdateDocumentArgs.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 +62,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;;;;;;;OAOG;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;AA+CnF,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.12",
+  "version": "1.0.0-next.123",
   "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,216 @@
+/********************************************************************************
+ * 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, type DataSessionFactory } from './data-session';
+import { RpcConnection, type RpcConnectionLifecycle } from './rpc-connection';
+
+/** Options for {@link DataConnection}. */
+export interface DataConnectionOptions<
+   TTransfer extends TransferElement = TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> 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;
+   /** Builds the sessions `createSession` hands out. Defaults to a plain {@link DataSession}. */
+   readonly sessionFactory?: DataSessionFactory<TTransfer, TServer>;
+}
+
+/** {@link DataConnectionOptions} for a client that does not speak {@link DataClientProtocol}. */
+export interface DataConnectionOptionsWithMethods<
+   TClient extends object,
+   TTransfer extends TransferElement = TransferElement,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> extends DataConnectionOptions<TTransfer, TServer> {
+   /**
+    * 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,
+   TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>
+> =
+   TClient extends DataClientProtocol<TTransfer>
+      ? [options?: DataConnectionOptions<TTransfer, TServer> & Partial<DataConnectionOptionsWithMethods<TClient, TTransfer, TServer>>]
+      : [options: DataConnectionOptionsWithMethods<TClient, TTransfer, TServer>];
+
+/**
+ * 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 opens 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>>();
+   protected readonly sessionFactory: DataSessionFactory<TTransfer, TServer>;
+
+   constructor(port: DataPort, client: TClient, ...rest: DataConnectionArgs<TTransfer, TClient, TServer>) {
+      const [options = {}] = rest as [
+         (DataConnectionOptions<TTransfer, TServer> & Partial<DataConnectionOptionsWithMethods<TClient, TTransfer, TServer>>)?
+      ];
+      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
+      });
+      this.sessionFactory =
+         options.sessionFactory ?? ((clientId, host, label) => new DataSession<TTransfer, TServer>(clientId, host, label));
+   }
+
+   /**
+    * Start a participant on this connection, registered with the server under a
+    * fresh id, `label` plus `#` plus a random UUID, or under `clientId` when
+    * given. Synchronous: the registration is sent at once, and the session's
+    * calls wait for it. The server refuses an id live anywhere in its process,
+    * and every call of that session then rejects with a
+    * `DuplicateClientIdError` code.
+    *
+    * 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 — and for
+    * an id a live session on this connection already holds.
+    */
+   createSession(label = 'session', clientId?: string): DataSession<TTransfer, TServer> {
+      this.assertLive();
+      const id = clientId ?? `${label}#${globalThis.crypto.randomUUID()}`;
+      if (FRAMEWORK_CLIENT_IDS.includes(id)) {
+         throw new Error(`clientId '${id}' is reserved by the framework and cannot identify a participant`);
+      }
+      if ([...this.sessions].some(session => session.clientId === id)) {
+         throw new Error(`clientId '${id}' already identifies a live participant on this connection`);
+      }
+      const session = this.sessionFactory(
+         id,
+         {
+            connected: () => this.connected(),
+            releaseSession: released => this.sessions.delete(released),
+            reportError: (error, reported) => this.reportError(error, reported)
+         },
+         label
+      );
+      this.sessions.add(session);
+      // A failure reaches the session's own calls, which wait for the same
+      // registration; caught here only so it is not also reported unhandled.
+      session.connected().catch(() => undefined);
+      return session;
+   }
+
+   /**
+    * After the transport dropped, reconnect on the next macrotask for the
+    * sessions with documents open, so they re-watch and follow their documents
+    * again without waiting for a call of their own; a session with nothing
+    * open restores on its next call. Nothing is scheduled once this connection
+    * is disposed, which drops its generation too.
+    */
+   protected override dropGeneration(): void {
+      const dropped = this.generation !== undefined;
+      super.dropGeneration();
+      if (dropped && !this.disposed) {
+         setTimeout(() => {
+            if (!this.disposed) {
+               this.sessions.forEach(session => session.reconnect());
+            }
+         }, 0);
+      }
+   }
+
+   /**
+    * Sessions are detached rather than disposed: the server ends every session
+    * on a connection it sees close, so ending each one 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();
+      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<TTransfer, TServer>) {
+      // 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();
+   }
+}