@hydranium/core 1.0.0-next.18 → 1.0.0-next.181

package/src/langium/scope/hydranium-scope-provider.ts

@@ -24,7 +24,6 @@ import {
    type AstNodeLocator,
    AstUtils,
    DefaultScopeProvider,
-   type LangiumDocuments,
    MapScope,
    type ReferenceInfo,
    type Scope,
@@ -35,9 +34,11 @@ import {
    WorkspaceCache,
    stream
 } from '@hydranium/langium';
+import { buildAstNode } from '../ast-extension/ast-node-builder.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumLanguageServices } from '../language-module.js';
 import { type NameProvider } from '../naming/name-provider.js';
+import { type HydraniumDocumentRegistry } from '../workspace/langium-documents.js';
 import { type ScopeExtensionService } from './scope-extension-service.js';
 import { isTieredDescription } from './scoped-ast-node-description.js';
 
@@ -143,7 +144,7 @@ export interface ScopeContext {
  * `reference-candidate-provider.ts` module.
  */
 export class HydraniumScopeProvider extends DefaultScopeProvider {
-   protected readonly langiumDocuments: LangiumDocuments;
+   protected readonly langiumDocuments: HydraniumDocumentRegistry;
    protected readonly astNodeLocator: AstNodeLocator;
    protected readonly scopeExtensionService: ScopeExtensionService;
    protected readonly options: HydraniumScopeProviderOptions;
@@ -182,6 +183,26 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
       this.tracer = services.shared.Tracer.for(options.logName ?? 'ScopeProvider').trace('instantiated');
    }
 
+   /**
+    * Drop every cached scope — the framework's project-tier chain and the
+    * inherited global scope it is filtered from.
+    *
+    * **Called from outside the class**, by the build pipeline once the batch is
+    * re-indexed. The caches' own eviction does not cover this:
+    * `DocumentBuilder.onUpdate` fires after the build has taken every changed
+    * document's symbols out of the index and before it puts them back, so a
+    * scope built in that gap denies those symbols exist and every document the
+    * same build links afterwards resolves against it.
+    *
+    * Both go together because the second is derived from the first: clearing
+    * only {@link scopeCache} refills it from a stale `globalScopeCache`, and
+    * clearing only `globalScopeCache` leaves the filtered copy standing.
+    */
+   clearScopeCaches(): void {
+      this.scopeCache.clear();
+      this.globalScopeCache.clear();
+   }
+
    /**
     * Framework-owned assembly seam. **Adopters do NOT override this** —
     * override {@link createGlobalScope} instead. This method layers the
@@ -469,12 +490,13 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * Convert a protocol-layer {@link ReferenceContext} into a Langium
     * {@link ReferenceInfo} the rest of the scope/linking machinery accepts.
     *
-    * Walks `syntheticPath` by FABRICATING a type-only stub per step, so a
-    * scope can be queried for an element that does not exist yet — which is
-    * what synthetic paths are for. The stubs carry no children, so a caller
-    * that needs to read a collection off the leaf wants
-    * {@link resolveReferenceSource} instead, which walks the same path into
-    * the real tree.
+    * Walks `syntheticPath` by FABRICATING a stub per step, so a scope can be
+    * queried for an element that does not exist yet — which is what synthetic
+    * paths are for. A stub carries the grammar's declared defaults and nothing
+    * else, so its containment lists are present but EMPTY: a caller that needs
+    * to read a populated collection off the leaf wants
+    * {@link resolveReferenceSource} instead, which walks the same path into the
+    * real tree.
     *
     * Throws if the context references an unresolvable source; callers
     * that prefer a soft failure should catch and fall back to
@@ -486,16 +508,15 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
          throw new Error('Invalid reference source');
       }
       for (const step of ctx.syntheticPath ?? []) {
-         container = {
+         container = buildAstNode(this.services.shared.AstReflection, step.type, {
             $container: container,
             $containerProperty: step.containerProperty,
             // Part of Langium's own container contract, so a stub that omits it
             // is an under-specified node: anything reading position off the
             // chain (a key provider, an adopter scope extension) sees
             // `undefined` where the caller named a slot.
-            $containerIndex: step.index,
-            $type: step.type
-         };
+            $containerIndex: step.index
+         });
       }
       return {
          reference: { $refText: '', ref: undefined },
@@ -586,18 +607,35 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
-    * Build a transient AST-node stub for a {@link SyntheticSource} request.
-    * Default: looks up the document via `LangiumDocuments` and uses its parse
-    * root as the container; returns `undefined` if the document isn't loaded.
-    * Consumers that need to materialise an empty document on demand (e.g.
-    * to query the scope before a file exists) override this.
+    * Build a transient AST-node stub for a {@link SyntheticSource} request: a
+    * node of the requested type, contained by the document at `source.uri`.
+    *
+    * **The container is materialised when no document is loaded there**, which
+    * is the case the source type exists for — a `SyntheticSource` names a node
+    * that does not exist yet, and the create-element flow asks at the FOLDER
+    * the file is about to be written into. Abstaining there would answer an
+    * empty candidate list, which a client cannot tell from "nothing matches".
+    *
+    * The stand-in parses under THIS provider's grammar, because a folder URI
+    * carries no extension for the routing ladder to end on and this provider is
+    * bound per grammar. Reaching for `createEmptyDocument(uri)` without the id
+    * instead fails inside the parse, on an empty extension rather than on the
+    * URI.
+    *
+    * The materialised document is unregistered and transient; see
+    * `createEmptyDocument`. Overriding is still open to a consumer whose
+    * "container" is an inner element rather than the parse root, or one that
+    * deliberately declines to answer for an absent document.
+    *
+    * The stub carries the grammar's declared defaults, so an extension reading a
+    * containment list off it sees an empty array rather than `undefined`.
     */
    protected resolveSyntheticSource(source: SyntheticSource): AstNode | undefined {
-      const document = this.langiumDocuments.getDocument(UriUtils.toUri(source.uri));
-      if (!document) {
-         return undefined;
-      }
-      return { $type: source.type, $container: document.parseResult.value };
+      const uri = UriUtils.toUri(source.uri);
+      const document =
+         this.langiumDocuments.getDocument(uri) ??
+         this.langiumDocuments.createEmptyDocument(uri, this.services.LanguageMetaData.languageId);
+      return buildAstNode(this.services.shared.AstReflection, source.type, { $container: document.parseResult.value });
    }
 
    /**

package/src/langium/serialization/abstract-serializer.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { isPromiseLike, type MaybePromise, type Tracer, type TransferElement } from '@hydranium/protocol';
+import { type MaybePromise, type Tracer, type TransferElement } from '@hydranium/protocol';
 import { type AstNode, type AstReflection, type GenericAstNode, isAstNode } from '@hydranium/langium';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumLanguageServices } from '../language-module.js';
@@ -66,16 +66,6 @@ export interface AbstractSerializerOptions extends LogNameOptions {
     * the extra property carries a value.
     */
    readonly referenceWrapperTypes?: ReadonlyMap<string, string>;
-   /**
-    * Whether {@link AbstractSerializer.serializeAst} trims trailing whitespace
-    * from the final output (leading whitespace is always trimmed). Defaults to
-    * `true` — the conventional "no trailing blank lines" document shape. Set to
-    * `false` for grammars whose values may legitimately END the document with
-    * blank lines that must survive a round-trip — e.g. a multi-line block-scalar
-    * property (see `YamlSerializerOptions.blockScalarProperties`),
-    * where a trailing-trim would silently eat user-typed blank lines.
-    */
-   readonly trimTrailingWhitespace?: boolean;
 }
 
 /**
@@ -139,29 +129,20 @@ export abstract class AbstractSerializer<
     * Entry point for AST-shape inputs. Typically the grammar root, but any
     * AST node works — the walker is recursive and shape-agnostic.
     *
-    * Preserves the sync fast path: when every subclass override and every
-    * adopter hook is sync, the return is a bare `string` (no Promise
-    * allocation, no microtask). The async branch fires only if at least one
-    * recursive `serializeNode` call resolved to a Promise.
+    * **Emits the model and nothing else — do not trim here.** Trailing
+    * whitespace belongs to the author, and a write path holding the prior
+    * document restores it from there; trimming at this end deletes it before
+    * that restore sees it. A serializer has no prior document to consult, so it
+    * cannot tell a deliberate blank line from an accidental one.
+    *
+    * **Nothing trims what a subclass emits**, at either end. Emitting leading
+    * whitespace therefore puts it in the file, where no write path removes it.
+    *
+    * Returns whatever `serializeNode` returns, so a fully sync subclass keeps a
+    * bare `string` with no promise allocation.
     */
    serializeAst(model: TAst): MaybePromise<string> {
-      const result = this.serializeNode(model, 0);
-      if (isPromiseLike(result)) {
-         return result.then(text => this.trimSerialized(text));
-      }
-      return this.trimSerialized(result);
-   }
-
-   /**
-    * Trim the final serialized output. Leading whitespace is always removed;
-    * trailing whitespace is removed unless {@link AbstractSerializerOptions.trimTrailingWhitespace}
-    * is `false` (which preserves document-ending blank lines, e.g. inside a block scalar).
-    */
-   protected trimSerialized(text: string | undefined): string {
-      if (text === undefined) {
-         return '';
-      }
-      return this.options.trimTrailingWhitespace === false ? text.trimStart() : text.trim();
+      return this.serializeNode(model, 0);
    }
 
    /**

package/src/langium/service-registry.ts

@@ -209,6 +209,19 @@ export class ExtendedServiceRegistry<
       return super.getServices(arg);
    }
 
+   /**
+    * Every registered language's services, typed as `TServices` like the
+    * lookups here rather than as Langium's base shape, so a sweep of the whole
+    * set reaches what a URI or a typed handle would have given it.
+    *
+    * The cast is sound because {@link register} is the only way a language
+    * enters and takes `TServices`; the inherited accessor is typed to Langium's
+    * base, which is the only reason one is needed.
+    */
+   override get all(): readonly TServices[] {
+      return super.all as readonly TServices[];
+   }
+
    /**
     * Lookup by anything that identifies a document — an AST node (routed by
     * the document it lives in), a `URI`, or a URI string. `undefined` when the
@@ -255,9 +268,13 @@ export class ExtendedServiceRegistry<
     * inherited Langium semantics, which throws on miss). Used for
     * dynamically-routed lookups where the language id comes from
     * external input.
+    *
+    * The cast is sound because {@link register} is the only way a language
+    * enters and takes `TServices`; `languageIdMap` is inherited and typed to
+    * Langium's base, which is the only reason one is needed.
     */
-   getServicesById(languageId: string): LangiumCoreServices | undefined {
-      return this.languageIdMap.get(languageId);
+   getServicesById(languageId: string): TServices | undefined {
+      return this.languageIdMap.get(languageId) as TServices | undefined;
    }
 
    /**

package/src/langium/shared-services.ts

@@ -9,8 +9,11 @@
 
 import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
+import type { ServerLocale } from '../locale/server-locale.js';
+import type { MessageRenderer } from '../messages/renderer.js';
 import type { SelfSaveRegistry } from '../documents/self-save-registry.js';
 import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import type { HydraniumDocumentRegistry } from './workspace/langium-documents.js';
 import type { BuildPhasePassService } from './build-phase-pass/build-phase-pass-service.js';
 import type { CstResidencyService } from './residency/cst-residency-service.js';
 import type { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
@@ -27,8 +30,9 @@ import type { AdditionalDocumentContribution } from './workspace/additional-docu
  * framework additions that other framework services consume: the dedicated
  * {@link Clock}, {@link Logger} and {@link Tracer} top-level slots (injectable
  * time source, emission-only logger, and the measure-and-emit tracer composed
- * from the other two), the {@link AdditionalDocumentContribution} group, an
- * {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
+ * from the other two), the {@link AdditionalDocumentContribution} group, the
+ * {@link MessageRenderer} and the {@link ServerLocale} it renders in,
+ * an {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
  * provider plus {@link HydraniumWorkspaceManager}, {@link ProjectManager},
  * {@link SelfSaveRegistry}, {@link BuildPipelineIntegration},
  * {@link BuildPhasePassService}, {@link CstResidencyService} and
@@ -57,6 +61,14 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
     * adopters deep-merge contributions that seed built-in / stdlib documents.
     */
    additionalDocuments: Record<string, AdditionalDocumentContribution>;
+   /**
+    * Renders each user-facing message once, before the server sends it. On the
+    * shared tier with no workspace dependency, because all three heads'
+    * messages pass through it.
+    */
+   MessageRenderer: MessageRenderer;
+   /** The locale an init handed the server, for whoever renders in it. */
+   ServerLocale: ServerLocale;
    /**
     * Narrows Langium's base `ServiceRegistry` slot to the framework impl the
     * framework always binds, so the abstaining lookups — `getServicesFor`
@@ -75,6 +87,11 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
       // framework always binds, so `wsRelativePath` and the folder-walk are
       // reachable from the minimal surface without a cast.
       WorkspaceManager: HydraniumWorkspaceManager;
+      // Same, for the registry: the framework always binds
+      // `HydraniumLangiumDocuments`, and `createEmptyDocument` is reachable
+      // only through this narrowing — a scope provider querying a URI before
+      // the file exists is the caller that needs it.
+      /* override */ LangiumDocuments: HydraniumDocumentRegistry;
       ProjectManager: ProjectManager<TProject>;
       SelfSaveRegistry: SelfSaveRegistry;
       BuildPipelineIntegration: BuildPipelineIntegration;

package/src/langium/transfer/transfer-encoder.ts

@@ -8,10 +8,11 @@
  ********************************************************************************/
 
 import {
+   hasMessageIdentity,
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
-   type TransferDocument,
+   TransferDocument,
    type TransferTypeFor
 } from '@hydranium/protocol';
 import { AstUtils, type AstNode, DocumentCache, DocumentState, isAstNode, isReference, type LangiumDocument } from '@hydranium/langium';
@@ -19,7 +20,7 @@ import { Diagnostic, DiagnosticSeverity } from 'vscode-languageserver-protocol';
 import { type AstDocument } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
-import { type TransferLspDiagnostic } from '../validation/document-validator.js';
+import { type AstDiagnostic } from '../validation/document-validator.js';
 
 /**
  * Which set of properties {@link TransferEncoder.toTransfer} emits.
@@ -28,11 +29,13 @@ import { type TransferLspDiagnostic } from '../validation/document-validator.js'
  *   including AST-extension-derived computed scalars and synthetic child
  *   mirrors. This is the wire shape clients consume, and the default.
  * - `'grammar'` — only the grammar-declared properties, per
- *   `AstReflection.getTypeMetaData($type).properties`. Excludes every
- *   computed / synthetic property by construction (no naming convention,
- *   no registration). Yields the authored state a serializer round-trips —
- *   a diffable, acyclic baseline for field-level recording / forward-write
- *   reconcile.
+ *   `AstReflection.getTypeMetaData($type).properties`, each carrying the
+ *   node's own authored value. Excludes every computed / synthetic property
+ *   by construction (no naming convention, no registration) and bypasses the
+ *   `resolvePropertyValue` substitution hook, so neither a computed KEY nor a
+ *   computed VALUE can reach this shape. Yields the authored state a
+ *   serializer round-trips — a diffable, acyclic baseline for field-level
+ *   recording / forward-write reconcile.
  */
 export type TransferMode = 'full' | 'grammar';
 
@@ -79,6 +82,37 @@ export interface TransferEnvelopeSource<TDiagnostic> {
    readonly diagnostics: readonly (TDiagnostic | Diagnostic)[];
 }
 
+/**
+ * The AST→transfer contract a DI slot holds, implemented by
+ * {@link DefaultTransferEncoder}.
+ *
+ * **This is an interface and not the class, and that is load-bearing.** A class
+ * in a slot drags its `protected` members into every assignability check, which
+ * TypeScript compares NOMINALLY — so the slot type could not be satisfied by a
+ * subclass declared against a second physical copy of this package, and an
+ * adopter narrowing the slot had to intersect with the framework's declaration
+ * rather than replace it, leaving method resolution dependent on declaration
+ * order. An interface has no protected members and is compared structurally, so
+ * neither applies.
+ *
+ * **The transfer returns are the structural base ({@link TransferElement}), not
+ * the per-grammar overlay.** The overlay cannot parameterise this contract:
+ * `TransferTypeFor` reaches `keyof TTransferMap`, which makes that parameter
+ * measured-INVARIANT, and invariant parameters relate only when their arguments
+ * are mutually assignable — so a map-parameterised contract admits no adopter
+ * instantiation at all. Heads read this contract and do not know adopter maps;
+ * an adopter recovers the precise type by declaring its own slot, which it can
+ * now do by replacement.
+ */
+export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   toTransfer<T extends AstNode>(ast: T, mode?: TransferMode): TransferElement;
+   toTransferDocument(langiumDocument: LangiumDocument): TransferDocument<TransferElement, TDiagnostic>;
+   astDocumentToTransferDocument<TAst extends AstNode>(
+      document: AstDocument<TAst, AstDiagnostic>
+   ): TransferDocument<TransferElement, TDiagnostic>;
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic;
+}
+
 /**
  * One-directional structural mapper from a Langium AST into the wire
  * transfer-model shape ({@link TransferElement}-based JSON).
@@ -112,7 +146,8 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link propertyKeys} — which property names the walk visits.
  * - {@link shouldEmitProperty} — per-key filter on top of the default
  *   `$`-internals strip.
- * - {@link resolvePropertyValue} — value substitution per property.
+ * - {@link resolvePropertyValue} — value substitution per property, `'full'`
+ *   mode only (see there for why `'grammar'` bypasses it).
  * - {@link finalizeTransferNode} — post-decoration per encoded node.
  * - {@link toTransferValue} — recursion seam per property value. Override
  *   to special-case reference encoding or to drop specific value shapes.
@@ -120,10 +155,10 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link toTransferDocument} — bundle root + diagnostics into the wire
  *   {@link TransferDocument} envelope. Override to filter / merge
  *   diagnostics from auxiliary sources or to project a synthesised root.
- * - {@link toTransferDiagnostic} — project a {@link TransferLspDiagnostic}
+ * - {@link toTransferDiagnostic} — project a {@link AstDiagnostic}
  *   (the framework validator's output) to {@link TDiagnostic}.
  */
-export class TransferEncoder<
+export class DefaultTransferEncoder<
    // The map is intentionally unconstrained — adopters supply typed
    // overlays whose specific-key shapes don't structurally satisfy a
    // `Record<string, TransferElement>` index signature. `TransferTypeFor`
@@ -226,7 +261,14 @@ export class TransferEncoder<
          if (!this.shouldEmitProperty(ast, key, context)) {
             continue;
          }
-         const value = this.resolvePropertyValue(ast, key, context);
+         // `'grammar'` reads the authored value straight off the node rather than
+         // through `resolvePropertyValue`. The mode promises a shape the serializer
+         // round-trips, and a value-substitution hook cannot honour that: what it
+         // returns is by construction not what the document declared. Scoping the
+         // hook to `'full'` is what makes that guarantee structural instead of a
+         // rule every override has to remember.
+         const value =
+            context.mode === 'grammar' ? (ast as unknown as Record<string, unknown>)[key] : this.resolvePropertyValue(ast, key, context);
          // `'grammar'` lists every declared property, including those absent on
          // this node; skip the absent ones. (`'full'` enumerates only own
          // properties, so absent properties never surface there.) Part of the
@@ -267,8 +309,17 @@ export class TransferEncoder<
    }
 
    /**
-    * Which value the walk emits under `key`. Default: the node's own value.
-    * Override to substitute a derived value under a grammar property name.
+    * Which value the walk emits under `key`, in `'full'` mode ONLY. Default:
+    * the node's own value.
+    *
+    * Override to substitute a derived value under a grammar property name — an
+    * inheritance-resolved field, a preference-dependent label. `'grammar'`
+    * bypasses this hook and reads the node directly: that mode's contract is
+    * the authored state a serializer round-trips, and a substituted value is by
+    * construction not the one the document declared. An override that applied
+    * in both modes would leave the grammar shape carrying derived values under
+    * declared property names — diffable and acyclic still, but no longer
+    * authored, which is the property every consumer of that mode relies on.
     */
    protected resolvePropertyValue(ast: AstNode, key: string, _context: EncodeContext): unknown {
       return (ast as unknown as Record<string, unknown>)[key];
@@ -340,12 +391,12 @@ export class TransferEncoder<
       source: TransferEnvelopeSource<TDiagnostic>,
       root: TransferTypeFor<TAst, TTransferMap>
    ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
-      return {
-         uri: source.uri,
-         version: source.version,
+      return TransferDocument.create(
+         source.uri,
+         source.version,
          root,
-         diagnostics: source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as TransferLspDiagnostic))
-      };
+         source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as AstDiagnostic))
+      );
    }
 
    /**
@@ -359,7 +410,7 @@ export class TransferEncoder<
     * second `LangiumDocuments.getDocument` lookup.
     *
     * The `diagnostic` projection assumes the snapshot's diagnostics carry
-    * the `TransferLspDiagnostic` shape ({@link Diagnostic} plus the
+    * the `AstDiagnostic` shape ({@link Diagnostic} plus the
     * framework validator's `element` / `property` decoration). Snapshots
     * built from raw Langium diagnostics structurally satisfy this — the
     * extra fields are optional in the projection.
@@ -370,7 +421,7 @@ export class TransferEncoder<
     * assembly seam rather than duplicating it.
     */
    astDocumentToTransferDocument<TAst extends AstNode>(
-      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
+      document: AstDocument<TAst, AstDiagnostic>
    ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
       const root = this.encodeNode(document.root, this.createEncodeContext('full', document.uri)) as TransferTypeFor<TAst, TTransferMap>;
       return this.assembleTransferDocument<TAst>(document, root);
@@ -378,7 +429,7 @@ export class TransferEncoder<
 
    /**
     * Project an LSP-shaped diagnostic (typically a
-    * {@link TransferLspDiagnostic} produced by
+    * {@link AstDiagnostic} produced by
     * `HydraniumDocumentValidator` — adds `element` + optional `property`
     * to the standard {@link Diagnostic} shape) to the wire-diagnostic
     * shape.
@@ -387,15 +438,24 @@ export class TransferEncoder<
     * LSP severity enum to the wire string union, discriminates the
     * diagnostic type from Langium's `data.code` (`'lexing-error'` /
     * `'parsing-error'` else `'validation-error'`), passes through
-    * message / element / property / code. Adopters whose validator
+    * message / element / property / code, and lifts the framework message
+    * params out of `data` so a translating surface can render a
+    * parameterised diagnostic rather than a template with its placeholders
+    * left standing. Adopters whose validator
     * doesn't decorate diagnostics with `element` still get a valid
     * `TransferDiagnostic` — the field falls back to `''`.
     *
     * Override only if the wire-diagnostic shape needs fields beyond
     * what {@link TransferDiagnostic} carries.
     */
-   toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic {
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic {
       const langiumCode = (diagnostic.data as { code?: string } | undefined)?.code;
+      // The same `data` the Langium code comes out of also carries the framework
+      // message identity, under its own key so the two conventions co-exist.
+      // Taking the params from there rather than from `code` is what lets a
+      // translating surface render a PARAMETERISED diagnostic: `code` survives on
+      // its own and yields a template with its placeholders left standing.
+      const identity = hasMessageIdentity(diagnostic.data) ? diagnostic.data.hydranium : undefined;
       const result: TransferDiagnostic = {
          type: langiumCode === 'lexing-error' ? 'lexing-error' : langiumCode === 'parsing-error' ? 'parsing-error' : 'validation-error',
          element: diagnostic.element ?? '',
@@ -408,7 +468,8 @@ export class TransferEncoder<
                : diagnostic.severity === DiagnosticSeverity.Warning
                  ? 'warning'
                  : 'info',
-         code: typeof diagnostic.code === 'number' || typeof diagnostic.code === 'string' ? diagnostic.code : langiumCode
+         code: typeof diagnostic.code === 'number' || typeof diagnostic.code === 'string' ? diagnostic.code : langiumCode,
+         params: identity?.params
       };
       return result as TDiagnostic;
    }