@hydranium/core 1.0.0-next.7 → 1.0.0-next.71

package/src/langium/module.ts

@@ -7,30 +7,34 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock, type Logger, type Project, type Tracer, type TransferDiagnostic, NoopLogger, SystemClock } from '@hydranium/protocol';
+import { type Clock, type Logger, type Project, type Tracer, NoopLogger, SystemClock } from '@hydranium/protocol';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 import { ServerTracer } from './diagnostics/server-tracer.js';
 import { HydraniumLangiumProfiler } from './diagnostics/hydranium-langium-profiler.js';
 import { type AstNode, type Module } from '@hydranium/langium';
 import { type DefaultSharedModuleContext, type LangiumSharedServices, type PartialLangiumSharedServices } from '@hydranium/langium/lsp';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
-import { ModelService } from './model-service/model-service.js';
+import { DefaultModelService, type ModelService } from './model-service/model-service.js';
 import { type ProjectManager } from './project/project-manager.js';
 import { SingleProjectManager } from './project/single-project-manager.js';
-import { TransferEncoder } from './transfer/transfer-encoder.js';
+import { DefaultTransferEncoder, type TransferEncoder } from './transfer/transfer-encoder.js';
 import { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
-import { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
+import { DefaultBuildPipelineIntegration, type BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
 import { type BuildPhasePassContribution } from './build-phase-pass/build-phase-pass.js';
 import { type BuildPhasePassService, DefaultBuildPhasePassService } from './build-phase-pass/build-phase-pass-service.js';
-import { CstResidencyService } from './residency/index.js';
+import { DefaultCstResidencyService, type CstResidencyService } from './residency/index.js';
+import { HydraniumConfigurationProvider } from './config/configuration-provider.js';
 import { HydraniumIndexManager } from './workspace/index-manager.js';
 import { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
 import { HydraniumWorkspaceLock } from './workspace/hydranium-workspace-lock.js';
 import { HydraniumLangiumDocumentFactory } from './workspace/hydranium-langium-document-factory.js';
+import { type HydraniumDocumentRegistry, HydraniumLangiumDocuments } from './workspace/langium-documents.js';
 import { type AdditionalDocumentContribution } from './workspace/additional-document-contribution.js';
 import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from './workspace/document-uri-policy.js';
 import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
-import { AstDocumentManager, type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
-import { SelfSaveRegistry } from '../documents/self-save-registry.js';
+import { DefaultAstDocumentManager, type AstDocumentManager, type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import { DefaultSelfSaveRegistry, type SelfSaveRegistry } from '../documents/self-save-registry.js';
 import { DefaultEmptyFileSystemProvider } from './workspace/file-system-provider.js';
 import { type ServerLanguageServices } from './language-module.js';
 import { ExtendedServiceRegistry } from './service-registry.js';
@@ -91,6 +95,24 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
     * plain `DefaultTracer` with their own `MemoryReader`.
     */
    Tracer: Tracer;
+   /**
+    * Renders each user-facing message once, before the server sends it — so
+    * every message is rendered by the side that knows the reading user's
+    * language. All three heads inherit one diagnostics pass, which is what
+    * makes this the single slot an adopter with i18n rebinds; the same binding
+    * serves framework codes and their own `defineMessage` codes alike.
+    *
+    * The framework ships English only and selects no locale, so the default
+    * returns every sentence unchanged. Adopters subclass and override
+    * `translationsFor`.
+    */
+   MessageRenderer: MessageRenderer;
+   /**
+    * The locale an init handed the server, for whoever renders in it. Held
+    * apart from the renderer so replacing the renderer cannot drop locale
+    * handling.
+    */
+   ServerLocale: ServerLocale;
    /**
     * LSP-bound slots layered on top of Langium's `LangiumSharedLSPServices`.
     * The framework contributes a single string slot here —
@@ -113,6 +135,12 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
    workspace: {
       /* override */ TextDocuments: HydraniumTextDocuments<TextDocument>;
       /* override */ WorkspaceManager: HydraniumWorkspaceManager;
+      /**
+       * Narrow Langium's registry slot to the framework surface, which adds
+       * `createEmptyDocument` — reachable only through this narrowing, and
+       * wanted by a scope provider querying a URI before the file exists.
+       */
+      /* override */ LangiumDocuments: HydraniumDocumentRegistry;
       /**
        * Narrow Langium's `IndexManager` slot to the framework subclass, which
        * layers an `elementsByName` map over Langium's index and exposes
@@ -228,14 +256,22 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
     * heads read both slots from shared services rather than constructor
     * arguments.
     *
-    * Slot types use the upper bounds (`unknown` for encoder map / facade
-    * generics, {@link TransferDiagnostic} for the encoder's wire-diagnostic
-    * shape) so adopter subclasses with narrower typed overlays satisfy
-    * the slot via output-position covariance — `TDiagnostic` appears
-    * only in encoder return positions.
+    * `TransferEncoder` is the INTERFACE, not `DefaultTransferEncoder` — an
+    * adopter can therefore REPLACE this declaration (see
+    * {@link WithServiceOverrides}) rather than intersect with it, which is what
+    * keeps slot resolution independent of the order a services type is written
+    * in. `ModelService` is still a class and does not yet have that property.
+    *
+    * A class in a slot costs two things, both measured. Its `protected` members
+    * join every assignability check and are compared NOMINALLY, so a subclass
+    * declared against a second physical copy of this package cannot satisfy it.
+    * And where the class is generic over a map reached through `keyof`, that
+    * parameter is measured INVARIANT — instantiations then relate only when
+    * their arguments are mutually assignable, which no adopter map is with the
+    * framework's. Neither survives on an interface.
     */
    model: {
-      TransferEncoder: TransferEncoder<unknown, TransferDiagnostic>;
+      TransferEncoder: TransferEncoder;
       ModelService: ModelService<AstNode, unknown>;
    };
    /**
@@ -279,6 +315,45 @@ export type ServerSharedServices<TProject extends Project = Project> = Omit<Lang
    workspace: Omit<LangiumSharedServices['workspace'], 'TextDocuments' | 'DocumentBuilder'>;
 } & ServerAddedSharedServices<TProject>;
 
+/**
+ * The service-tree namespaces — the keys whose value groups further slots
+ * rather than being a slot itself.
+ *
+ * Consumed by {@link WithServiceOverrides} to know where to merge one level
+ * deeper. **Add a namespace to {@link ServerAddedSharedServices} and you must
+ * add it here**, and the failure of forgetting is silent in the direction that
+ * matters: an unlisted namespace is treated as a leaf, so an adopter overriding
+ * one slot inside it replaces the WHOLE namespace and loses the sibling slots
+ * with no diagnostic. The reverse mistake — listing a leaf — fails loudly.
+ */
+type ServiceNamespace = 'lsp' | 'workspace' | 'model';
+
+/**
+ * Compose an adopter's service tree so its declarations REPLACE the framework's
+ * rather than intersecting with them.
+ *
+ * Langium composes services by intersection, which accumulates: two
+ * declarations of one slot survive as an overload set, and which one a call
+ * resolves to depends on the order the intersection was written in — silently,
+ * with no diagnostic at the point a reorder changes it. There is no override
+ * operator for intersections, so the framework's declaration has to be removed
+ * before the adopter's is added. This does that, one level deep for each
+ * {@link ServiceNamespace}, so a narrowed slot replaces its framework twin
+ * while its siblings survive.
+ *
+ * Only slots typed as INTERFACES can be replaced this way. A class-typed slot
+ * drags its `protected` members into the assignability check — compared
+ * nominally — so an adopter subclass does not satisfy it and the framework's
+ * declaration cannot be dropped.
+ */
+export type WithServiceOverrides<TBase, TOverrides> = Omit<TBase, keyof TOverrides> & {
+   [K in keyof TOverrides]: K extends ServiceNamespace
+      ? K extends keyof TBase
+         ? Omit<TBase[K], keyof TOverrides[K]> & TOverrides[K]
+         : TOverrides[K]
+      : TOverrides[K];
+};
+
 /**
  * Construction context for {@link createServerSharedModule}.
  *
@@ -327,6 +402,8 @@ export function createServerSharedModule(
       ServiceRegistry: services => new ExtendedServiceRegistry<ServerLanguageServices>(services),
       Logger: () => new NoopLogger(),
       Tracer: services => new ServerTracer(services.Logger, services.Clock),
+      ServerLocale: services => new DefaultServerLocale(services),
+      MessageRenderer: services => new DefaultMessageRenderer(services),
       // Bind Langium's per-grammar-rule / per-`$type` parse/link/validate
       // profiler (the data the framework's own `Tracer`/`ProfileSession` passes
       // cannot produce), routed through our `Logger` and debug-gated. At the
@@ -388,16 +465,24 @@ export function createServerSharedModule(
          TextDocuments: services => new HydraniumTextDocuments(services),
          WorkspaceManager: services => new HydraniumWorkspaceManager(services),
          IndexManager: services => new HydraniumIndexManager(services),
+         // Langium's default asks only about sections named after registered
+         // language ids, so a section `lsp.configurationRoot` is bound to reads
+         // `undefined` forever with no request on the wire.
+         ConfigurationProvider: services => new HydraniumConfigurationProvider(services),
          // Override Langium's factory so a `fromModel` (code-built) virtual
          // document retains serialized text via the per-language Serializer,
          // making it re-read-safe through the virtual-aware FileSystemProvider.
          LangiumDocumentFactory: services => new HydraniumLangiumDocumentFactory(services),
+         // Langium's default routes through no identity seam and treats every
+         // failed load alike, so leaving this unbound opts a server out of both
+         // with nothing to signal it.
+         LangiumDocuments: services => new HydraniumLangiumDocuments(services),
          DocumentBuilder: services => new HydraniumDocumentBuilder(services),
          // The write-lock scope this marks is inert unless a host installs a
          // scope tracker — `@hydranium/core/node` does.
          WorkspaceLock: () => new HydraniumWorkspaceLock(),
          ProjectManager: services => new SingleProjectManager(services),
-         SelfSaveRegistry: services => new SelfSaveRegistry(services),
+         SelfSaveRegistry: services => new DefaultSelfSaveRegistry(services),
          DocumentUriPolicy: () => new DefaultDocumentUriPolicy(),
          // Writable filesystem with two paths:
          // - Adopter passed `context.fileSystemProvider` and it returned a
@@ -421,20 +506,20 @@ export function createServerSharedModule(
             }
             return new DefaultEmptyFileSystemProvider(services);
          },
-         AstDocumentManager: services => new AstDocumentManager(services),
+         AstDocumentManager: services => new DefaultAstDocumentManager(services),
          // Eagerly constructed, so its build-phase listeners attach before the
          // first build.
-         BuildPipelineIntegration: services => new BuildPipelineIntegration(services),
+         BuildPipelineIntegration: services => new DefaultBuildPipelineIntegration(services),
          BuildPhasePassService: services => new DefaultBuildPhasePassService(services),
          // Eagerly constructed, so its `Validated` pass registers before the
          // first build.
-         CstResidencyService: services => new CstResidencyService(services)
+         CstResidencyService: services => new DefaultCstResidencyService(services)
       },
       model: {
          // Generic walker — adopters with a typed `$type → wire shape` overlay
          // rebind this slot with a subclass.
-         TransferEncoder: services => new TransferEncoder(services),
-         ModelService: services => new ModelService(services)
+         TransferEncoder: services => new DefaultTransferEncoder(services),
+         ModelService: services => new DefaultModelService(services)
       },
       // Empty default so `services.buildPhasePasses` always resolves (Langium
       // throws on access to an unbound slot). The framework's own integrity /

package/src/langium/naming/name-provider.ts

@@ -59,6 +59,16 @@ export interface NameProviderOptions {
     * an `id` field) override explicitly; the explicit override at
     * the adopter side documents the grammar's convention rather than
     * burying it in a framework default.
+    *
+    * **The override is not optional where `name` is a display LABEL rather
+    * than an identifier**, and getting it wrong is quiet at first and then
+    * loud. A `name=STRING` holding `"Order.Line"` is legitimate content, but
+    * the default reads it as the identifier: `getName` composes a qualified
+    * name whose segments cannot be told apart from the label's own dots, and
+    * `nameSeparatorCheck` reports `hydranium/core/separator-in-name` on every
+    * such node. That diagnostic then names the wrong remedy — it asks for a
+    * different character, when the fix is to point this option at the property
+    * that really is the identifier.
     */
    readonly nameProperties?: readonly string[];
 }

package/src/langium/naming/name-separator-validation.ts

@@ -8,10 +8,39 @@
  ********************************************************************************/
 
 import { type AstNode, type ValidationAcceptor, type ValidationChecks } from '@hydranium/langium';
+import { defineMessage } from '@hydranium/protocol';
+import { acceptMessage } from '../../messages/carriers.js';
 import { type ServerLanguageServices } from '../language-module.js';
 import { type ValidationCheckContribution, type ValidationCheckRegistry } from '../validation/validation-contribution.js';
 import type { NameProvider } from './name-provider.js';
 
+/**
+ * A name value that collides with the qualified-name separator.
+ *
+ * **The sentence addresses a MODELLER, and the remedy it names is theirs**:
+ * where `name` really is the identifier, a different character is the fix and
+ * the only one available to whoever is typing.
+ *
+ * **The adopter-facing failure is a different one, and this message cannot
+ * carry it.** With `nameProperties` left at its default `['name']` over a
+ * grammar where `name` is a display LABEL — a `STRING` legitimately holding
+ * `"Order.Line"` — this fires on every dotted label at once, and "use a
+ * different character" is then advice nobody can act on: the content is
+ * correct and the configuration is not. A burst of this diagnostic across
+ * unrelated nodes is that misconfiguration, not a naming problem, and the fix
+ * is `nameProperties`. Widening the sentence to say both was rejected: a
+ * modeller cannot act on a DI option, and naming one in an editor squiggle
+ * teaches the wrong audience.
+ *
+ * Unreachable from a grammar whose identifier charset excludes the separator,
+ * which is every example here and the reference adopter — so it reads as dead
+ * and is not: it guards the configuration, not the content.
+ */
+export const SEPARATOR_IN_NAME = defineMessage(
+   'hydranium/core/separator-in-name',
+   "Name '{name}' contains the configured name separator '{separator}', which is reserved for qualified-name composition — use a different character."
+);
+
 /**
  * Per-node validation check: flag name-bearing AST nodes whose name
  * value contains the configured name separator. Such values produce
@@ -38,11 +67,11 @@ export function nameSeparatorCheck(nameProvider: NameProvider): (node: AstNode,
       }
       const separator = nameProvider.nameSeparator;
       if (ownName.includes(separator)) {
-         accept(
-            'error',
-            `Name '${ownName}' contains the configured name separator '${separator}', which is reserved for qualified-name composition — use a different character.`,
-            { node }
-         );
+         // `{ node }` rather than `{ node, property: 'name' }`: moving the
+         // squiggle onto the name property is a behaviour change to the one
+         // diagnostic every adopter receives by default, so it is decided on its
+         // own merits rather than carried in by a mechanical migration.
+         acceptMessage(accept, 'error', SEPARATOR_IN_NAME, { node }, { name: ownName, separator });
       }
    };
 }

package/src/langium/residency/cst-residency-service.ts

@@ -24,9 +24,13 @@ import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
  * Default priority of the CST-residency pass. Deliberately very high so it runs
  * *last* among `Validated` build-phase passes (the registry iterates priority
- * ascending): every other reaction to the build — an adopter's own derived-state
- * pass included — settles while the CST is still guaranteed resident, before the
- * residency policy arms the shed.
+ * ascending).
+ *
+ * The ordering is defensive, not load-bearing: the pass only arms or cancels an
+ * idle timer, so every pass at `Validated` reads a resident CST whichever order
+ * they run in, and lowering it changes nothing observable while that holds. It
+ * becomes load-bearing the moment the shed stops being deferred — a pass that
+ * frees the CST synchronously has to run after every reader of it.
  */
 export const CST_RESIDENCY_PASS_PRIORITY = 1_000_000;
 
@@ -225,9 +229,29 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
  * demand by the identity-preserving graft of {@link rehydrateNode} /
  * {@link rehydrate}, driven transparently from the framework
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
- * `AbstractHydraniumLangiumDocuments.getOrCreateDocument`.
+ * `HydraniumLangiumDocuments.getOrCreateDocument`.
+ */
+/**
+ * Keeps a document's CST available to the readers that need one, shedding it
+ * for documents that have gone idle and re-grafting on demand.
  */
-export class CstResidencyService {
+export interface CstResidencyService {
+   /**
+    * Ensure `document` has a CST, re-parsing its retained text if it was shed.
+    * A resident document is left exactly as it is, so this is safe to call on
+    * a hot path and safe to call twice.
+    */
+   rehydrate(document: LangiumDocument): void;
+
+   /**
+    * Node-level convenience over {@link rehydrate}, cheap enough for an
+    * unconditional call: a node whose `$cstNode` is already set returns
+    * without resolving its document.
+    */
+   rehydrateNode(node: AstNode): void;
+}
+
+export class DefaultCstResidencyService implements CstResidencyService {
    protected readonly strategy: CstResidencyStrategy;
    /** Bytes-per-node for the optional reclaim estimate in traces; `0` disables it. */
    protected readonly estimatedBytesPerShedNode: number;
@@ -277,8 +301,8 @@ export class CstResidencyService {
     * until navigation latency on shed files is actually observed to hurt. This
     * method is where that hook goes.
     */
-   rehydrate(document: LangiumDocument): boolean {
-      return rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
+   rehydrate(document: LangiumDocument): void {
+      rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
    }
 
    /**
@@ -287,11 +311,11 @@ export class CstResidencyService {
     * `true` without even resolving the document, so hot read paths
     * (`getNameNode`, comment lookup) call this unconditionally.
     */
-   rehydrateNode(node: AstNode): boolean {
+   rehydrateNode(node: AstNode): void {
       if (node.$cstNode !== undefined) {
-         return true;
+         return;
       }
-      return this.rehydrate(AstUtils.getDocument(node));
+      this.rehydrate(AstUtils.getDocument(node));
    }
 
    /**
@@ -353,8 +377,8 @@ export class CstResidencyService {
       this.shedTotal += this.shed(document);
    }
 
-   /** Cancel and drop every idle timer — for clean shutdown and deterministic tests. */
-   dispose(): void {
+   /** Cancel every armed shed, so a document that has gone idle keeps its CST. */
+   cancelPendingShed(): void {
       for (const timer of this.idleTimers.values()) {
          timer.dispose();
       }

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;
@@ -469,12 +470,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 +488,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 +587,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/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,6 +8,7 @@
  ********************************************************************************/
 
 import {
+   hasMessageIdentity,
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
@@ -79,6 +80,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, TDiagnostic | TransferLspDiagnostic>
+   ): TransferDocument<TransferElement, TDiagnostic>;
+   toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic;
+}
+
 /**
  * One-directional structural mapper from a Langium AST into the wire
  * transfer-model shape ({@link TransferElement}-based JSON).
@@ -123,7 +155,7 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link toTransferDiagnostic} — project a {@link TransferLspDiagnostic}
  *   (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`
@@ -387,7 +419,10 @@ 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 `''`.
     *
@@ -396,6 +431,12 @@ export class TransferEncoder<
     */
    toTransferDiagnostic(diagnostic: TransferLspDiagnostic): 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 +449,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;
    }