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

package/src/format-log-arg.ts

@@ -0,0 +1,176 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { describeErrorWithStack } from './messages/primitives';
+
+/** How deep an object argument is rendered; a deeper object reads `[Object]` or `[Array]`. */
+const LOG_ARG_DEPTH = 2;
+/** How many items or keys of one array or object are rendered. */
+const LOG_ARG_ITEMS = 100;
+/** How many characters of one string or key inside an object argument are rendered. */
+const LOG_ARG_STRING_LENGTH = 10_000;
+/**
+ * About how many characters one argument renders, since the limits above
+ * multiply. The entry that would pass it reads `...`; later ones are left out.
+ */
+const LOG_ARG_LENGTH = 100_000;
+
+/** Options of {@link formatLogArg}. An object, so that a `map` index cannot be passed as one. */
+export interface FormatLogArgOptions {
+   /** The `space` argument of `JSON.stringify`; compact where omitted. */
+   readonly indent?: number;
+}
+
+/**
+ * Render a log argument as text for a log line:
+ * - a string as it is;
+ * - an error by its stack and causes;
+ * - another object as JSON, cut to a bounded size;
+ * - anything else by its description, as is an object JSON renders as nothing
+ *   or cannot render.
+ *
+ * The cut is needed because the log call serialises synchronously and every
+ * Langium AST node is cyclic. The JSON stops at `LOG_ARG_DEPTH` levels,
+ * `LOG_ARG_ITEMS` items or keys and `LOG_ARG_STRING_LENGTH` characters per
+ * string or key, and at about `LOG_ARG_LENGTH` in all. A reference back to an
+ * object that contains it reads `[Circular]`, and a BigInt its digits; the
+ * markers are JSON strings. `util.inspect` would cut too, but is Node-only.
+ *
+ * Never throws, since a log call that throws loses the line and interrupts its
+ * caller. A `%s`-style specifier is not substituted.
+ */
+export function formatLogArg(value: unknown, options: FormatLogArgOptions = {}): string {
+   if (typeof value === 'string') {
+      return value;
+   }
+   if (typeof value === 'object' && value !== null) {
+      try {
+         // `undefined` where `toJSON` returns nothing.
+         const json: string | undefined =
+            value instanceof Error ? undefined : JSON.stringify(value, boundedReplacer(options.indent), options.indent);
+         if (json !== undefined) {
+            return json;
+         }
+      } catch {
+         // A throwing getter or `toJSON`, or a revoked proxy; described below instead.
+      }
+   }
+   return describeErrorWithStack(value);
+}
+
+interface Visit {
+   readonly parent: object;
+   readonly depth: number;
+   /** The object a cut copy stands in for, which a cycle refers back to. */
+   readonly source: object;
+}
+
+function boundedReplacer(indent: number | undefined): (this: object, key: string, value: unknown) => unknown {
+   // Keyed by the object last entered; JSON is written depth first, so its entry is on the path being written.
+   const visits = new Map<object, Visit>();
+   const isOnPath = (value: object, holder: object | undefined): boolean =>
+      holder !== undefined && ((visits.get(holder)?.source ?? holder) === value || isOnPath(value, visits.get(holder)?.parent));
+   // As `JSON.stringify` clamps its `space`.
+   const space = Math.min(10, Math.max(0, Math.floor(indent ?? 0)));
+   let remaining = LOG_ARG_LENGTH;
+   let exhausted = false;
+   return function (this: object, key: string, raw: unknown): unknown {
+      if (exhausted) {
+         // In an object the entry is left out; in an array it reads `null`.
+         return undefined;
+      }
+      // A boxed primitive is written as its value, so it is cut as one.
+      const value = raw instanceof String || raw instanceof Number || raw instanceof Boolean || raw instanceof BigInt ? raw.valueOf() : raw;
+      const depth = (visits.get(this)?.depth ?? -1) + 1;
+      const rendered = render(value, depth, this);
+      const isObject = typeof rendered === 'object' && rendered !== null;
+      // What this entry writes: its value, its key unless it is an item, and the punctuation and indent around them.
+      const written = isObject ? undefined : JSON.stringify(rendered);
+      // A value JSON cannot write is left out of an object, key and all, and written as `null` in an array.
+      const leftOut = !isObject && written === undefined && !Array.isArray(this);
+      const valueLength = isObject ? 2 : (written?.length ?? 4);
+      const keyLength = depth === 0 || Array.isArray(this) ? 0 : JSON.stringify(key).length + 1 + (space > 0 ? 1 : 0);
+      const layoutLength = 1 + (space > 0 ? (1 + space * depth) * (isObject ? 2 : 1) : 0);
+      const length = leftOut ? 0 : valueLength + keyLength + layoutLength;
+      if (length > remaining) {
+         exhausted = true;
+         return '...';
+      }
+      remaining -= length;
+      if (isObject) {
+         visits.set(rendered, { parent: this, depth, source: value as object });
+      }
+      return rendered;
+   };
+
+   function render(value: unknown, depth: number, holder: object): unknown {
+      if (typeof value === 'string') {
+         return cutString(value);
+      }
+      if (typeof value === 'bigint') {
+         return String(value);
+      }
+      if (typeof value !== 'object' || value === null) {
+         return value;
+      }
+      if (isOnPath(value, holder)) {
+         return '[Circular]';
+      }
+      if (depth > LOG_ARG_DEPTH) {
+         return Array.isArray(value) || isTypedArray(value) ? '[Array]' : '[Object]';
+      }
+      return cut(value);
+   }
+}
+
+function cutString(value: string): string {
+   const more = value.length - LOG_ARG_STRING_LENGTH;
+   return more > 0 ? `${value.slice(0, LOG_ARG_STRING_LENGTH)}... ${more} more characters` : value;
+}
+
+function isTypedArray(value: object): value is ArrayLike<unknown> {
+   return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+/**
+ * `value`, or a copy of its first {@link LOG_ARG_ITEMS} items or keys, keys cut
+ * as strings are, with a note of how many more there are. A typed array is
+ * copied to an array, which reads its items without listing its keys.
+ */
+function cut(value: object): object {
+   if (Array.isArray(value) || isTypedArray(value)) {
+      const more = value.length - LOG_ARG_ITEMS;
+      const items = Array.from({ length: Math.min(value.length, LOG_ARG_ITEMS) }, (_, i) => value[i]);
+      return more > 0 ? [...items, `... ${more} more items`] : Array.isArray(value) ? value : items;
+   }
+   // Linear in the keys: no API lists the first few alone, and `JSON.stringify` would list them all too.
+   const keys = Object.keys(value);
+   const more = keys.length - LOG_ARG_ITEMS;
+   const kept = keys.slice(0, LOG_ARG_ITEMS);
+   if (more <= 0 && kept.every(key => key.length <= LOG_ARG_STRING_LENGTH)) {
+      return value;
+   }
+   // No prototype, so a `__proto__` key is an entry like any other.
+   const copy: Record<string, unknown> = Object.create(null);
+   // A cut key or the note can equal a key already written; numbered, so neither entry is lost.
+   const add = (key: string, entry: unknown): void => {
+      let unique = key;
+      for (let i = 2; unique in copy; i++) {
+         unique = `${key} (${i})`;
+      }
+      copy[unique] = entry;
+   };
+   for (const key of kept) {
+      add(cutString(key), (value as Record<string, unknown>)[key]);
+   }
+   if (more > 0) {
+      add(`... ${more} more keys`, '...');
+   }
+   return copy;
+}

package/src/glsp-edits-settled-actions.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * Copyright (c) 2026 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
+ ********************************************************************************/
+
+// Declared field by field rather than extending GLSP's action types, as the
+// save actions are: this package carries no GLSP dependency.
+
+/**
+ * A request the server answers, with an {@link EditsSettledAction}, once every
+ * edit the client sent before it has been handled and its text has reached
+ * the language client, so the client knows those edits are answered.
+ *
+ * An operation has no answer of its own: the server replies with a model
+ * update and a dirty state, with a message, or with nothing at all when the
+ * operation changed nothing. The server handles a client's actions one at a
+ * time, so a request sent after the edits is answered after them, whatever
+ * each one answered. A server that fails it answers with a GLSP
+ * `RejectAction`, which ends the wait too.
+ */
+export interface RequestEditsSettledAction {
+   /** Answered only by a server that advertises this kind. The framework's dispatcher sends none to a server that does not. */
+   kind: typeof RequestEditsSettledAction.KIND;
+   /** The id the response echoes as its `responseId`. Empty until the dispatcher assigns one. */
+   requestId: string;
+   /**
+    * How long the server waits before it rejects the request, as it does any
+    * request; a rejection then means not settled, and the answer that follows
+    * is dropped. GLSP's `requestUntil` sets one; `request` leaves it unset.
+    */
+   timeout?: number;
+   /** GLSP's typing marker for the response. Never set. */
+   readonly _?: EditsSettledAction;
+}
+
+export namespace RequestEditsSettledAction {
+   export const KIND = 'hydraniumRequestEditsSettled';
+
+   export function create(options: { requestId?: string } = {}): RequestEditsSettledAction {
+      return { kind: KIND, requestId: '', ...options };
+   }
+}
+
+/** The server's answer to a {@link RequestEditsSettledAction}. */
+export interface EditsSettledAction {
+   /** No client handler takes this kind: the dispatcher settles the request by {@link responseId} instead. */
+   kind: typeof EditsSettledAction.KIND;
+   /** The `requestId` of the request this answers. The server's dispatcher sets it. */
+   responseId: string;
+}
+
+export namespace EditsSettledAction {
+   export const KIND = 'hydraniumEditsSettled';
+
+   export function create(options: { responseId?: string } = {}): EditsSettledAction {
+      return { kind: KIND, responseId: '', ...options };
+   }
+}

package/src/glsp-request-model-args.ts

@@ -0,0 +1,16 @@
+/********************************************************************************
+ * 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 `RequestModelAction` option carrying a diagram's resume token. A load
+ * whose token matches the one the live session under its client id was started
+ * with takes that session over, so a diagram that reconnects or reloads keeps
+ * its unsaved text; without it, the id held by another session is refused.
+ */
+export const RESUME_TOKEN_ARG = 'hydraniumResumeToken';

package/src/glsp-save-model-actions.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Declared field by field rather than extending GLSP's action types: this
+// package carries no GLSP dependency, and both GLSP heads already depend on it.
+// The fields are GLSP's own, so both actions are assignable to GLSP's
+// `RequestAction` and `ResponseAction`.
+
+/**
+ * A save of a diagram's model that the server answers, with a
+ * {@link ModelSavedAction} once the save has finished or a GLSP
+ * `RejectAction` when it fails.
+ *
+ * It carries what GLSP's `SaveModelAction` carries, and the server saves it the
+ * same way. GLSP's `SaveModelAction` is not answered: the server's only
+ * reply is a dirty-state change, which the client drops when the dirty flag
+ * does not change, so a client cannot tell which save an answer belongs to or
+ * whether a save failed.
+ */
+export interface RequestSaveModelAction {
+   /**
+    * Answered only by a server that advertises this kind. The framework's
+    * Theia saveable sends GLSP's `SaveModelAction` to one that does not.
+    */
+   kind: typeof RequestSaveModelAction.KIND;
+   /** The id the response echoes as its `responseId`. Empty until the dispatcher assigns one. */
+   requestId: string;
+   /** How long the receiver waits for its own handler, in milliseconds. */
+   timeout?: number;
+   /** The file to save to, as in GLSP's `SaveModelAction`; absent saves to the diagram's source. */
+   fileUri?: string;
+   /** GLSP's typing marker for the response. Never set. */
+   readonly _?: ModelSavedAction;
+}
+
+export namespace RequestSaveModelAction {
+   export const KIND = 'hydraniumRequestSaveModel';
+
+   export function create(options: { fileUri?: string; requestId?: string } = {}): RequestSaveModelAction {
+      return { kind: KIND, requestId: '', ...options };
+   }
+}
+
+/** The server's answer to a {@link RequestSaveModelAction} that saved. */
+export interface ModelSavedAction {
+   /** No client handler takes this kind: the dispatcher settles the save by {@link responseId} instead. */
+   kind: typeof ModelSavedAction.KIND;
+   /** The `requestId` of the save this answers. The server's dispatcher sets it. */
+   responseId: string;
+}
+
+export namespace ModelSavedAction {
+   export const KIND = 'hydraniumModelSaved';
+
+   export function create(options: { responseId?: string } = {}): ModelSavedAction {
+      return { kind: KIND, responseId: '', ...options };
+   }
+}

package/src/index.ts

@@ -15,12 +15,18 @@
 // every production bundle that imports the root.
 
 export * from './abstract-logger';
+export * from './console-logger';
 export * from './client';
+export * from './client-ids';
 export * from './clock';
 export * from './data';
 export * from './browser-runtime';
 export * from './debouncer';
+export * from './glsp-edits-settled-actions';
+export * from './glsp-request-model-args';
+export * from './glsp-save-model-actions';
 export * from './errors';
+export * from './format-log-arg';
 export * from './host-diagnostics';
 export * from './logger';
 export * from './latency-collector';
@@ -29,17 +35,22 @@ export * from './latency-collector';
 // the modules that raise them.
 export * from './messages/primitives';
 export * from './patch-merge';
+export * from './reconcile-write';
 export * from './noop-logger';
 export * from './observable-value';
+export * from './pending-work-tracker';
 export * from './profile-session';
 export * from './profiling';
 export * from './tracer';
 export * from './transfer-diagnostic';
 export * from './transfer-element';
+export * from './types';
 export * from './model-service';
 export * from './transfer-document';
 export * from './model-server';
 export * from './project';
+export * from './random-uuid';
+export * from './save-text-document';
 export * from './rpc';
 export * from './uri';
 export * from './util';

package/src/latency-collector.ts

@@ -87,8 +87,13 @@ export interface LatencyReport {
  */
 export type LatencyRetention = { readonly kind: 'keep-all' } | { readonly kind: 'ring-buffer'; readonly maxSamplesPerMethod: number };
 
-/** Per-method state: retained samples (bounded in ring-buffer mode) plus lifetime totals. */
-interface MethodAccumulator {
+/**
+ * Per-method state: retained samples (bounded in ring-buffer mode) plus lifetime
+ * totals. The mutable tally behind {@link MethodLatency}, which is the derived
+ * report row. Held by the `protected` {@link LatencyCollector.durations}, so a
+ * subclass recording its own samples has to name it.
+ */
+export interface MethodLatencyTally {
    /** Retained durations for percentile estimation; capped in ring-buffer mode. Order is irrelevant (report sorts). */
    readonly samples: number[];
    /** Next slot to overwrite once the ring buffer is full (ring-buffer mode only). */
@@ -119,7 +124,9 @@ function percentile(sortedAscending: readonly number[], percent: number): number
  * deterministic on a fake clock.
  */
 export class LatencyCollector {
-   protected readonly durations = new Map<string, MethodAccumulator>();
+   /** One tally per method name. Emptied by {@link reset}. */
+   protected readonly durations = new Map<string, MethodLatencyTally>();
+   /** Restarted by {@link reset}. Its reading is the report's `windowMs`. */
    protected window: Stopwatch;
 
    constructor(

package/src/logger.ts

@@ -24,6 +24,7 @@ export const LEVEL_LABELS: Record<LogLevel, string> = {
 /** 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: LogThreshold = 'info';
+let fileLevel: LogThreshold | undefined;
 
 /**
  * Cross-side public logger contract. Every consumer of the framework — browser
@@ -38,15 +39,15 @@ let currentLevel: LogThreshold = 'info';
  * 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;
@@ -93,12 +94,32 @@ export namespace Logger {
       return currentLevel;
    }
    /**
-    * 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.
+    */
+   export function setFileLevel(level: LogThreshold | undefined): void {
+      fileLevel = level;
+   }
+   /** Read the log file's own threshold, `undefined` while it follows {@link getLevel}. */
+   export function getFileLevel(): LogThreshold | undefined {
+      return fileLevel;
+   }
+   /**
+    * 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())`.
     */
    export function isLevelEnabled(level: LogLevel): boolean {
-      return LEVEL_ORDER[level] <= LEVEL_ORDER[currentLevel];
+      return LEVEL_ORDER[level] <= Math.max(LEVEL_ORDER[currentLevel], fileLevel ? LEVEL_ORDER[fileLevel] : 0);
    }
    /**
     * Whether a message at `threshold` would be emitted: `false` for `'off'`,
@@ -134,8 +155,23 @@ export function parseLogLevel(value: unknown): LogThreshold | undefined {
  * instead of duplicating the literal string.
  */
 export 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 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 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 const DEFAULT_CPU_PROFILE_FILE_ENV = 'HYDRANIUM_CPU_PROFILE_FILE';
 
 /**
  * Human-readable formatting helpers used in log lines and diagnostic output.

package/src/messages/index.ts

@@ -25,8 +25,17 @@
 
 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,

package/src/messages/primitives.ts

@@ -162,11 +162,67 @@ export function messageError<S extends string>(
 }
 
 /**
- * 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 function renderFrameworkMessage(message: ResolvedMessage, translations?: Record<string, string>): string {
+export type MessageCatalogue = Readonly<Record<string, string>>;
+
+export 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.
+    */
+   export function merge(...catalogues: ReadonlyArray<MessageCatalogue | undefined>): MessageCatalogue | undefined {
+      const present = catalogues.filter((catalogue): catalogue is MessageCatalogue => catalogue !== undefined);
+      if (present.length <= 1) {
+         return present[0];
+      }
+      return Object.assign({}, ...present) as MessageCatalogue;
+   }
+}
+
+/**
+ * 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 function renderFrameworkMessage(message: ResolvedMessage, translations?: MessageCatalogue): string {
    const template = translations?.[message.code];
    return template ? interpolate(template, message.params) : message.text;
 }
@@ -180,9 +236,77 @@ export function resolvedFromResponseError(error: ResponseError<unknown>): Resolv
  * 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 function describeError(error: unknown): string {
-   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.
+ */
+export function describeErrorWithStack(error: unknown): string {
+   // A cause chain may loop back on itself.
+   return describeChain(error, new Set());
+}
+
+function describeChain(error: unknown, seen: Set<unknown>): string {
+   const lines: string[] = [];
+   let current: unknown = 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: unknown[] = 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: Error): string {
+   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: unknown, select: () => unknown): string {
+   try {
+      return String(select());
+   } catch {
+      try {
+         return Object.prototype.toString.call(value);
+      } catch {
+         return `[${typeof value}]`;
+      }
+   }
 }
 
 /**