@hydranium/protocol 1.0.0-next.24 → 1.0.0-next.27

package/lib/messages/primitives.js

@@ -0,0 +1,138 @@
+"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.defineMessage = defineMessage;
+exports.interpolate = interpolate;
+exports.messageData = messageData;
+exports.resolve = resolve;
+exports.hasMessageIdentity = hasMessageIdentity;
+exports.messageError = messageError;
+exports.renderFrameworkMessage = renderFrameworkMessage;
+exports.resolvedFromResponseError = resolvedFromResponseError;
+exports.describeError = describeError;
+exports.isMessageDeclaration = isMessageDeclaration;
+exports.collectMessages = collectMessages;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+/**
+ * Declare a message. Placeholder names are inferred from `text` rather than
+ * declared again in a type argument: a second spelling of every name is the
+ * repetition that drifts, since adding a placeholder to the sentence and not to
+ * the type compiles.
+ */
+function defineMessage(code, text) {
+    const literal = text;
+    return { code, text: literal, format: (...args) => interpolate(literal, args[0] ?? {}) };
+}
+const PLACEHOLDER = /\{([^}]+)\}/g;
+/**
+ * Substitute `{name}` tokens, leaving an unfilled token in place.
+ *
+ * It must not throw. This runs over an adopter's translation as well as our own
+ * text, so a typo in a foreign catalogue has to degrade to a slightly wrong
+ * sentence rather than raise inside a toast render. Re-scanning the result to
+ * detect an unfilled token is what an earlier form did, and it cannot work:
+ * `String.replace` does not rescan replacement text, so the check could not tell
+ * an unfilled placeholder from user data shaped like one — an element literally
+ * named `{separator}` crashed at the authoring site.
+ */
+function interpolate(template, params) {
+    // Indexed rather than `key in params`: a hand-built or version-skewed
+    // identity can arrive with no params at all, and `in` throws on a non-object
+    // where a lookup degrades.
+    const lookup = params;
+    return template.replace(PLACEHOLDER, (match, key) => {
+        const value = lookup?.[key];
+        return value === undefined ? match : String(value);
+    });
+}
+function messageData(message, ...args) {
+    return { hydranium: { code: message.code, params: args[0] ?? {} } };
+}
+/**
+ * Identity plus resolved English, for a hand-off carrying a value rather than a
+ * protocol field. The result is structured-clone safe, so it survives a process
+ * hop where one intervenes and costs nothing where none does.
+ */
+function resolve(message, ...args) {
+    return { code: message.code, text: message.format(...args), params: args[0] ?? {} };
+}
+/**
+ * Validates every field {@link MessageIdentity} declares, `params` included.
+ * A guard over foreign input that checks only `code` while declaring `params`
+ * non-optional hands `undefined` to the renderer, which fails with the worst
+ * polarity available: invisible in English, crashing only once a translation is
+ * loaded.
+ */
+function hasMessageIdentity(data) {
+    if (typeof data !== 'object' || data === null || Array.isArray(data) || !('hydranium' in data)) {
+        return false;
+    }
+    const identity = data.hydranium;
+    if (typeof identity !== 'object' || identity === null || Array.isArray(identity)) {
+        return false;
+    }
+    const candidate = identity;
+    return typeof candidate.code === 'string' && typeof candidate.params === 'object' && candidate.params !== null;
+}
+/**
+ * The numeric `code` and the message's catalogue code are unrelated and both are
+ * needed: `ResponseError.code` is an `integer`, so it cannot hold a
+ * `hydranium/…` key, and it is what a caller switches on after reconstruction.
+ */
+function messageError(code, message, ...params) {
+    return new vscode_jsonrpc_1.ResponseError(code, message.format(...params), messageData(message, ...params));
+}
+/**
+ * Render on the side that knows the reading user's locale. `translations` is
+ * whatever flat `code → template` map the host exposes; omitting it is how an
+ * adopter without i18n opts out, and yields the English.
+ */
+function renderFrameworkMessage(message, translations) {
+    const template = translations?.[message.code];
+    return template ? interpolate(template, message.params) : message.text;
+}
+function resolvedFromResponseError(error) {
+    return hasMessageIdentity(error.data) ? { ...error.data.hydranium, text: error.message } : undefined;
+}
+/**
+ * The detail half of a `{detail}` placeholder. A technical error string is safe
+ * to pass as a parameter for the same reason a number is: it is not itself
+ * translatable text, so it needs no code of its own. A PROSE fragment is not,
+ * and must become one code per value instead.
+ */
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Recognises a declaration among a barrel's exports. The `format` check is what
+ * discriminates: a `code` + `text` pair alone admits any object that happens to
+ * carry both.
+ */
+function isMessageDeclaration(value) {
+    const candidate = value;
+    return (typeof candidate === 'object' &&
+        candidate !== null &&
+        typeof candidate.code === 'string' &&
+        typeof candidate.text === 'string' &&
+        typeof candidate.format === 'function');
+}
+/**
+ * Every declaration a `./messages` barrel exports.
+ *
+ * A caller cannot get there with `Object.values(barrel).filter(isMessageDeclaration)`:
+ * a barrel's value type is a union of its declarations AND its functions, and
+ * `filter` will not narrow a function type down to a `MessageDefinition`, so the
+ * result stays the union and reading `.code` off it does not compile. Taking the
+ * barrel as an opaque object is what makes the one-liner work.
+ */
+function collectMessages(barrel) {
+    return Object.values(barrel).filter(isMessageDeclaration);
+}
+//# sourceMappingURL=primitives.js.map

package/lib/messages/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/messages/primitives.ts"],"names":[],"mappings":"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"}

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

@@ -33,6 +33,7 @@ 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 { ResolvedMessage } from '../messages/primitives';
 import type { Project } from '../project';
 import type { TransferDiagnostic } from '../transfer-diagnostic';
 import type { TransferElement } from '../transfer-element';
@@ -69,12 +70,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

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,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AACrH,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;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;;;;;;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,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"}

package/lib/testing/data-doubles.js

@@ -55,8 +55,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);

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;;AA2FlF,4CAwBC;AA+BD,0DA0BC;AA1KD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,mDAAiE;AA0DjE;;;;;;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,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,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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.24",
+  "version": "1.0.0-next.27",
   "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"

package/src/client/data-port.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 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
@@ -77,10 +78,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

package/src/client/data-session.ts

@@ -9,11 +9,28 @@
 
 import type { MessageConnection } from 'vscode-jsonrpc';
 import { DATA_CLIENT_PROTOCOL_METHODS, DATA_SERVER_WIRE_PREFIX, type DataClientProtocol, type DataServerProtocol } from '../data';
+import { defineMessage, describeError, resolve } from '../messages/primitives';
 import { type RpcProxy, createRpcProxy } from '../rpc';
 import type { TransferDocument } from '../transfer-document';
 import type { TransferElement } from '../transfer-element';
 import type { DataPort } from './data-port';
 
+/**
+ * The transport never opened. A complete sentence rather than a fragment: a
+ * fragment is nested inside a sentence the framework does not own, so no
+ * translator controls the whole and the composition cannot be made to read
+ * correctly in every language.
+ */
+export const DATA_SERVER_CONNECT_FAILED = defineMessage(
+   'hydranium/protocol/data-server-connect-failed',
+   'Could not connect to the data server: {detail}'
+);
+
+export const DATA_SERVER_NOT_READY = defineMessage(
+   'hydranium/protocol/data-server-not-ready',
+   'The data server did not become ready: {detail}'
+);
+
 /** Options for {@link DataSession}. */
 export interface DataSessionOptions {
    /**
@@ -168,7 +185,9 @@ export class DataSession<TTransfer extends TransferElement> {
       // Rejection is reported here rather than left to float: an unhandled
       // rejection on a connection promise is the failure mode that reads as
       // "the model is empty" instead of "the transport never opened".
-      connection.catch((error: unknown) => this.port.reportError(error, 'connecting to the data server'));
+      connection.catch((error: unknown) =>
+         this.port.reportError(error, resolve(DATA_SERVER_CONNECT_FAILED, { detail: describeError(error) }))
+      );
       const server = createRpcProxy<DataServerProtocol<TTransfer>, DataClientProtocol<TTransfer>>(connection, {
          methodNamespace: this.methodNamespace,
          localTarget: this.client,
@@ -189,7 +208,7 @@ export class DataSession<TTransfer extends TransferElement> {
          if (this.generation === generation) {
             this.generation = undefined;
          }
-         this.port.reportError(error, 'waiting for the data server to become ready');
+         this.port.reportError(error, resolve(DATA_SERVER_NOT_READY, { detail: describeError(error) }));
          throw error;
       }
    }

package/src/client/message-relay.ts

@@ -8,8 +8,29 @@
  ********************************************************************************/
 
 import { Emitter, type Disposable, type Event, type Message, type MessageReader, type MessageWriter } from 'vscode-jsonrpc';
+import { defineMessage, describeError, resolve, type ResolvedMessage } from '../messages/primitives';
 import type { PostMessageChannel } from './post-message-transport';
 
+export const RELAY_TRANSPORT_OPEN_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-open-failed',
+   'Could not open the transport to relay: {detail}'
+);
+
+export const RELAY_TRANSPORT_READ_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-read-failed',
+   'Could not read from the relayed transport: {detail}'
+);
+
+export const RELAY_TRANSPORT_WRITE_FAILED = defineMessage(
+   'hydranium/protocol/relay-transport-write-failed',
+   'Could not write to the relayed transport: {detail}'
+);
+
+export const RELAY_REPLAY_FAILED = defineMessage(
+   'hydranium/protocol/relay-replay-failed',
+   'Could not replay a buffered message to the relayed transport: {detail}'
+);
+
 /**
  * The framed side of a relay: the reader/writer pair over whatever transport the
  * host actually holds — a TCP socket to the data-server, a child process' stdio,
@@ -30,13 +51,14 @@ export interface RelayTransport {
 export interface MessageRelayOptions {
    /**
     * Surface a failure the way the host does. Same contract as
-    * `DataPort.reportError`: `context` names what was being attempted.
+    * `DataPort.reportError`: `reported` is a complete sentence plus the identity
+    * needed to render it in another language.
     *
     * A relay has no other way to report — it sits between two transports and
     * owns neither, so a swallowed error here presents as a form that never
     * populates.
     */
-   readonly reportError?: (error: unknown, context: string) => void;
+   readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
 }
 
 /** A live relay. Dispose to tear both directions down. */
@@ -143,7 +165,7 @@ export function relayToPostMessageChannel(
          bufferSubscription?.dispose();
          bufferSubscription = undefined;
          buffered.length = 0;
-         options.reportError?.(error, 'opening the transport to relay');
+         options.reportError?.(error, resolve(RELAY_TRANSPORT_OPEN_FAILED, { detail: describeError(error) }));
          closeFramedSide();
          return false;
       }
@@ -166,12 +188,12 @@ export function relayToPostMessageChannel(
          opened.reader.listen(message => channel.post(message)),
          opened.reader.onClose(() => closeFramedSide()),
          opened.reader.onError(error => {
-            options.reportError?.(error, 'reading from the relayed transport');
+            options.reportError?.(error, resolve(RELAY_TRANSPORT_READ_FAILED, { detail: describeError(error) }));
             closeFramedSide();
          }),
          channel.onMessage(message => {
             void opened.writer.write(message).catch((error: unknown) => {
-               options.reportError?.(error, 'writing to the relayed transport');
+               options.reportError?.(error, resolve(RELAY_TRANSPORT_WRITE_FAILED, { detail: describeError(error) }));
             });
          })
       );
@@ -183,7 +205,7 @@ export function relayToPostMessageChannel(
 
       for (const message of buffered) {
          void opened.writer.write(message).catch((error: unknown) => {
-            options.reportError?.(error, 'replaying a buffered message to the relayed transport');
+            options.reportError?.(error, resolve(RELAY_REPLAY_FAILED, { detail: describeError(error) }));
          });
       }
       buffered.length = 0;

package/src/errors.ts

@@ -8,6 +8,20 @@
  ********************************************************************************/
 
 import { ResponseError } from 'vscode-jsonrpc';
+import { defineMessage, type HydraniumMessageData, messageData } from './messages/primitives';
+
+/**
+ * The catalogue declaration behind {@link ConflictError}'s sentence.
+ *
+ * Its English must keep containing {@link CONFLICT_ERROR_MESSAGE_MARKER}: the
+ * marker is tier 3 of {@link isConflictError}'s ladder, and it matches on text.
+ * That tier only ever works untranslated, which is why it is the last resort
+ * behind the numeric code rather than the primary check.
+ */
+export const STALE_BASED_UPDATE = defineMessage(
+   'hydranium/protocol/stale-based-update',
+   'Stale-based update for {uri}: expected v{expected}, server is at v{actual}'
+);
 
 /**
  * Application-specific JSON-RPC error code for {@link ConflictError}.
@@ -24,7 +38,7 @@ export const CONFLICT_ERROR_CODE = 1001;
  * Structured payload carried in {@link ConflictError.data}, and the only place
  * a post-RPC caller can read the version mismatch from.
  */
-export interface ConflictErrorData {
+export interface ConflictErrorData extends HydraniumMessageData {
    readonly uri: string;
    /** The based-on version the caller authored against. */
    readonly expected: number;
@@ -65,11 +79,11 @@ export interface ConflictErrorData {
  */
 export class ConflictError extends ResponseError<ConflictErrorData> {
    constructor(uri: string, expected: number, actual: number) {
-      super(CONFLICT_ERROR_CODE, `Stale-based update for ${uri}: expected v${expected}, server is at v${actual}`, {
-         uri,
-         expected,
-         actual
-      });
+      const params = { uri, expected, actual };
+      // The identity rides alongside the typed payload rather than replacing
+      // it: this class's getters and `isConflictError`'s name check are surface
+      // an adopter may bind, so the payload widens rather than changing shape.
+      super(CONFLICT_ERROR_CODE, STALE_BASED_UPDATE.format(params), { ...params, ...messageData(STALE_BASED_UPDATE, params) });
       this.name = 'ConflictError';
       // ResponseError's constructor calls `Object.setPrototypeOf(this,
       // ResponseError.prototype)` to keep its own prototype chain intact across

package/src/index.ts

@@ -24,6 +24,10 @@ export * from './errors';
 export * from './host-diagnostics';
 export * from './logger';
 export * from './latency-collector';
+// The primitives only. The `./messages` subpath additionally enumerates this
+// package's own declarations, which the root barrel already re-exports through
+// the modules that raise them.
+export * from './messages/primitives';
 export * from './patch-merge';
 export * from './noop-logger';
 export * from './observable-value';

package/src/messages/index.ts

@@ -0,0 +1,35 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * The message-externalization mechanism, plus every user-facing message
+ * `@hydranium/protocol` itself raises.
+ *
+ * Declarations stay beside their call sites and are re-exported here, so this is
+ * enumeration rather than centralization: a code's package segment has to name
+ * the package that raises it, and a shared module would make that segment a lie
+ * for every message in it. Adding a message therefore touches the file that
+ * raises it and this list, and nothing else.
+ *
+ * A barrel makes every code and English default public API, so renaming a code
+ * is a breaking change. That was already true — an adopter's catalogue keys on
+ * these codes either way — but it is now in the type system rather than implicit.
+ * The English is a fallback, not a contract; the code is the contract.
+ */
+
+export * from './primitives';
+
+export { STALE_BASED_UPDATE } from '../errors';
+export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/data-session';
+export {
+   RELAY_REPLAY_FAILED,
+   RELAY_TRANSPORT_OPEN_FAILED,
+   RELAY_TRANSPORT_READ_FAILED,
+   RELAY_TRANSPORT_WRITE_FAILED
+} from '../client/message-relay';