@hydranium/protocol 1.0.0-next.37 → 1.0.0-next.371

package/lib/logger.d.ts

@@ -24,15 +24,15 @@ export declare const LEVEL_LABELS: Record<LogLevel, string>;
  * and every `for` / `sub` / `with` derivation preserves the implementation type.
  */
 export interface Logger {
-    /** Log a message at error level. */
+    /** Requested work failed; logged once, by the code that ends the failure, not by one that rethrows it. */
     error(message?: string, ...args: unknown[]): this;
-    /** Log a message at warn level. */
+    /** An anomaly that was handled, or work declined by design, such as a conflict or a cap; a clean run logs none. */
     warn(message?: string, ...args: unknown[]): this;
-    /** Log a message at info level. */
+    /** A milestone the person running the server would recognise without knowing the internals. */
     info(message?: string, ...args: unknown[]): this;
-    /** Log a message at debug level. */
+    /** Diagnosis; its level decides whether the line is built, never which code runs. */
     debug(message?: string, ...args: unknown[]): this;
-    /** High-volume diagnostic lines, only emitted at the `'trace'` threshold. */
+    /** High-volume diagnosis, emitted only at the `'trace'` threshold; as for `debug`, no code runs only for it. */
     trace(message?: string, ...args: unknown[]): this;
     /** Log a message at info-level threshold with a `Log` label (rather than `Info`). */
     log(message?: string, ...args: unknown[]): this;
@@ -74,7 +74,23 @@ export declare namespace Logger {
     /** Read the current process-wide log threshold. */
     function getLevel(): LogThreshold;
     /**
-     * Whether a message at `level` would be emitted at the current threshold.
+     * Set the log file's own threshold, which {@link setLevel} does not move;
+     * `undefined` makes the file follow {@link getLevel}. A file sink compares
+     * against `getFileLevel() ?? getLevel()`, every other sink against
+     * {@link getLevel}.
+     *
+     * Set it through the file sink's own configuration, which clears it with
+     * the file: set here with no file configured, it widens
+     * {@link isLevelEnabled} for lines nothing writes.
+     */
+    function setFileLevel(level: LogThreshold | undefined): void;
+    /** Read the log file's own threshold, `undefined` while it follows {@link getLevel}. */
+    function getFileLevel(): LogThreshold | undefined;
+    /**
+     * Whether any sink takes a message at `level`: the more verbose of
+     * {@link getLevel} and {@link getFileLevel} decides. A sink that admits less
+     * re-checks its own threshold before writing.
+     *
      * Use to guard expensive log-line construction:
      * `if (Logger.isLevelEnabled('trace')) logger.trace(buildPayload())`.
      */
@@ -103,8 +119,23 @@ export declare function parseLogLevel(value: unknown): LogThreshold | undefined;
  * instead of duplicating the literal string.
  */
 export declare const DEFAULT_LOG_LEVEL_ENV = "HYDRANIUM_LOG_LEVEL";
-/** Env var the server reads its log file-tee target from. See {@link DEFAULT_LOG_LEVEL_ENV}. */
+/**
+ * Env var the server reads its log file-tee target from. The path may hold
+ * `{workspace}`, filled in once the server knows its workspace, and `{pid}`.
+ * See {@link DEFAULT_LOG_LEVEL_ENV}.
+ */
 export declare const DEFAULT_LOG_FILE_ENV = "HYDRANIUM_LOG_FILE";
+/**
+ * Env var the server reads the file tee's own threshold from, which the LSP
+ * log-level setting does not change. See {@link Logger.setFileLevel}.
+ */
+export declare const DEFAULT_LOG_FILE_LEVEL_ENV = "HYDRANIUM_LOG_FILE_LEVEL";
+/**
+ * Env var naming the file a Node server writes its CPU profile to when it
+ * ends. Takes `{workspace}` and `{pid}` as {@link DEFAULT_LOG_FILE_ENV} does;
+ * the write replaces the file, so `{pid}` keeps one per server.
+ */
+export declare const DEFAULT_CPU_PROFILE_FILE_ENV = "HYDRANIUM_CPU_PROFILE_FILE";
 /**
  * Human-readable formatting helpers used in log lines and diagnostic output.
  */

package/lib/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AACrE,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE5C,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAA8D,CAAC;AAEpH,uGAAuG;AACvG,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAMjD,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACpB,oCAAoC;IACpC,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAClD,mCAAmC;IACnC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,mCAAmC;IACnC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,oCAAoC;IACpC,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAClD,6EAA6E;IAC7E,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAClD,qFAAqF;IACrF,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,6EAA6E;IAC7E,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iFAAiF;IACjF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oFAAoF;IACpF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;;;;GASG;AACH,yBAAiB,MAAM,CAAC;IACrB,qGAAqG;IACrG,SAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAElD;IACD,mDAAmD;IACnD,SAAgB,QAAQ,IAAI,YAAY,CAEvC;IACD;;;;OAIG;IACH,SAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEvD;IACD;;;;OAIG;IACH,SAAgB,kBAAkB,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAEnE;CACH;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAGtE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAC3D,gGAAgG;AAChG,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD;;GAEG;AACH,yBAAiB,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAgB,SAAS,CAAC,CAAC,GAAE,IAAiB,GAAG,MAAM,CAMtD;IAED,wEAAwE;IACxE,SAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE1C;IAED,6EAA6E;IAC7E,SAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY3C;CACH"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/lib/logger.js

@@ -8,7 +8,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Format = exports.DEFAULT_LOG_FILE_ENV = exports.DEFAULT_LOG_LEVEL_ENV = exports.Logger = exports.LEVEL_LABELS = exports.LEVEL_ORDER = void 0;
+exports.Format = exports.DEFAULT_CPU_PROFILE_FILE_ENV = exports.DEFAULT_LOG_FILE_LEVEL_ENV = exports.DEFAULT_LOG_FILE_ENV = exports.DEFAULT_LOG_LEVEL_ENV = exports.Logger = exports.LEVEL_LABELS = exports.LEVEL_ORDER = void 0;
 exports.isLogThreshold = isLogThreshold;
 exports.parseLogLevel = parseLogLevel;
 exports.LEVEL_ORDER = { off: 0, error: 1, warn: 2, info: 3, debug: 4, trace: 5 };
@@ -23,6 +23,7 @@ exports.LEVEL_LABELS = {
 /** Module-global threshold; shared by every `AbstractLogger` instance so derived child
  *  loggers pick up live updates without each having to subscribe to a configuration source. */
 let currentLevel = 'info';
+let fileLevel;
 /**
  * Companion namespace for the {@link Logger} interface holding global
  * threshold configuration.
@@ -46,12 +47,34 @@ var Logger;
     }
     Logger.getLevel = getLevel;
     /**
-     * Whether a message at `level` would be emitted at the current threshold.
+     * Set the log file's own threshold, which {@link setLevel} does not move;
+     * `undefined` makes the file follow {@link getLevel}. A file sink compares
+     * against `getFileLevel() ?? getLevel()`, every other sink against
+     * {@link getLevel}.
+     *
+     * Set it through the file sink's own configuration, which clears it with
+     * the file: set here with no file configured, it widens
+     * {@link isLevelEnabled} for lines nothing writes.
+     */
+    function setFileLevel(level) {
+        fileLevel = level;
+    }
+    Logger.setFileLevel = setFileLevel;
+    /** Read the log file's own threshold, `undefined` while it follows {@link getLevel}. */
+    function getFileLevel() {
+        return fileLevel;
+    }
+    Logger.getFileLevel = getFileLevel;
+    /**
+     * Whether any sink takes a message at `level`: the more verbose of
+     * {@link getLevel} and {@link getFileLevel} decides. A sink that admits less
+     * re-checks its own threshold before writing.
+     *
      * Use to guard expensive log-line construction:
      * `if (Logger.isLevelEnabled('trace')) logger.trace(buildPayload())`.
      */
     function isLevelEnabled(level) {
-        return exports.LEVEL_ORDER[level] <= exports.LEVEL_ORDER[currentLevel];
+        return exports.LEVEL_ORDER[level] <= Math.max(exports.LEVEL_ORDER[currentLevel], fileLevel ? exports.LEVEL_ORDER[fileLevel] : 0);
     }
     Logger.isLevelEnabled = isLevelEnabled;
     /**
@@ -86,8 +109,23 @@ function parseLogLevel(value) {
  * instead of duplicating the literal string.
  */
 exports.DEFAULT_LOG_LEVEL_ENV = 'HYDRANIUM_LOG_LEVEL';
-/** Env var the server reads its log file-tee target from. See {@link DEFAULT_LOG_LEVEL_ENV}. */
+/**
+ * Env var the server reads its log file-tee target from. The path may hold
+ * `{workspace}`, filled in once the server knows its workspace, and `{pid}`.
+ * See {@link DEFAULT_LOG_LEVEL_ENV}.
+ */
 exports.DEFAULT_LOG_FILE_ENV = 'HYDRANIUM_LOG_FILE';
+/**
+ * Env var the server reads the file tee's own threshold from, which the LSP
+ * log-level setting does not change. See {@link Logger.setFileLevel}.
+ */
+exports.DEFAULT_LOG_FILE_LEVEL_ENV = 'HYDRANIUM_LOG_FILE_LEVEL';
+/**
+ * Env var naming the file a Node server writes its CPU profile to when it
+ * ends. Takes `{workspace}` and `{pid}` as {@link DEFAULT_LOG_FILE_ENV} does;
+ * the write replaces the file, so `{pid}` keeps one per server.
+ */
+exports.DEFAULT_CPU_PROFILE_FILE_ENV = 'HYDRANIUM_CPU_PROFILE_FILE';
 /**
  * Human-readable formatting helpers used in log lines and diagnostic output.
  */

package/lib/logger.js.map

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

package/lib/messages/index.d.ts

@@ -22,7 +22,9 @@
  * 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 { DOCUMENT_NOT_OPEN, DUPLICATE_CLIENT_ID, SAVE_FAILED, SESSION_CLOSED, STALE_BASE_VERSION_SAVE, STALE_BASE_VERSION_UPDATE } from '../errors';
+export { DATA_CONNECTION_SESSION_RESTORE_FAILED, DATA_CONNECTION_WATCH_RESTORE_FAILED } from '../client/data-connection';
+export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
+export { DATA_SESSION_ANSWER_WITHOUT_MODEL, DATA_SESSION_RESTORE_FAILED, DATA_SESSION_UNSAVED_LOST } from '../client/data-session';
 export { RELAY_REPLAY_FAILED, RELAY_TRANSPORT_OPEN_FAILED, RELAY_TRANSPORT_READ_FAILED, RELAY_TRANSPORT_WRITE_FAILED } from '../client/message-relay';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;GAcG;AAEH,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EACJ,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC9B,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;GAcG;AAEH,cAAc,cAAc,CAAC;AAE7B,OAAO,EACJ,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,uBAAuB,EACvB,yBAAyB,EAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,sCAAsC,EAAE,oCAAoC,EAAE,MAAM,2BAA2B,CAAC;AACzH,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,iCAAiC,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACnI,OAAO,EACJ,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC9B,MAAM,yBAAyB,CAAC"}

package/lib/messages/index.js

@@ -22,7 +22,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RELAY_TRANSPORT_WRITE_FAILED = exports.RELAY_TRANSPORT_READ_FAILED = exports.RELAY_TRANSPORT_OPEN_FAILED = exports.RELAY_REPLAY_FAILED = exports.DATA_SERVER_NOT_READY = exports.DATA_SERVER_CONNECT_FAILED = exports.STALE_BASED_UPDATE = void 0;
+exports.RELAY_TRANSPORT_WRITE_FAILED = exports.RELAY_TRANSPORT_READ_FAILED = exports.RELAY_TRANSPORT_OPEN_FAILED = exports.RELAY_REPLAY_FAILED = exports.DATA_SESSION_UNSAVED_LOST = exports.DATA_SESSION_RESTORE_FAILED = exports.DATA_SESSION_ANSWER_WITHOUT_MODEL = exports.DATA_SERVER_NOT_READY = exports.DATA_SERVER_CONNECT_FAILED = exports.DATA_CONNECTION_WATCH_RESTORE_FAILED = exports.DATA_CONNECTION_SESSION_RESTORE_FAILED = exports.STALE_BASE_VERSION_UPDATE = exports.STALE_BASE_VERSION_SAVE = exports.SESSION_CLOSED = exports.SAVE_FAILED = exports.DUPLICATE_CLIENT_ID = exports.DOCUMENT_NOT_OPEN = void 0;
 /**
  * The message-externalization mechanism, plus every user-facing message
  * `@hydranium/protocol` itself raises.
@@ -40,10 +40,22 @@ exports.RELAY_TRANSPORT_WRITE_FAILED = exports.RELAY_TRANSPORT_READ_FAILED = exp
  */
 __exportStar(require("./primitives"), exports);
 var errors_1 = require("../errors");
-Object.defineProperty(exports, "STALE_BASED_UPDATE", { enumerable: true, get: function () { return errors_1.STALE_BASED_UPDATE; } });
+Object.defineProperty(exports, "DOCUMENT_NOT_OPEN", { enumerable: true, get: function () { return errors_1.DOCUMENT_NOT_OPEN; } });
+Object.defineProperty(exports, "DUPLICATE_CLIENT_ID", { enumerable: true, get: function () { return errors_1.DUPLICATE_CLIENT_ID; } });
+Object.defineProperty(exports, "SAVE_FAILED", { enumerable: true, get: function () { return errors_1.SAVE_FAILED; } });
+Object.defineProperty(exports, "SESSION_CLOSED", { enumerable: true, get: function () { return errors_1.SESSION_CLOSED; } });
+Object.defineProperty(exports, "STALE_BASE_VERSION_SAVE", { enumerable: true, get: function () { return errors_1.STALE_BASE_VERSION_SAVE; } });
+Object.defineProperty(exports, "STALE_BASE_VERSION_UPDATE", { enumerable: true, get: function () { return errors_1.STALE_BASE_VERSION_UPDATE; } });
+var data_connection_1 = require("../client/data-connection");
+Object.defineProperty(exports, "DATA_CONNECTION_SESSION_RESTORE_FAILED", { enumerable: true, get: function () { return data_connection_1.DATA_CONNECTION_SESSION_RESTORE_FAILED; } });
+Object.defineProperty(exports, "DATA_CONNECTION_WATCH_RESTORE_FAILED", { enumerable: true, get: function () { return data_connection_1.DATA_CONNECTION_WATCH_RESTORE_FAILED; } });
+var rpc_connection_1 = require("../client/rpc-connection");
+Object.defineProperty(exports, "DATA_SERVER_CONNECT_FAILED", { enumerable: true, get: function () { return rpc_connection_1.DATA_SERVER_CONNECT_FAILED; } });
+Object.defineProperty(exports, "DATA_SERVER_NOT_READY", { enumerable: true, get: function () { return rpc_connection_1.DATA_SERVER_NOT_READY; } });
 var data_session_1 = require("../client/data-session");
-Object.defineProperty(exports, "DATA_SERVER_CONNECT_FAILED", { enumerable: true, get: function () { return data_session_1.DATA_SERVER_CONNECT_FAILED; } });
-Object.defineProperty(exports, "DATA_SERVER_NOT_READY", { enumerable: true, get: function () { return data_session_1.DATA_SERVER_NOT_READY; } });
+Object.defineProperty(exports, "DATA_SESSION_ANSWER_WITHOUT_MODEL", { enumerable: true, get: function () { return data_session_1.DATA_SESSION_ANSWER_WITHOUT_MODEL; } });
+Object.defineProperty(exports, "DATA_SESSION_RESTORE_FAILED", { enumerable: true, get: function () { return data_session_1.DATA_SESSION_RESTORE_FAILED; } });
+Object.defineProperty(exports, "DATA_SESSION_UNSAVED_LOST", { enumerable: true, get: function () { return data_session_1.DATA_SESSION_UNSAVED_LOST; } });
 var message_relay_1 = require("../client/message-relay");
 Object.defineProperty(exports, "RELAY_REPLAY_FAILED", { enumerable: true, get: function () { return message_relay_1.RELAY_REPLAY_FAILED; } });
 Object.defineProperty(exports, "RELAY_TRANSPORT_OPEN_FAILED", { enumerable: true, get: function () { return message_relay_1.RELAY_TRANSPORT_OPEN_FAILED; } });

package/lib/messages/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;;AAElF;;;;;;;;;;;;;;GAcG;AAEH,+CAA6B;AAE7B,oCAA+C;AAAtC,4GAAA,kBAAkB,OAAA;AAC3B,uDAA2F;AAAlF,0HAAA,0BAA0B,OAAA;AAAE,qHAAA,qBAAqB,OAAA;AAC1D,yDAKiC;AAJ9B,oHAAA,mBAAmB,OAAA;AACnB,4HAAA,2BAA2B,OAAA;AAC3B,4HAAA,2BAA2B,OAAA;AAC3B,6HAAA,4BAA4B,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;;AAElF;;;;;;;;;;;;;;GAcG;AAEH,+CAA6B;AAE7B,oCAOmB;AANhB,2GAAA,iBAAiB,OAAA;AACjB,6GAAA,mBAAmB,OAAA;AACnB,qGAAA,WAAW,OAAA;AACX,wGAAA,cAAc,OAAA;AACd,iHAAA,uBAAuB,OAAA;AACvB,mHAAA,yBAAyB,OAAA;AAE5B,6DAAyH;AAAhH,yIAAA,sCAAsC,OAAA;AAAE,uIAAA,oCAAoC,OAAA;AACrF,2DAA6F;AAApF,4HAAA,0BAA0B,OAAA;AAAE,uHAAA,qBAAqB,OAAA;AAC1D,uDAAmI;AAA1H,iIAAA,iCAAiC,OAAA;AAAE,2HAAA,2BAA2B,OAAA;AAAE,yHAAA,yBAAyB,OAAA;AAClG,yDAKiC;AAJ9B,oHAAA,mBAAmB,OAAA;AACnB,4HAAA,2BAA2B,OAAA;AAC3B,4HAAA,2BAA2B,OAAA;AAC3B,6HAAA,4BAA4B,OAAA"}

package/lib/messages/primitives.d.ts

@@ -108,19 +108,74 @@ export type HydraniumResponseError = ResponseError<HydraniumMessageData>;
  */
 export declare function messageError<S extends string>(code: number, message: MessageDefinition<S>, ...params: ParamsArg<S>): HydraniumResponseError;
 /**
- * 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.
+ * The reading user's language, as the tag a client declared.
+ *
+ * Neither validated nor normalised anywhere: rejecting an unfamiliar tag would
+ * be selecting a locale, which the framework does not do.
+ *
+ * NOT a Langium language id, which names a grammar. The two are strings of the
+ * same shape reachable from the same services, so one used where the other
+ * belongs misses every lookup rather than failing.
+ */
+export type Locale = string;
+/**
+ * A host's templates for one locale, keyed by the whole message code.
+ *
+ * **Flat, not nested.** A code is one key here, `/` separators included; a host
+ * whose own catalogue format nests — Theia's does — flattens on the way in. A
+ * map that nests instead misses every lookup while type-checking, because the
+ * value this is indexed by is `ResolvedMessage.code`.
+ *
+ * **Partial by nature rather than by convention.** A code with no entry renders
+ * its English default, so a catalogue covering none of a package's codes is a
+ * valid catalogue and not a broken one — which is what lets an adopter translate
+ * as much or as little as they like.
+ *
+ * Deliberately NOT narrowed to the codes that exist, and a `Code extends string`
+ * parameter would not buy what it appears to: a catalogue is loaded as JSON, so
+ * it reaches a checked position as a variable rather than as an object literal,
+ * and excess-property checking — the only thing that would reject a mistyped
+ * key — does not run there. The gain is a compile error for a catalogue with no
+ * correct key at all; the cost is a code union to maintain by hand, since a
+ * declaration does not carry its code as a literal type.
  */
-export declare function renderFrameworkMessage(message: ResolvedMessage, translations?: Record<string, string>): string;
+export type MessageCatalogue = Readonly<Record<string, string>>;
+export declare namespace MessageCatalogue {
+    /**
+     * One catalogue from several, for a renderer whose override supplies entries
+     * over the ones it inherits.
+     *
+     * **Later wins**, so a caller passes the inherited answer before its own.
+     *
+     * **No source at all answers `undefined`, not `{}`.** A renderer holds that
+     * answer as the locale having no catalogue and renders straight through; an
+     * empty object is a catalogue that misses every lookup, so returning one
+     * turns the opt-out into a per-message search that yields the same English.
+     */
+    function merge(...catalogues: ReadonlyArray<MessageCatalogue | undefined>): MessageCatalogue | undefined;
+}
+/**
+ * Render on the side that knows the reading user's locale. Omitting
+ * `translations` is how an adopter without i18n opts out, and yields the
+ * English.
+ */
+export declare function renderFrameworkMessage(message: ResolvedMessage, translations?: MessageCatalogue): string;
 export declare function resolvedFromResponseError(error: ResponseError<unknown>): ResolvedMessage | 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.
+ *
+ * For a reader of the client; the log takes {@link describeErrorWithStack}.
  */
 export declare function describeError(error: unknown): string;
+/**
+ * An error for the log: its stack where it has one, which names where it was
+ * thrown, and its causes, which name what failed when an error wraps another.
+ * Never for the client, whose reader cannot act on a stack.
+ */
+export declare function describeErrorWithStack(error: unknown): string;
 /**
  * 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

package/lib/messages/primitives.d.ts.map

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

package/lib/messages/primitives.js

@@ -8,6 +8,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageCatalogue = void 0;
 exports.defineMessage = defineMessage;
 exports.interpolate = interpolate;
 exports.messageData = messageData;
@@ -17,6 +18,7 @@ exports.messageError = messageError;
 exports.renderFrameworkMessage = renderFrameworkMessage;
 exports.resolvedFromResponseError = resolvedFromResponseError;
 exports.describeError = describeError;
+exports.describeErrorWithStack = describeErrorWithStack;
 exports.isMessageDeclaration = isMessageDeclaration;
 exports.collectMessages = collectMessages;
 const vscode_jsonrpc_1 = require("vscode-jsonrpc");
@@ -89,10 +91,32 @@ function hasMessageIdentity(data) {
 function messageError(code, message, ...params) {
     return new vscode_jsonrpc_1.ResponseError(code, message.format(...params), messageData(message, ...params));
 }
+var MessageCatalogue;
+(function (MessageCatalogue) {
+    /**
+     * One catalogue from several, for a renderer whose override supplies entries
+     * over the ones it inherits.
+     *
+     * **Later wins**, so a caller passes the inherited answer before its own.
+     *
+     * **No source at all answers `undefined`, not `{}`.** A renderer holds that
+     * answer as the locale having no catalogue and renders straight through; an
+     * empty object is a catalogue that misses every lookup, so returning one
+     * turns the opt-out into a per-message search that yields the same English.
+     */
+    function merge(...catalogues) {
+        const present = catalogues.filter((catalogue) => catalogue !== undefined);
+        if (present.length <= 1) {
+            return present[0];
+        }
+        return Object.assign({}, ...present);
+    }
+    MessageCatalogue.merge = merge;
+})(MessageCatalogue || (exports.MessageCatalogue = MessageCatalogue = {}));
 /**
- * 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.
+ * Render on the side that knows the reading user's locale. Omitting
+ * `translations` is how an adopter without i18n opts out, and yields the
+ * English.
  */
 function renderFrameworkMessage(message, translations) {
     const template = translations?.[message.code];
@@ -106,9 +130,78 @@ function resolvedFromResponseError(error) {
  * 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.
+ *
+ * For a reader of the client; the log takes {@link describeErrorWithStack}.
  */
 function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
+    return describeSafely(error, () => (error instanceof Error ? error.message : error));
+}
+/**
+ * An error for the log: its stack where it has one, which names where it was
+ * thrown, and its causes, which name what failed when an error wraps another.
+ * Never for the client, whose reader cannot act on a stack.
+ */
+function describeErrorWithStack(error) {
+    // A cause chain may loop back on itself.
+    return describeChain(error, new Set());
+}
+function describeChain(error, seen) {
+    const lines = [];
+    let current = error;
+    let prefix = '';
+    try {
+        do {
+            seen.add(current);
+            const described = current;
+            lines.push(prefix + describeSafely(described, () => (described instanceof Error ? stackOrMessage(described) : described)));
+            // Node fails a connect to several addresses with one, whose own message is empty.
+            if (current instanceof AggregateError) {
+                try {
+                    const errors = current.errors;
+                    lines.push(...errors.filter(inner => !seen.has(inner)).map(inner => `Including: ${describeChain(inner, seen)}`));
+                }
+                catch {
+                    // An `errors` that is no list, or throws when read; the cause still follows.
+                }
+            }
+            current = current instanceof Error ? current.cause : undefined;
+            prefix = 'Caused by: ';
+        } while (current !== undefined && current !== null && !seen.has(current));
+    }
+    catch {
+        // A getter or proxy trap threw while walking the chain; keep what was described.
+    }
+    return lines.join('\n');
+}
+/** `error`'s stack as a string, or its message where reading or converting the stack throws. */
+function stackOrMessage(error) {
+    try {
+        return String(error.stack ?? error.message);
+    }
+    catch {
+        return String(error.message);
+    }
+}
+/**
+ * What `select()` picks from `value`, as a string, or where selecting or
+ * converting it throws, as `String` does for an object without a prototype,
+ * the `[object Type]` tag, or where reading the tag throws too, the value's
+ * type. Describing an error must not throw, or the failure it reports is lost;
+ * the conversion sits inside the guard because a thrown value's `message` or
+ * `stack` need not be a string.
+ */
+function describeSafely(value, select) {
+    try {
+        return String(select());
+    }
+    catch {
+        try {
+            return Object.prototype.toString.call(value);
+        }
+        catch {
+            return `[${typeof value}]`;
+        }
+    }
 }
 /**
  * Recognises a declaration among a barrel's exports. The `format` check is what

package/lib/messages/primitives.js.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/messages/primitives.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;AAwDlF,sCAGC;AAeD,kCASC;AAoBD,kCAEC;AAOD,0BAEC;AASD,gDAUC;AAeD,oCAMC;AAOD,wDAGC;AAED,8DAEC;AAQD,sCAEC;AAOD,oDASC;AAWD,0CAEC;AA7MD,mDAA+C;AAgD/C;;;;;GAKG;AACH,SAAgB,aAAa,CAAmB,IAAY,EAAE,IAAoB;IAC/E,MAAM,OAAO,GAAG,IAAS,CAAC;IAC1B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;AAC5F,CAAC;AAED,MAAM,WAAW,GAAG,cAAc,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,SAAgB,WAAW,CAAC,QAAgB,EAAE,MAAqB;IAChE,sEAAsE;IACtE,6EAA6E;IAC7E,2BAA2B;IAC3B,MAAM,MAAM,GAAG,MAAiE,CAAC;IACjF,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE;QACzD,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACN,CAAC;AAoBD,SAAgB,WAAW,CAAmB,OAA6B,EAAE,GAAG,IAAkB;IAC/F,OAAO,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,SAAgB,OAAO,CAAmB,OAA6B,EAAE,GAAG,IAAkB;IAC3F,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,IAAa;IAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,IAAI,IAAI,CAAC,EAAE,CAAC;QAC9F,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,QAAQ,GAAI,IAA+B,CAAC,SAAS,CAAC;IAC5D,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChF,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,QAAoC,CAAC;IACvD,OAAO,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC;AAClH,CAAC;AAUD;;;;GAIG;AACH,SAAgB,YAAY,CACzB,IAAY,EACZ,OAA6B,EAC7B,GAAG,MAAoB;IAEvB,OAAO,IAAI,8BAAa,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AAC9F,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,OAAwB,EAAE,YAAqC;IACnG,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,OAAO,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;AAC1E,CAAC;AAED,SAAgB,yBAAyB,CAAC,KAA6B;IACpE,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACxG,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB,CAAC,KAAc;IAChD,MAAM,SAAS,GAAG,KAAoE,CAAC;IACvF,OAAO,CACJ,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI;QAClB,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAClC,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAClC,OAAO,SAAS,CAAC,MAAM,KAAK,UAAU,CACxC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAAC,MAAc;IAC3C,OAAQ,MAAM,CAAC,MAAM,CAAC,MAAM,CAAe,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../../src/messages/primitives.ts"],"names":[],"mappings":"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"}

package/lib/model-server.d.ts

@@ -12,8 +12,14 @@
  * language identifier — consumers parameterise the document/root types
  * over `TRoot`.
  */
-import type { TransferClientArgs } from './model-service/args';
 import type { ReferenceCandidate } from './model-service/reference-candidate';
+/** Identifies a client-document binding. */
+export interface TransferClientArgs {
+    /** Document URI. */
+    uri: string;
+    /** Stable identifier for the client invoking the operation. */
+    clientId: string;
+}
 /** Open a document on behalf of a client. */
 export interface OpenModelArgs extends TransferClientArgs {
     /**
@@ -35,19 +41,43 @@ export interface OpenModelArgs extends TransferClientArgs {
      * means read from the filesystem, which is the normal case.
      *
      * Honoured only on the first open of a URI: opening an already-open document
-     * is a no-op, so passing `text` for one silently changes nothing. Write
-     * through the update path instead.
+     * attaches the caller to the existing shared entry and does not replace its
+     * content with this seed. Write through the update path instead. The open
+     * response reads the current shared content after registration; a textual
+     * `didOpen` attach may separately refresh the build.
      */
     text?: string;
+    /**
+     * Kept on the server for this client's open until it closes, for the
+     * server's own open path to read. Only a client session's open keeps them,
+     * and a repeat open keeps the first open's.
+     */
+    options?: object;
 }
 /** Close a previously-opened document for the client. */
 export interface CloseModelArgs extends TransferClientArgs {
 }
 export interface TransferUpdatedEvent<TDocument> {
     document: TDocument;
+    /**
+     * The client whose write this event echoes: the author of the version on a
+     * `'changed'`, and the unknown-client id on a `'rebuilt'`, which echoes no
+     * write. A recipient compares it against its own id to recognise its echo.
+     */
     sourceClientId: string;
-    /** See `ModelDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
-    reason: 'changed' | 'deleted' | 'rebuilt' | 'saved';
+    /** See `TransferDocumentUpdateReason` in `./data/events` for the canonical reason set + semantics. */
+    reason: 'changed' | 'rebuilt' | 'saved';
+    /**
+     * The client whose write caused the build that produced this event, or the
+     * unknown-client id when no single client's did. On a `'changed'` it is the
+     * version's author. A `'rebuilt'` names the writer of another document, so
+     * it is a cause, never an echo: its diagnostics and references are new to
+     * that writer too.
+     *
+     * In-process only: the data head does not send it, and an event built
+     * elsewhere may leave it out, which a reader takes as "not known".
+     */
+    causedBy?: string;
 }
 export interface TransferSavedEvent<TDocument> {
     /** The document as persisted — the state that reached disk, not the state at request time. */
@@ -114,10 +144,10 @@ export declare function isElementSource(object: unknown): object is ElementSourc
 /** An element of a document that does not yet exist on disk — used during element creation flows. */
 export interface SyntheticSource {
     /**
-     * The document the element would belong to. That document must already be
-     * LOADED — the default resolution takes its parse root as the synthetic
-     * node's container and answers `undefined` when it is not, so a URI for a
-     * file that exists on disk but was never opened resolves to nothing.
+     * The document the element would belong to. It need not be loaded, or
+     * exist — an unloaded URI materialises a transient empty document, so a
+     * folder is a valid anchor. A URI that IS loaded contributes that
+     * document's parse root as the container, putting its contents in scope.
      */
     uri: string;
     /**
@@ -126,6 +156,16 @@ export interface SyntheticSource {
      * it is what scoping filters candidates against.
      */
     type: string;
+    /**
+     * The grammar the element will belong to, as a language id.
+     *
+     * Optional because `uri` and `type` each answer on their own when
+     * unambiguous. Set it when neither is: a URI naming no file carries no
+     * extension to route on, and a `type` two grammars can produce identifies
+     * neither. Unset, such a source reaches the server's own policy, which
+     * answers the same way for every caller.
+     */
+    language?: string;
 }
 export declare function isSyntheticSource(object: unknown): object is SyntheticSource;
 /**
@@ -135,7 +175,7 @@ export declare function isSyntheticSource(object: unknown): object is SyntheticS
 export declare namespace ReferenceSource {
     function document(uri: string): DocumentSource;
     function element(name: string, type?: string): ElementSource;
-    function synthetic(uri: string, type: string): SyntheticSource;
+    function synthetic(uri: string, type: string, language?: string): SyntheticSource;
 }
 /**
  * One step in a synthetic navigation path from a {@link ReferenceSource}
@@ -329,9 +369,10 @@ export interface FindNextNameArgs {
      */
     uri: string;
     /**
-     * The AST `$type` of the element being named. Collisions are only looked for
-     * among elements of that same type, so the returned name may still be taken
-     * by an element of another type.
+     * The AST `$type` of the element being named. Collisions are looked for
+     * among elements of that type and of any subtype of it, so a supertype
+     * names a uniqueness scope its concrete types share; the returned name may
+     * still be taken by an element outside that hierarchy.
      */
     type: string;
     /**
@@ -348,5 +389,11 @@ export interface FindNextNameArgs {
      * See {@link NameTier} for what each tier covers.
      */
     tier?: NameTier;
+    /**
+     * The grammar to name under, routed as {@link SyntheticSource.language} —
+     * this call builds one. A caller that sets it there must set it here, or
+     * candidates and the name it proposes come from different grammars.
+     */
+    language?: string;
 }
 //# sourceMappingURL=model-server.d.ts.map