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

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{expectedVersion}, server is at v{actualVersion}'
+);
 
 /**
  * Application-specific JSON-RPC error code for {@link ConflictError}.
@@ -24,16 +38,16 @@ 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;
+   readonly expectedVersion: number;
    /** The server's current text-document version at the time of the throw. */
-   readonly actual: number;
+   readonly actualVersion: number;
 }
 
 /**
- * Thrown by `ModelService.update` / `ModelService.save` when the caller-
+ * Thrown by a client session's `update` / `save` when the caller-
  * supplied based-on version no longer matches the server's current text-
  * document version for the same URI — i.e. the snapshot the caller
  * authored against has been superseded by an intervening edit.
@@ -46,11 +60,9 @@ export interface ConflictErrorData {
  * `err.data` (the instance is reconstructed as a generic
  * `ResponseError`, so subclass getters / fields do not survive).
  *
- * Detection is opt-in via the optional `baseVersion` field on
- * `TransferUpdateArgs` / `TransferSaveArgs`; callers that omit the field get
- * no gating. This mirrors LSP's `OptionalVersionedTextDocumentIdentifier`
- * posture, so headless / CLI / batch tooling with no meaningful based-on
- * version can opt out explicitly.
+ * Detection is driven by the required `basedOn` field of every write
+ * request; a caller with no meaningful based-on version passes
+ * `'anything'` and gets no gating.
  *
  * Three reasonable adopter recovery strategies:
  *
@@ -64,18 +76,19 @@ export interface ConflictErrorData {
  * No auto-retry or auto-merge ships by default.
  */
 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
-      });
+   constructor(uri: string, expectedVersion: number, actualVersion: number) {
+      const params = { uri, expectedVersion, actualVersion };
+      // The identity rides alongside the typed payload rather than replacing
+      // it: `isConflictError`'s name check is surface an adopter may bind, so
+      // adding the identity widens the payload rather than reshaping it.
+      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
       // transpilation targets; that resets us to ResponseError, hiding the
       // ConflictError-specific getters. Restore the prototype here so
-      // `err.uri` / `.expected` / `.actual` resolve through this class.
+      // `err.uri` / `.expectedVersion` / `.actualVersion` resolve through this
+      // class.
       Object.setPrototypeOf(this, ConflictError.prototype);
    }
 
@@ -83,13 +96,134 @@ export class ConflictError extends ResponseError<ConflictErrorData> {
       return this.data!.uri;
    }
 
-   get expected(): number {
-      return this.data!.expected;
+   /**
+    * The based-on version the caller authored against.
+    *
+    * Must not be renamed to `expected`, nor its sibling to `actual`: a test
+    * reporter reads an error carrying both as an assertion failure, and
+    * vitest's formatter then ASSIGNS to them, which throws on an accessor and
+    * replaces the real failure with a `TypeError`.
+    */
+   get expectedVersion(): number {
+      return this.data!.expectedVersion;
    }
 
-   get actual(): number {
-      return this.data!.actual;
+   /** The server's version at the time of the throw. Not `actual` — see {@link expectedVersion}. */
+   get actualVersion(): number {
+      return this.data!.actualVersion;
+   }
+}
+
+/**
+ * JSON-RPC code for {@link SessionClosedError}, beside {@link CONFLICT_ERROR_CODE}
+ * and for the same reason: the code survives reconstruction, the class does not.
+ */
+export const SESSION_CLOSED_ERROR_CODE = 1004;
+/** JSON-RPC code for {@link DocumentNotOpenError}. */
+export const DOCUMENT_NOT_OPEN_ERROR_CODE = 1005;
+/** JSON-RPC code for {@link DuplicateClientIdError}. */
+export const DUPLICATE_CLIENT_ID_ERROR_CODE = 1006;
+
+/**
+ * The catalogue declaration behind {@link SessionClosedError}'s default
+ * sentence. It names no client id: the sentence can reach an end user, and the
+ * id stays in {@link SessionClosedErrorData.clientId} for whoever needs it.
+ */
+export const SESSION_CLOSED = defineMessage('hydranium/protocol/session-closed', 'The editing session has ended.');
+
+/** Structured payload carried in {@link SessionClosedError.data}. */
+export interface SessionClosedErrorData extends HydraniumMessageData {
+   readonly clientId: string;
+}
+
+/**
+ * Thrown by every call on a client session after it ended, and by an open that
+ * was still in flight when its session ended: by the server for its sessions,
+ * and by a client-side `DataSession` once disposed, so a caller handles both
+ * the same way. A caller recognises it with {@link isSessionClosedError}, never
+ * by its sentence.
+ */
+export class SessionClosedError extends ResponseError<SessionClosedErrorData> {
+   /**
+    * `message` replaces the default English, for a caller that knows more than
+    * that the session is gone. The identity stays {@link SESSION_CLOSED}'s, so a
+    * translating renderer renders the catalogue sentence in its place.
+    */
+   constructor(clientId: string, message = SESSION_CLOSED.format()) {
+      super(SESSION_CLOSED_ERROR_CODE, message, { clientId, ...messageData(SESSION_CLOSED) });
+      this.name = 'SessionClosedError';
+      // `ResponseError` resets the prototype to its own; see `ConflictError`.
+      Object.setPrototypeOf(this, SessionClosedError.prototype);
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * Thrown when a client session writes a document it does not have open.
+ *
+ * A session writes only what it has open, so this is the answer both to a write
+ * that never opened and to one whose open was closed underneath it — by the
+ * session itself, or by the document being deleted.
+ */
+export class DocumentNotOpenError extends ResponseError<{ readonly uri: string; readonly clientId: string }> {
+   constructor(uri: string, clientId: string) {
+      super(DOCUMENT_NOT_OPEN_ERROR_CODE, `Document ${uri} is not open in client session ${clientId}`, { uri, clientId });
+      this.name = 'DocumentNotOpenError';
+      Object.setPrototypeOf(this, DocumentNotOpenError.prototype);
    }
+
+   get uri(): string {
+      return this.data!.uri;
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * Thrown when a client session is started under an id that is already live in
+ * the process, or that the framework reserves for itself.
+ *
+ * Ids are unique process-wide because the id is also the author label on every
+ * version and the key a client recognises its own echoes by; two participants
+ * sharing one would each take the other's writes for their own.
+ */
+export class DuplicateClientIdError extends ResponseError<{ readonly clientId: string }> {
+   constructor(clientId: string) {
+      super(DUPLICATE_CLIENT_ID_ERROR_CODE, `Client id ${clientId} is already in use`, { clientId });
+      this.name = 'DuplicateClientIdError';
+      Object.setPrototypeOf(this, DuplicateClientIdError.prototype);
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * Whether `error` is a {@link SessionClosedError}: by name in-process, by code
+ * after an RPC, where it arrives as a plain `ResponseError`.
+ */
+export function isSessionClosedError(error: unknown): error is SessionClosedError {
+   return hasErrorIdentity(error, 'SessionClosedError', SESSION_CLOSED_ERROR_CODE);
+}
+
+/** Whether `error` is a {@link DocumentNotOpenError}; see {@link isSessionClosedError}. */
+export function isDocumentNotOpenError(error: unknown): error is DocumentNotOpenError {
+   return hasErrorIdentity(error, 'DocumentNotOpenError', DOCUMENT_NOT_OPEN_ERROR_CODE);
+}
+
+/** Whether `error` is a {@link DuplicateClientIdError}; see {@link isSessionClosedError}. */
+export function isDuplicateClientIdError(error: unknown): error is DuplicateClientIdError {
+   return hasErrorIdentity(error, 'DuplicateClientIdError', DUPLICATE_CLIENT_ID_ERROR_CODE);
+}
+
+function hasErrorIdentity(error: unknown, name: string, code: number): boolean {
+   return error instanceof Error && (error.name === name || (error as Partial<ResponseError<unknown>>).code === code);
 }
 
 /** Marker substring present in every {@link ConflictError} message, used by

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

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * 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 {
+   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 {
+   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

@@ -16,14 +16,20 @@
 
 export * from './abstract-logger';
 export * from './client';
+export * from './client-ids';
 export * from './clock';
 export * from './data';
 export * from './browser-runtime';
 export * from './debouncer';
+export * from './glsp-save-model-actions';
 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/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,7 @@ function percentile(sortedAscending: readonly number[], percent: number): number
  * deterministic on a fake clock.
  */
 export class LatencyCollector {
-   protected readonly durations = new Map<string, MethodAccumulator>();
+   protected readonly durations = new Map<string, MethodLatencyTally>();
    protected window: Stopwatch;
 
    constructor(

package/src/messages/index.ts

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * 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 { SESSION_CLOSED, STALE_BASED_UPDATE } from '../errors';
+export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
+export { 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';

package/src/messages/primitives.ts

@@ -0,0 +1,271 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { ResponseError } from 'vscode-jsonrpc';
+
+/**
+ * The framework externalizes user-facing strings and SELECTS no locale: it
+ * relays the one its client declared and renders with whatever templates the
+ * adopter installed, defaulting to its English. Every such string carries a
+ * stable code beside that English, and exactly one side renders it — the side
+ * that knows the reading user's language.
+ *
+ * Which side that is depends on the message, not on the package. A server
+ * message is rendered by the server, at the one seam every carrier passes
+ * through, in the locale it was handed at init. A message the client tier raises
+ * is rendered there, because those fire when the server is unreachable. Nothing
+ * is rendered twice: two renders of one sentence are two authorities over it,
+ * and they diverge on the first reword.
+ *
+ * Codes are `hydranium/<unscoped-package>/<name>`. The package segment locates
+ * the declaration, so a message is declared in the package that raises it and a
+ * code never names a package it does not live in. `.` and `:` are forbidden in a
+ * segment: they are i18next's default key and namespace separators, where either
+ * silently becomes a nested lookup that misses.
+ */
+export type MessageParams = Readonly<Record<string, string | number>>;
+
+type Placeholder<S extends string> = S extends `${string}{${infer Name}}${infer Rest}` ? Name | Placeholder<Rest> : never;
+
+export type ParamsOf<S extends string> = [Placeholder<S>] extends [never]
+   ? Record<never, never>
+   : Readonly<Record<Placeholder<S>, string | number>>;
+
+/** Required exactly when the text has placeholders, absent when it does not. */
+export type ParamsArg<S extends string> = [Placeholder<S>] extends [never] ? [] : [params: ParamsOf<S>];
+
+/**
+ * Rejects a text argument already widened to `string`. Load-bearing rather than
+ * defensive: the whole compile-time guarantee is conditional on `S` inferring a
+ * literal, and for a concatenated or pre-widened text the placeholder set
+ * silently becomes empty, `format()` accepts no arguments, and the missing
+ * substitution surfaces only at runtime.
+ */
+export type LiteralText<S extends string> = string extends S ? never : S;
+
+export interface MessageDefinition<S extends string> {
+   readonly code: string;
+   readonly text: S;
+   format(...args: ParamsArg<S>): string;
+}
+
+/**
+ * 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.
+ */
+export function defineMessage<S extends string>(code: string, text: LiteralText<S>): MessageDefinition<S> {
+   const literal = text as S;
+   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.
+ */
+export function interpolate(template: string, params: MessageParams): string {
+   // 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 as Record<string, string | number | undefined> | undefined;
+   return template.replace(PLACEHOLDER, (match, key: string) => {
+      const value = lookup?.[key];
+      return value === undefined ? match : String(value);
+   });
+}
+
+export interface MessageIdentity {
+   readonly code: string;
+   readonly params: MessageParams;
+}
+
+/**
+ * Envelope for a protocol `data` field. Namespaced under one key so it co-exists
+ * with a carrier's own `data` conventions rather than occupying `data` itself.
+ */
+export interface HydraniumMessageData {
+   readonly hydranium: MessageIdentity;
+}
+
+/** An identity plus its resolved English — everything a renderer needs, on any carrier. */
+export interface ResolvedMessage extends MessageIdentity {
+   readonly text: string;
+}
+
+export function messageData<S extends string>(message: MessageDefinition<S>, ...args: ParamsArg<S>): HydraniumMessageData {
+   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.
+ */
+export function resolve<S extends string>(message: MessageDefinition<S>, ...args: ParamsArg<S>): ResolvedMessage {
+   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.
+ */
+export function hasMessageIdentity(data: unknown): data is HydraniumMessageData {
+   if (typeof data !== 'object' || data === null || Array.isArray(data) || !('hydranium' in data)) {
+      return false;
+   }
+   const identity = (data as { hydranium: unknown }).hydranium;
+   if (typeof identity !== 'object' || identity === null || Array.isArray(identity)) {
+      return false;
+   }
+   const candidate = identity as Partial<MessageIdentity>;
+   return typeof candidate.code === 'string' && typeof candidate.params === 'object' && candidate.params !== null;
+}
+
+/**
+ * A type alias rather than a subclass. Only `code`, `message` and `data` cross
+ * the wire, so a subclass buys nothing there: `instanceof` does not survive
+ * reconstruction, and the subclass costs an `Object.setPrototypeOf` in every
+ * constructor purely to undo what `ResponseError`'s own constructor does.
+ */
+export type HydraniumResponseError = ResponseError<HydraniumMessageData>;
+
+/**
+ * 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.
+ */
+export function messageError<S extends string>(
+   code: number,
+   message: MessageDefinition<S>,
+   ...params: ParamsArg<S>
+): HydraniumResponseError {
+   return new ResponseError(code, message.format(...params), messageData(message, ...params));
+}
+
+/**
+ * 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 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;
+}
+
+export function resolvedFromResponseError(error: ResponseError<unknown>): ResolvedMessage | undefined {
+   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.
+ */
+export function describeError(error: unknown): string {
+   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.
+ */
+export function isMessageDeclaration(value: unknown): value is MessageDefinition<string> {
+   const candidate = value as { code?: unknown; text?: unknown; format?: unknown } | null;
+   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.
+ */
+export function collectMessages(barrel: object): MessageDefinition<string>[] {
+   return (Object.values(barrel) as unknown[]).filter(isMessageDeclaration);
+}