@hydranium/core 1.0.0-next.5 → 1.0.0-next.50

package/src/langium/keys/containment.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Containment-array maintenance for callers that build or delete AST nodes
+ * programmatically — a GLSP operation handler being the usual one.
+ *
+ * **These live beside the key provider because the constraint is the key
+ * provider's.** `NameBasedKeyProvider` keys a node the `NameProvider` gives no
+ * name from its position, as `` `${$containerProperty}@${$containerIndex}` ``,
+ * so a node appended with a bare `array.push` carries neither and
+ * `getElementKey` answers `undefined` — the element has no key at all, and the
+ * GLSP index cannot address it. Deleting from the middle of such a list must
+ * renumber the survivors, or an id derived later in the same command names the
+ * wrong node. Shipping the constraint's statement without the code that
+ * discharges it leaves every adopter in that position re-deriving thirty lines
+ * from prose, and both failures are silent.
+ *
+ * The population is narrower than "anyone creating elements from a diagram": it
+ * takes a grammar with UNNAMED element types, programmatic creation or deletion
+ * of them, and this key provider. A grammar whose diagram elements are all
+ * named never reaches it, and the two ways out are named on the provider —
+ * give the type a name, or bind a provider whose fallback is content-derived.
+ *
+ * **Free functions, and deliberately not a step on the AST builder.** Building a
+ * node detached and appending it later is legitimate, so a containment step
+ * cannot be mandatory; and an optional fluent step could not check the index
+ * against the array unless it were handed the array, at which point it is these
+ * signatures with more ceremony. `AstNodeInit` already accepts the three fields
+ * for a caller who has them, which is the case these cover: it is the INDEX that
+ * cannot be known without reading the array.
+ */
+
+import type { AstNode } from '@hydranium/langium';
+import type { Mutable } from '@hydranium/protocol';
+
+/**
+ * Append `child` to `children`, stamping the Langium containment plumbing
+ * (`$container`, `$containerProperty`, `$containerIndex`) so a positional key
+ * can address it.
+ *
+ * `property` and `children` are separate parameters rather than one property
+ * name the function dereferences: the array is what the index is derived from,
+ * so taking it directly is what makes the two agree by construction instead of
+ * by a lookup that a typo could point elsewhere.
+ *
+ * @returns `child`, so a caller can append and use it in one expression.
+ */
+export function appendChild<TChild extends AstNode>(container: AstNode, property: string, children: TChild[], child: TChild): TChild {
+   const mutable = child as Mutable<TChild>;
+   mutable.$container = container;
+   mutable.$containerProperty = property;
+   mutable.$containerIndex = children.length;
+   children.push(child);
+   return child;
+}
+
+/**
+ * Remove every entry of `children` that is in `toRemove`, then renumber the
+ * survivors' `$containerIndex`.
+ *
+ * Mutates `children` in place rather than returning a new array, because the
+ * caller's array IS the AST's containment list — replacing the reference would
+ * leave the parent pointing at the old one.
+ *
+ * @returns how many entries were removed, so a caller can tell a no-op delete
+ * from one that changed the model without comparing lengths itself.
+ */
+export function removeChildren<TChild extends AstNode>(children: TChild[], toRemove: ReadonlySet<TChild>): number {
+   if (toRemove.size === 0) {
+      return 0;
+   }
+   const survivors = children.filter(child => !toRemove.has(child));
+   const removed = children.length - survivors.length;
+   children.length = 0;
+   for (const [index, child] of survivors.entries()) {
+      (child as Mutable<TChild>).$containerIndex = index;
+      children.push(child);
+   }
+   return removed;
+}

package/src/langium/keys/index.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './containment.js';
 export * from './element-key-provider.js';
 export * from './name-based-key-provider.js';
 export * from './positional-key-provider.js';

package/src/langium/keys/name-based-key-provider.ts

@@ -55,6 +55,10 @@ import { type NameProvider } from '../naming/name-provider.js';
  * - After a removal, surviving siblings need their `$containerIndex`
  *   renumbered, or a key derived afterwards addresses the wrong node.
  *
+ * {@link appendChild} and {@link removeChildren} discharge both, and ship
+ * beside this provider because the constraint is this provider's rather than
+ * any caller's.
+ *
  * Adopters that need insert / delete stability for unnamed types should
  * give those types a name in the grammar, or bind a key provider whose
  * fallback is content-derived rather than positional.

package/src/langium/model-service/model-service.ts

@@ -11,6 +11,7 @@ import {
    type CanonicalUri,
    type CloseModelArgs,
    ConflictError,
+   defineMessage,
    Logger,
    type MaybeObservableValue,
    type MaybePromise,
@@ -34,6 +35,23 @@ import { labelPhaseListener } from '../document-builder/labeled-phase-listener.j
 import { LANGUAGE_CLIENT_ID } from '../../documents/client-ids.js';
 import { type ServerSharedServices } from '../module.js';
 
+/**
+ * The undo-stack entry for a server-authored write pushed to the editor.
+ *
+ * **A user-facing LABEL, not a log string**, which is easy to miss because it
+ * travels as an options field rather than as a message: LSP specifies
+ * `ApplyWorkspaceEditParams.label` as "presented in the user interface for
+ * example on an undo stack to undo the workspace edit". So a user who edits
+ * through a form or drags a diagram node reads this in their editor's undo menu
+ * — which is why it is rendered like any other message the server sends rather
+ * than left as the English literal it was.
+ *
+ * Parameterless deliberately. The obvious improvement is to name the document,
+ * and it is the wrong one: an undo menu is already grouped under the file, so
+ * the URI would be noise in the one place it is redundant.
+ */
+export const MODEL_UPDATE_EDIT = defineMessage('hydranium/core/model-update-edit', 'Update Model');
+
 /** Max time {@link ModelService.settleSave} waits for the build to settle and the sync chain to drain. */
 const SAVE_SETTLE_TIMEOUT_MS = 10_000;
 
@@ -182,7 +200,74 @@ export interface ModelServiceOptions extends LogNameOptions {
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
  */
-export class ModelService<
+/**
+ * The seam every non-LSP head talks to: the data server, the GLSP head and an
+ * adopter's own services reach documents through this slot rather than through
+ * the workspace stores.
+ *
+ * **Two families, and the distinction matters more than the names suggest.**
+ * `waitFor*` is a pure wait — it never triggers a build, so a caller waiting on
+ * a document no build has touched waits until something else builds it.
+ * `ensureDocumentState` and the phase shorthands over it *dispatch*: warm
+ * documents are awaited, cold ones are built.
+ *
+ * **Diagnostics are typed `never` below `Validated`.** Validation is the last
+ * phase, so at any earlier landmark the array either is not yet computed or
+ * still holds the previous build's, and reading it would take stale results
+ * for fresh ones. A caller that needs diagnostics asks for {@link validated}.
+ *
+ * What the `never` buys, exactly: reading a field off an element is a compile
+ * error, and nothing can be appended. It does NOT stop a caller assigning an
+ * element to a typed variable, because `never` is assignable to everything — so
+ * this is a guard against reaching for diagnostics by accident, not a seal
+ * against doing it deliberately.
+ *
+ * The waits resolve at or ABOVE their target, so an already-validated document
+ * does carry usable diagnostics and the `never` over-forbids there. That
+ * direction is the safe one: the alternative permits stale reads silently. A
+ * member taking a phase as a PARAMETER cannot judge statically and so returns
+ * `TDiagnostic`, leaving the choice to the caller.
+ */
+export interface ModelService<TAst extends AstNode, TDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement> {
+   /**
+    * Resolves once the workspace has been initialised and its first build has
+    * completed — the gate every read should wait behind, since a document
+    * queried before it may be unbuilt and reach no phase.
+    *
+    * A property rather than a method, matching `ProjectManager.ready` and
+    * Langium's `WorkspaceManager.ready`. An implementation needing a stricter
+    * gate supplies a Promise that awaits its own concern as well.
+    */
+   readonly ready: Promise<void>;
+
+   // Pure waits — never trigger a build.
+   waitForDocumentState(uri: string, state: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   waitForBuilderState(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+
+   // Wait if warm, build if cold.
+   ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   rebuild(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   open(args: OpenModelArgs): Promise<Disposable>;
+   close(args: CloseModelArgs): Promise<void>;
+   isOpen(uri: string): boolean;
+   getDocument(uri: string): LangiumDocument | undefined;
+
+   onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+}
+
+export class DefaultModelService<
    TAst extends AstNode,
    TDiagnostic = TransferDiagnostic,
    /**
@@ -195,7 +280,7 @@ export class ModelService<
     * integrity service) that pass AST roots remain compatible.
     */
    TTransfer extends TransferElement = TransferElement
-> {
+> implements ModelService<TAst, TDiagnostic, TTransfer> {
    protected readonly tracer: Tracer;
    /**
     * The single document-identity seam (`services.workspace.DocumentUriPolicy`),
@@ -329,8 +414,12 @@ export class ModelService<
     * {@link waitForDocumentState} for the common "wait until content is stable"
     * case (e.g. settling a save). Pure wait — does not trigger a build.
     */
-   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken);
+   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
+      return (await this.waitForDocumentStateCanonical(
+         this.uriPolicy.canonicalUri(uri),
+         IntegrityService.SettledState,
+         cancelToken
+      )) as AstDocument<TAst, never>;
    }
 
    /**
@@ -484,11 +573,22 @@ export class ModelService<
     *
     * Phase invariants encoded in the return type:
     * - `parsed` / `linked` / `settled` / `indexed` return
-    *   `AstDocument<TAst, never>` — diagnostics array is empty by phase
-    *   contract.
+    *   `AstDocument<TAst, never>` — no diagnostics have been computed at
+    *   those phases.
     * - `validated` returns `AstDocument<TAst, TDiagnostic>` — diagnostics
     *   are populated.
     *
+    * **The `never` is a claim about the PHASE, not a guarantee about the
+    * instance, and the gap is reachable rather than theoretical.** The wait
+    * underneath resolves at or ABOVE the requested state, so a document
+    * something else already carried past `Validated` comes back from
+    * `settled()` with a populated diagnostics array typed `never`. Nothing
+    * strips it — the envelope copies the live document's array verbatim — and
+    * any host that validates its workspace before a consumer asks produces
+    * exactly that. So read an empty array as "none were computed, or there are
+    * none", never as "this document is clean", and call {@link validated} when
+    * the answer has to mean the second.
+    *
     * `settled` is the integrity-overlay name for "all integrity rules
     * have fired"; it maps to {@link IntegrityService.SettledState} (which
     * equals `DocumentState.IndexedReferences`), but the dedicated method
@@ -598,19 +698,29 @@ export class ModelService<
       // created from the payload rather than read from the filesystem — `update`
       // is an upsert. For an already-open document `open` refreshes content (the
       // text is ignored on that branch), so existing-document behaviour is
-      // unchanged. `version` is intentionally NOT forwarded to `open`: a cold
-      // create stays at its initial version, so a based-on-`version` update of a
-      // not-yet-existing document still trips the conflict gate below.
+      // unchanged. `version` is intentionally NOT forwarded to `open`, so a cold
+      // create stays at its initial version rather than adopting a number the
+      // caller chose.
+      //
+      // The gate's version is read BEFORE that open, and must be: for a document
+      // no client holds open, the open assigns the shared version from the
+      // INCOMING text, so a version read afterwards has already absorbed the
+      // caller's own write. Gating on it rejected every modifying write to a
+      // closed document, having compared the caller's `baseVersion` against a
+      // number the caller itself produced — and a serialised round-trip that is
+      // not byte-identical to the stored text was enough to trigger it. Reading
+      // first keeps both cases the gate exists for: an unknown URI answers 0, so
+      // a based-on-version update of a not-yet-existing document still trips it,
+      // and a genuine conflict still trips it, another writer having advanced the
+      // sequence past the version the caller read.
+      const currentVersion = this.services.workspace.TextDocuments.version(uri);
       const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
       await run('open', () => this.open({ uri, clientId: args.clientId, text }));
-      if (args.baseVersion !== undefined) {
-         const current = this.services.workspace.TextDocuments.version(uri);
-         if (current !== args.baseVersion) {
-            // Distinct from the post-build "superseded" debug line below: this is a
-            // based-on-stale rejection (the write never applies), not two writes racing.
-            this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${current}`);
-            throw new ConflictError(uri, args.baseVersion, current);
-         }
+      if (args.baseVersion !== undefined && currentVersion !== args.baseVersion) {
+         // Distinct from the post-build "superseded" debug line below: this is a
+         // based-on-stale rejection (the write never applies), not two writes racing.
+         this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${currentVersion}`);
+         throw new ConflictError(uri, args.baseVersion, currentVersion);
       }
       const appliedVersion = await run('apply', () => this.services.workspace.AstDocumentManager.update(uri, text, args.clientId));
       // Dispatch through the public `rebuild` (which re-canonicalizes the already-
@@ -834,17 +944,17 @@ export class ModelService<
     *
     * The signal is "a known client other than the language client authored this
     * version **and** the URI was in the last build's changed set
-    * (`isDirectChange`)". A framework-internal rebuild reports no author
+    * (`isTriggeringEdit`)". A framework-internal rebuild reports no author
     * (`getAuthor` → `undefined`), so it fails `hasKnownAuthor` without comparing
     * against a sentinel. This is NOT redundant with content/registration — it
     * distinguishes "client edited" from "framework rebuilt", which neither the
-    * shadow nor `isDirectChange` alone can.
+    * shadow nor `isTriggeringEdit` alone can.
     */
    protected isNonLanguageClientEdit(document: LangiumDocument): boolean {
       const documents = this.services.workspace.AstDocumentManager;
       const author = documents.getAuthor(document);
       const hasKnownAuthor = !!author && author !== LANGUAGE_CLIENT_ID;
-      return hasKnownAuthor && documents.isDirectChange(document.textDocument.uri);
+      return hasKnownAuthor && documents.isTriggeringEdit(document.textDocument.uri);
    }
 
    /**
@@ -878,13 +988,26 @@ export class ModelService<
       this.syncChains.set(uri, chain);
    }
 
+   /**
+    * The undo-stack label for a server-authored write, in the locale the server
+    * was handed at init.
+    *
+    * One method rather than the literal at each `applyEdit`, because the two
+    * call sites are the same edit — a push and its full-replace retry — and an
+    * undo menu showing two different words for one operation would read as two
+    * operations.
+    */
+   protected editLabel(): string {
+      return this.services.MessageRenderer.renderMessage(MODEL_UPDATE_EDIT);
+   }
+
    protected async drainSyncQueue(uri: string): Promise<void> {
       const uriLogger = this.tracer.withUri(uri);
       while (this.pendingSync.has(uri)) {
          const text = this.pendingSync.get(uri)!;
          this.pendingSync.delete(uri);
          try {
-            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+            let result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
             if (result?.applied === false && !this.pendingSync.has(uri)) {
                // The push is addressed at the client's LAST DECLARED VERSION, so a
                // rejection normally means the client's buffer moved while the
@@ -905,7 +1028,7 @@ export class ModelService<
                // queued — best-effort, since a settle arriving later simply pushes
                // after this and still wins.
                uriLogger.warn(`Language client rejected applyEdit at its declared version — re-pushing a full replace`);
-               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: 'Update Model' });
+               result = await this.services.workspace.TextDocuments.applyEditToLanguageClient(uri, text, { label: this.editLabel() });
                if (result?.applied === false) {
                   uriLogger.warn(`Language client rejected the full-replace retry too — client content is stale`);
                }

package/src/langium/module.ts

@@ -7,30 +7,33 @@
  * 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 { 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 +94,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 +134,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 +255,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 +314,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 +401,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
@@ -392,12 +468,16 @@ export function createServerSharedModule(
          // 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 +501,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 });
       }
    };
 }