@hydranium/core 1.0.0-next.30 → 1.0.0-next.32

package/src/langium/validation/document-validator.ts

@@ -7,10 +7,20 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer, TransferDiagnostic } from '@hydranium/protocol';
+import {
+   defineMessage,
+   describeError,
+   messageData,
+   type LogThreshold,
+   type MaybeObservableValue,
+   ObservableValue,
+   type Tracer,
+   TransferDiagnostic
+} from '@hydranium/protocol';
 import {
    type AstNode,
    type AstNodeLocator,
+   type AstReflection,
    DefaultDocumentValidator,
    type DiagnosticInfo,
    type LangiumDocument,
@@ -48,6 +58,26 @@ export interface TransferLspDiagnostic extends Diagnostic {
    property?: string;
 }
 
+/**
+ * A reference resolved to nothing.
+ *
+ * **The English is byte-identical to Langium's `DefaultLinker.createLinkingError`
+ * sentence, and must stay so.** The identity is attached to a diagnostic Langium
+ * already worded, so a divergence here would silently change the text every
+ * adopter without a catalogue sees. {@link HydraniumDocumentValidator.processLinkingErrors}
+ * attaches it only when the two match exactly, which is also what keeps an
+ * adopter's own reworded linking error from being mislabelled as this one.
+ *
+ * It exists because this is the most-seen validation error in any language built
+ * on the framework, and Langium puts its own code in `data.code` rather than on
+ * `Diagnostic.code` — so without a framework identity every adopter wanting to
+ * render it has to special-case Langium's shape.
+ */
+export const UNRESOLVED_REFERENCE = defineMessage(
+   'hydranium/core/unresolved-reference',
+   "Could not resolve reference to {referenceType} named '{refText}'."
+);
+
 export interface DocumentValidatorOptions extends LogNameOptions {
    /**
     * Level at which the `validateDocument` timing line is emitted, or `'off'`
@@ -94,6 +124,7 @@ export interface DocumentValidatorOptions extends LogNameOptions {
 export class HydraniumDocumentValidator extends DefaultDocumentValidator {
    protected readonly tracer: Tracer;
    protected readonly astNodeLocator: AstNodeLocator;
+   protected readonly reflection: AstReflection;
    protected readonly logLevel: ObservableValue<LogThreshold>;
    protected readonly logAfterMs: ObservableValue<number>;
    protected readonly validateVirtualDocuments: ObservableValue<boolean>;
@@ -103,6 +134,7 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       super(services);
       this.tracer = services.shared.Tracer.for(options.logName ?? 'DocumentValidator').trace('instantiated');
       this.astNodeLocator = services.workspace.AstNodeLocator;
+      this.reflection = services.shared.AstReflection;
       this.logLevel = ObservableValue.from(options.logLevel ?? 'debug');
       this.logAfterMs = ObservableValue.from(options.logAfterMs ?? 20);
       this.validateVirtualDocuments = ObservableValue.from(options.validateVirtualDocuments ?? false);
@@ -157,6 +189,90 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       return !this.validateSyntheticNodes.value && isSyntheticNode(node);
    }
 
+   /**
+    * Langium's linking-error pass, plus the framework identity on each
+    * diagnostic it produced.
+    *
+    * Langium puts its own `linking-error` marker in `data.code` and leaves
+    * `Diagnostic.code` unset, so nothing identifies the message on a surface
+    * that drops `data` — which is every editor surface. This adds the framework
+    * identity to both `code` and `data.hydranium` while LEAVING `data.code` in
+    * place: `stopAfterLinkingErrors` and Langium's code-action dispatch both
+    * read it.
+    *
+    * **The identity is attached only when the message is the one
+    * {@link UNRESOLVED_REFERENCE} renders.** Two other sentences reach this
+    * list: the linker's exception form, raised when resolution itself throws,
+    * and whatever an adopter overriding `createLinkingError` chose. Labelling
+    * either would make a catalogue render the wrong sentence — and for the
+    * exception form it would discard the underlying cause. Comparing against
+    * the locally rendered English is what discriminates; there is no structural
+    * field that does.
+    */
+   protected override processLinkingErrors(document: LangiumDocument, diagnostics: Diagnostic[], options: ValidationOptions): void {
+      const from = diagnostics.length;
+      super.processLinkingErrors(document, diagnostics, options);
+      for (let index = from; index < diagnostics.length; index++) {
+         diagnostics[index] = this.identifyLinkingError(diagnostics[index]);
+      }
+   }
+
+   /**
+    * Add the {@link UNRESOLVED_REFERENCE} identity to one linking diagnostic,
+    * or return it untouched when its message is not the sentence that identity
+    * renders.
+    *
+    * `refText` comes from the `data` Langium populated; `referenceType` is not
+    * in it, so it is recovered the same way `createLinkingError` produced it —
+    * through the reflection, from the container type and property.
+    */
+   protected identifyLinkingError(diagnostic: Diagnostic): Diagnostic {
+      const data = diagnostic.data as { code?: unknown; refText?: unknown; containerType?: unknown; property?: unknown } | undefined;
+      if (typeof data?.refText !== 'string' || typeof data.containerType !== 'string' || typeof data.property !== 'string') {
+         return diagnostic;
+      }
+      const referenceType = this.referenceTypeOf(data.containerType, data.property, data.refText);
+      if (referenceType === undefined) {
+         return diagnostic;
+      }
+      const params = { referenceType, refText: data.refText };
+      if (diagnostic.message !== UNRESOLVED_REFERENCE.format(params)) {
+         return diagnostic;
+      }
+      // Merged OVER Langium's data rather than replacing it, so `data.code`
+      // survives for the readers that switch on it.
+      return { ...diagnostic, code: UNRESOLVED_REFERENCE.code, data: { ...data, ...messageData(UNRESOLVED_REFERENCE, params) } };
+   }
+
+   /**
+    * The declared target type of the reference this diagnostic came from, or
+    * `undefined` when the reflection cannot name one.
+    *
+    * **The lookup can throw, and that is the reason this is a method rather
+    * than an inline call.** `AbstractAstReflection.getReferenceType` raises on
+    * an unknown container `$type` and on a property that is not a reference —
+    * and the linking error whose type it cannot name is the one most likely to
+    * reach here, because `DefaultLinker` catches its OWN failed lookup and
+    * turns it into the exception-form message. Rethrowing would take
+    * `validateDocument` with it, since Langium wraps `processLinkingErrors` in
+    * no try: a diagnostic Langium degraded gracefully would become a failed
+    * build. Declining is also the right answer on the merits — a reference
+    * whose type cannot be named is not the message
+    * {@link UNRESOLVED_REFERENCE} claims.
+    */
+   protected referenceTypeOf(containerType: string, property: string, refText: string): string | undefined {
+      try {
+         return this.reflection.getReferenceType({
+            container: { $type: containerType } as AstNode,
+            property,
+            reference: { $refText: refText }
+         } as Parameters<AstReflection['getReferenceType']>[0]);
+      } catch (err: unknown) {
+         this.tracer.debug(`cannot name the reference type for ${containerType}.${property}: ${describeError(err)}`);
+         return undefined;
+      }
+   }
+
    protected override toDiagnostic<N extends AstNode>(
       severity: ValidationSeverity,
       message: string,

package/src/langium/workspace/hydranium-workspace-manager.ts

@@ -9,9 +9,10 @@
 
 import { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
 import { DefaultWorkspaceManager, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver';
+import { type CancellationToken, type InitializeParams } from 'vscode-languageserver';
 import type { WorkspaceFolder } from 'vscode-languageserver-types';
 import { type LogNameOptions, resolveLogFilePlaceholder, toLogFileWorkspaceToken } from '../diagnostics/logger.js';
+import type { ServerLocale } from '../../locale/server-locale.js';
 import type { ProjectChangeEvent } from '../project/project-change-event.js';
 import type { ProjectManager } from '../project/project-manager.js';
 import type { ServerSharedServicesMinimal } from '../shared-services.js';
@@ -156,6 +157,8 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
    readonly workspaceInitialized: Promise<unknown> = this.workspaceInitializedDeferred.promise;
 
    protected readonly uriPolicy: DocumentUriPolicy;
+   /** Handed the client's locale at init; read by whoever renders in it. */
+   protected readonly serverLocale: ServerLocale;
    protected readonly writableFileSystemProvider: WritableFileSystemProvider;
    protected readonly additionalDocuments: Record<string, AdditionalDocumentContribution>;
    /** Registry consulted by {@link warnIfUnroutable} to check a seeded document routes. */
@@ -166,6 +169,7 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       this.projectManager = services.workspace.ProjectManager;
       this.projectManager.onProjectsChanged(event => this.onProjectsChanged(event));
       this.uriPolicy = services.workspace.DocumentUriPolicy;
+      this.serverLocale = services.ServerLocale;
       this.writableFileSystemProvider = services.workspace.FileSystemProvider;
       this.additionalDocuments = services.additionalDocuments;
       this.languageRegistry = services.ServiceRegistry;
@@ -360,6 +364,19 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       }
    }
 
+   /**
+    * Forward the locale the client declared, then Langium's own read of the
+    * params. `DefaultWorkspaceManager.initialize` reads `workspaceFolders`
+    * alone, so `params.locale` would otherwise be discarded — and this is the
+    * only place it arrives, which the headless init seams route through too.
+    */
+   override initialize(params: InitializeParams): void {
+      if (params.locale) {
+         this.serverLocale.accept(params.locale);
+      }
+      super.initialize(params);
+   }
+
    /**
     * Override of Langium's workspace setup to resolve / reject
     * {@link workspaceInitializedDeferred} once setup completes. Adopters with

package/src/langium/workspace/initialize-workspace.ts

@@ -18,6 +18,25 @@ import type { ServerSharedServicesMinimal } from '../shared-services.js';
 /** A workspace folder root accepted by the headless init seams: a filesystem path or a {@link URI}. */
 export type WorkspaceFolderInput = string | URI;
 
+/**
+ * Options for the headless init seams.
+ *
+ * **Optional, and the parameter is optional too**, so that no existing caller
+ * has to change to gain a field it does not set.
+ */
+export interface ProgrammaticInitOptions {
+   /**
+    * The locale to render user-facing server messages in — the headless
+    * equivalent of LSP `initialize`'s `locale`, for a head with no LSP
+    * connection (`startStdioServer`, the CLI subcommands, a test harness).
+    *
+    * Omitted means no locale, which the default renderer resolves as the
+    * framework's English. That is the correct answer for a headless tool: it
+    * has no reading user to have a language.
+    */
+   readonly locale?: string;
+}
+
 /**
  * Normalize the seam's flexible folder argument to LSP {@link WorkspaceFolder}s.
  * A `string` is resolved to an absolute filesystem path and wrapped as a
@@ -58,17 +77,25 @@ function toWorkspaceFolders(folders: WorkspaceFolderInput | ReadonlyArray<Worksp
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function initializeWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
    const workspaceFolders = toWorkspaceFolders(folders);
    const manager = services.workspace.WorkspaceManager;
-   // `initialize` records the folders (DefaultWorkspaceManager reads only this
+   // `locale` goes through the synthesized params rather than a direct
+   // `acceptLocale` call, so this seam and a real LSP `initialize` reach the
+   // slot by the SAME path — an adopter overriding the capture in
+   // `HydraniumWorkspaceManager.initialize` is honoured headlessly too, which a
+   // second write site here would silently bypass.
+   //
+   // `initialize` records the folders (DefaultWorkspaceManager reads only that
    // field); `initialized` runs `mutex.write(initializeWorkspace)` and resolves
    // once discovery + the init build settle, so awaiting it is the ready gate.
-   manager.initialize({ workspaceFolders } as InitializeParams);
+   manager.initialize({ workspaceFolders, locale: options.locale } as InitializeParams);
    await manager.initialized({} as InitializedParams);
 }
 
@@ -91,12 +118,14 @@ export async function initializeWorkspaceProgrammatically(
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function buildWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
-   await initializeWorkspaceProgrammatically(services, folders);
+   await initializeWorkspaceProgrammatically(services, folders, options);
    const documents = services.workspace.LangiumDocuments.all.toArray();
    await services.workspace.DocumentBuilder.build(documents, { validation: true });
 }

package/src/locale/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './server-locale.js';

package/src/locale/server-locale.ts

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * 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 type { Tracer } from '@hydranium/protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+
+/** Construction options for {@link ServerLocale}. */
+export type ServerLocaleOptions = LogNameOptions;
+
+/**
+ * The locale the server was handed at init, for whoever needs to render in the
+ * reading user's language. Held apart from the message renderer that reads it,
+ * so replacing the renderer cannot drop locale handling.
+ *
+ * A plain string in and out. A consumer that must react to a change rather than
+ * read the current value wraps this itself — nothing does today, and both real
+ * hosts respawn the server on a display-language switch.
+ */
+export class ServerLocale {
+   protected readonly tracer: Tracer;
+   protected current: string | undefined;
+
+   constructor(services: ServerSharedServicesMinimal, options: ServerLocaleOptions = {}) {
+      this.tracer = services.Tracer.for(options.logName ?? 'ServerLocale').trace('instantiated');
+   }
+
+   /** The locale, or `undefined` when no init supplied one — which means the framework's English. */
+   get value(): string | undefined {
+      return this.current;
+   }
+
+   /**
+    * Take the locale an init declared.
+    *
+    * **One locale per process, and the reason the OTHER heads need none of
+    * their own.** The data and GLSP heads publish a port over the LSP
+    * connection and are reached by forwarding a socket to it, so they are the
+    * same process as the LSP head that was handed this locale — there is no
+    * topology in which one of them serves a second frontend. The Theia backend
+    * is the case that would break it, and it holds no locale precisely because
+    * it serves every frontend at once; nothing there writes here.
+    *
+    * The framework accepts a locale and never sources one, and neither
+    * validates nor normalises the tag: rejecting an unfamiliar one would be
+    * selecting a locale.
+    *
+    * Override to ignore the argument, which is how a host pins a locale it
+    * already knows but has no LSP client to declare.
+    */
+   accept(locale: string): void {
+      this.current = locale;
+      this.tracer.debug(`locale set to '${locale}'`);
+   }
+}

package/src/messages/carriers.ts

@@ -16,7 +16,7 @@ import {
    type ResolvedMessage
 } from '@hydranium/protocol';
 import type { AstNode, DiagnosticData, DiagnosticInfo, Properties, ValidationAcceptor } from '@hydranium/langium';
-import type { Diagnostic } from 'vscode-languageserver-protocol';
+import { Diagnostic } from 'vscode-languageserver-protocol';
 
 /**
  * Raise a validation diagnostic from a declaration, so the call site never
@@ -52,17 +52,17 @@ export function acceptMessage<S extends string, N extends AstNode, P extends Pro
 }
 
 /**
- * Recover the identity from a published diagnostic, for a surface that renders
- * diagnostics itself.
+ * Recover the identity from a published diagnostic, for a surface that
+ * identifies or renders diagnostics itself.
  *
- * The `MarkupContent` narrowing is not padding: `Diagnostic.message` is
- * `string | MarkupContent` in LSP 3.17+ and this does not compile without it.
- * Only the string form is a resolved English sentence.
+ * `Diagnostic.message` is `string | MarkupContent` in LSP 3.17+, so the text
+ * comes from upstream's own `Diagnostic.getMessageString` rather than a
+ * hand-rolled narrowing — consuming the library in its style, and one fewer
+ * place restating the union.
  */
 export function resolvedFromDiagnostic(diagnostic: Diagnostic): ResolvedMessage | undefined {
    if (!hasMessageIdentity(diagnostic.data)) {
       return undefined;
    }
-   const text = typeof diagnostic.message === 'string' ? diagnostic.message : diagnostic.message.value;
-   return { ...diagnostic.data.hydranium, text };
+   return { ...diagnostic.data.hydranium, text: Diagnostic.getMessageString(diagnostic) };
 }

package/src/messages/index.ts

@@ -18,7 +18,10 @@
  */
 
 export * from './carriers.js';
+export * from './renderer.js';
 
+export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
 export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
+export { UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.js';
 export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
 export { NO_SUCH_FILE, NO_SUCH_PATH } from '../langium/workspace/in-memory-file-system-provider.js';

package/src/messages/renderer.ts

@@ -0,0 +1,184 @@
+/********************************************************************************
+ * 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 {
+   describeError,
+   renderFrameworkMessage,
+   resolve,
+   resolvedFromResponseError,
+   type MessageDefinition,
+   type ParamsArg,
+   type ResolvedMessage,
+   type Tracer
+} from '@hydranium/protocol';
+import { SimpleCache } from '@hydranium/langium';
+import type { ResponseError } from 'vscode-jsonrpc';
+import { Diagnostic } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import type { ServerLocale } from '../locale/server-locale.js';
+import { resolvedFromDiagnostic } from './carriers.js';
+
+/** Construction options for {@link ServerMessageRenderer}. */
+export type ServerMessageRendererOptions = LogNameOptions;
+
+/**
+ * Renders every user-facing message the server sends, in the locale the server
+ * was handed at init. The framework ships no catalogue, so its own behaviour is
+ * a pass-through.
+ *
+ * Adopters override {@link translationsFor}: the public render methods carry
+ * the no-throw contract, and the catalogue lookup they wrap is what can fail.
+ *
+ * Two render methods rather than one, because what is useful to an adopter is
+ * the carrier's structured fields and the two carriers have different ones. A
+ * single `render(text)` would force an adopter to match English prose, which
+ * breaks on the first Langium reword.
+ */
+export class ServerMessageRenderer {
+   protected readonly tracer: Tracer;
+   protected readonly serverLocale: ServerLocale;
+   /**
+    * {@link translationsFor}'s answer per locale, `undefined` answers included —
+    * a `SimpleCache` distinguishes "absent" from "cached as none", which matters
+    * because shipping no catalogue is the framework's own hot path.
+    *
+    * `SimpleCache` rather than Langium's `WorkspaceCache`: the eviction axis
+    * there is document change, and a catalogue does not depend on documents, so
+    * it would evict on every build AND put a `DocumentBuilder` dependency on a
+    * service the shared tier declares free of one. Nothing evicts this: the
+    * locale arrives once per process. A subclass whose catalogue can change
+    * clears it.
+    */
+   protected readonly catalogues = new SimpleCache<string | undefined, Record<string, string> | undefined>();
+
+   constructor(services: ServerSharedServicesMinimal, options: ServerMessageRendererOptions = {}) {
+      this.serverLocale = services.ServerLocale;
+      this.tracer = services.Tracer.for(options.logName ?? 'MessageRenderer').trace('instantiated');
+   }
+
+   /**
+    * The sentence to publish for `diagnostic`, replacing its current `message`.
+    * Sees lexer and parser errors too, which Langium pushes onto the document
+    * without routing them through `toDiagnostic`.
+    *
+    * **Must not throw**, which is why the guard is here and not at the call
+    * site: this runs inside the `Validated` phase, and Langium's
+    * `notifyDocumentPhase` rethrows anything that is not a cancellation — so an
+    * escaping error leaves the document AT `Validated` with the phase's
+    * listeners never run, and the client receives no diagnostics for that file.
+    * A subclass overriding this method takes that contract on itself.
+    */
+   renderDiagnostic(diagnostic: Diagnostic): string {
+      try {
+         const resolved = resolvedFromDiagnostic(diagnostic);
+         return resolved ? this.render(resolved) : Diagnostic.getMessageString(diagnostic);
+      } catch (err: unknown) {
+         this.reportFailure(err, 'a diagnostic');
+         return Diagnostic.getMessageString(diagnostic);
+      }
+   }
+
+   /**
+    * The sentence to send for `error`, replacing its current `message`. Same
+    * no-throw contract as {@link renderDiagnostic}: an escaping error replaces a
+    * typed rejection the caller can handle with one it cannot.
+    */
+   renderError(error: ResponseError<unknown>): string {
+      try {
+         const resolved = resolvedFromResponseError(error);
+         return resolved ? this.render(resolved) : error.message;
+      } catch (err: unknown) {
+         this.reportFailure(err, 'an RPC error');
+         return error.message;
+      }
+   }
+
+   /**
+    * The sentence for a declaration the caller holds directly, for a carrier
+    * with no slot to put an identity in.
+    *
+    * GLSP's action protocol is the case: every member of its message, status
+    * and reject actions is prose or an enum, so a code cannot travel and the
+    * raise site is the last place that still knows which message this is.
+    * Prefer {@link renderDiagnostic} / {@link renderError} wherever a carrier
+    * does hold the identity — they keep the render off the raise site, so an
+    * adopter's own messages ride the same one binding.
+    *
+    * Same no-throw contract as the carrier methods.
+    */
+   renderMessage<S extends string>(message: MessageDefinition<S>, ...params: ParamsArg<S>): string {
+      // `resolve` is inside the guard with the render, not before it: it calls
+      // the declaration's own `format`, which for an adopter declaration is
+      // arbitrary code, and a throw there would escape a method whose contract
+      // says it cannot.
+      let resolved: ResolvedMessage | undefined;
+      try {
+         resolved = resolve(message, ...params);
+         return this.render(resolved);
+      } catch (err: unknown) {
+         this.reportFailure(err, `the message '${message.code}'`);
+         // Unset only when `format` ITSELF threw, which leaves the
+         // uninterpolated template as the only text there is. A failed render
+         // still has the resolved English.
+         return resolved?.text ?? message.text;
+      }
+   }
+
+   /**
+    * The catalogue for the current locale, or `undefined` for none — the
+    * framework's answer, shipping none. Overriding this leaves every identity
+    * decision, every pass-through and the no-throw guard in place.
+    *
+    * **Called once per locale, not once per message**, so an override may load
+    * a file or build a map without that cost landing per diagnostic. The
+    * corollary is that a catalogue mutated in place afterwards is not seen;
+    * clear {@link catalogues} to invalidate.
+    *
+    * An adopter wanting Langium's own uncoded sentences instead matches
+    * `Diagnostic.data.code` from an overridden {@link renderDiagnostic}, never
+    * the sentence.
+    */
+   protected translationsFor(_locale: string | undefined): Record<string, string> | undefined {
+      return undefined;
+   }
+
+   /**
+    * Resolve one identity against the current locale's catalogue.
+    *
+    * Reads the locale per call. Copying it into a field at construction pins
+    * whatever was there before init ran, which is always `undefined` — services
+    * compose first.
+    *
+    * The catalogue behind it is memoized, because a workspace-wide validation
+    * renders once per diagnostic and the naive override — parse a JSON file,
+    * build a map — then pays that per diagnostic rather than per locale.
+    */
+   protected render(message: ResolvedMessage): string {
+      const locale = this.serverLocale.value;
+      return renderFrameworkMessage(
+         message,
+         this.catalogues.get(locale, () => this.translationsFor(locale))
+      );
+   }
+
+   /**
+    * Emit a failed render. Logged rather than swallowed: the fallback output is
+    * byte-identical to a correctly-configured default, so a throwing catalogue
+    * is otherwise invisible.
+    */
+   protected reportFailure(err: unknown, carrier: string): void {
+      this.tracer.error(this.formatRenderFailure(err, carrier));
+   }
+
+   /** Format the failed-render line. Override to name the adopter's catalogue entry. */
+   protected formatRenderFailure(err: unknown, carrier: string): string {
+      return `rendering ${carrier} failed; falling back to the server's own text. ${describeError(err)}`;
+   }
+}

package/src/testing/fake-document.ts

@@ -7,7 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { DocumentState, type AstNode, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { DocumentState, type AstNode, type AstReflection, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { buildAstNode } from '../langium/ast-extension/ast-node-builder.js';
 
 /**
  * Build a typed AST-node fixture for unit tests.
@@ -23,12 +24,29 @@ import { DocumentState, type AstNode, type LangiumDocument, UriUtils, type URI }
  * framework synthetic node, and marking it would change scope/index behaviour.
  * A test that wants a genuine synthetic node calls `markSynthetic` explicitly.
  *
+ * **Without a `reflection`, the fixture carries only what the test spells out**,
+ * which is a shape production never produces: a parsed or built node always has
+ * its grammar-declared containment arrays, so a fixture that omits one lets a
+ * test pass against an impossible node, and lets code that walks a list crash
+ * only under test. Pass the grammar's reflection whenever the type is a real
+ * one and the code under test reads a collection off it. Fixtures typed against
+ * ad-hoc names have no reflection to pass and keep the plain form.
+ *
  * @param node the node shape — `$type` is required; every other property is a
  *   value the test cares about (`$container`, cross-reference values, internal
- *   `_id` fields, …). The object is returned by reference, not copied.
+ *   `_id` fields, …).
+ * @param reflection when given, pre-fills the grammar's declared defaults the
+ *   same way {@link buildAstNode} does, and the result is a fresh object rather
+ *   than `node` itself. Omitted, `node` is returned by reference.
  */
-export function makeFakeAstNode<TAst extends AstNode = AstNode>(node: { $type: string } & Record<string, unknown>): TAst {
-   return node as unknown as TAst;
+export function makeFakeAstNode<TAst extends AstNode = AstNode>(
+   node: { $type: string } & Record<string, unknown>,
+   reflection?: AstReflection
+): TAst {
+   if (!reflection) {
+      return node as unknown as TAst;
+   }
+   return buildAstNode<TAst>(reflection, node.$type, node);
 }
 
 /**