@hydranium/core 1.0.0-next.31 → 1.0.0-next.313

package/src/langium/module.ts

@@ -8,20 +8,24 @@
  ********************************************************************************/
 
 import { type Clock, type Logger, type Project, type Tracer, type TransferDiagnostic, 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 { type ClientSessionFactory, DefaultClientSessionFactory } from './model-service/client-session.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';
@@ -30,9 +34,19 @@ import { type HydraniumDocumentRegistry, HydraniumLangiumDocuments } from './wor
 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 { DefaultEmptyFileSystemProvider } from './workspace/file-system-provider.js';
+import { DefaultAstDocumentManager, type AstDocumentManager } from '../documents/ast-document-manager.js';
+import { DefaultSelfSaveRegistry, type SelfSaveRegistry } from './workspace/self-save-registry.js';
+import { DefaultFileSystemTaskQueue, type FileSystemTaskQueue } from '../documents/file-system-task-queue.js';
+import { DefaultModelLedger, type ModelLedger } from '../documents/model-ledger.js';
+import { DefaultDocumentReleaseHandler, type DocumentReleaseHandler } from '../documents/document-release-handler.js';
+import { DefaultVersionSyncService, type VersionSyncService } from '../documents/version-sync-service.js';
+import {
+   DefaultEmptyFileSystemProvider,
+   DefaultFileSystemProviderRegistry,
+   type FileSystemProviderRegistry,
+   type WritableFileSystemProvider
+} from './workspace/file-system-provider.js';
+import { VIRTUAL_SCHEME, VirtualFileSystemProvider } from './workspace/virtual-document.js';
 import { type ServerLanguageServices } from './language-module.js';
 import { ExtendedServiceRegistry } from './service-registry.js';
 
@@ -44,7 +58,10 @@ import { ExtendedServiceRegistry } from './service-registry.js';
  * these shared services; per-head shared bindings, if any, are
  * contributed by additional modules layered after this one.
  */
-export interface ServerAddedSharedServices<TProject extends Project = Project> {
+export interface ServerAddedSharedServices<
+   TProject extends Project = Project,
+   TDiagnostic extends TransferDiagnostic = TransferDiagnostic
+> {
    /**
     * Injectable time source. Framework default is {@link SystemClock} (real
     * `Date.now` / `performance.now` / `setTimeout`); tests bind a fake to
@@ -92,6 +109,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 —
@@ -134,12 +169,11 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        * the `awaitDocumentState` bug-fix, framework-wired phase logs,
        * and the `markNextReason` observability primitive without
        * binding the slot explicitly. The
-       * `HydraniumDocumentUpdateHandler`'s `dispatch` calls this
-       * slot's `markNextReason` to stage the LSP event that triggered
-       * the build, for a subclass's build logging to tag its line with,
-       * so narrowing here is a load-bearing type contract — adopters who
-       * explicitly downgrade to Langium's default lose that call site's
-       * compile-time target.
+       * `HydraniumDocumentUpdateHandler`'s `dispatch` and
+       * `ModelService.rebuild` build through this slot's
+       * `scheduleUpdate`, so narrowing here is a load-bearing contract:
+       * a builder without it fails every LSP-driven build, and every
+       * session write that takes the lock, at run time.
        */
       /* override */ DocumentBuilder: HydraniumDocumentBuilder;
       /**
@@ -153,20 +187,36 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        */
       /* override */ WorkspaceLock: HydraniumWorkspaceLock;
       /**
-       * Tighten Langium's read-only `FileSystemProvider` slot to
-       * {@link WritableFileSystemProvider}. The framework's save path
-       * ({@link AstDocumentManager.save}, integrity corrections,
-       * `ModelService.save`) requires write semantics — a read-only slot
-       * type forces an `as WritableFileSystemProvider` cast at the binding
-       * line and defers the failure of a read-only implementation to the
-       * first save. The `.`-entry default is
-       * {@link DefaultEmptyFileSystemProvider}, which is what keeps the core
-       * barrel free of `node:fs` and therefore browser-bundleable; a Node host
-       * binds `@hydranium/core/node`'s Node-backed provider (wired to
-       * {@link SelfSaveRegistry}) instead, and adopters override with their own
+       * Tighten Langium's read-only `FileSystemProvider` slot to a
+       * {@link FileSystemProviderRegistry}, which is writable: the
+       * framework's save path ({@link AstDocumentManager.save}, integrity
+       * corrections, a session's `save`) requires write semantics, and a
+       * read-only slot type defers the failure of a read-only
+       * implementation to the first save.
+       *
+       * Bound to {@link DefaultFileSystemProviderRegistry}, which dispatches
+       * by scheme to the {@link ServerAddedSharedServices.fileSystemProviders}
+       * group and sends every other scheme to its `host`: the provider
+       * `context.fileSystemProvider` returns when it is writable, or else
+       * `DefaultEmptyFileSystemProvider`, which is what keeps the core
+       * barrel free of `node:fs` and therefore browser-bundleable. A Node
+       * host passes `@hydranium/core/node`'s Node-backed provider (wired to
+       * {@link SelfSaveRegistry}) instead, and adopters pass their own
        * writable implementation when neither fits.
+       *
+       * To reach the members of its own provider, an adopter declares this
+       * slot as `FileSystemProviderRegistry<MyProvider>` through
+       * {@link WithServiceOverrides}, binds a
+       * `DefaultFileSystemProviderRegistry` with that host from a factory
+       * whose return type names the narrowed slot (a module's `DeepPartial`
+       * checks no host member otherwise), and reads
+       * `FileSystemProvider.host`. A
+       * registry that serves a seeded document under none of its providers
+       * loses the document at its last close, which
+       * {@link HydraniumWorkspaceManager.warnIfDocumentsUnserved} reports
+       * once at startup.
        */
-      /* override */ FileSystemProvider: WritableFileSystemProvider;
+      /* override */ FileSystemProvider: FileSystemProviderRegistry;
       ProjectManager: ProjectManager<TProject>;
       SelfSaveRegistry: SelfSaveRegistry;
       /**
@@ -193,9 +243,17 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        * there is only one, and `'plaintext'` when there are several, rather
        * than naming a language the document demonstrably is not. Consumers
        * that need to narrow the diagnostic type or override lifecycle
-       * behaviour rebind this slot with a subclass.
+       * behaviour rebind this slot with a subclass. Subscribes to the build
+       * pipeline and the text store in its constructor, so it is eagerly
+       * constructed via `DEFAULT_EAGER_SERVICES`.
        */
-      AstDocumentManager: AstDocumentManager<AstNode, unknown>;
+      AstDocumentManager: AstDocumentManager<AstNode>;
+      /**
+       * Orders the server's disk accesses of each file. One slot for every
+       * reader and writer: a service given a queue of its own does not order
+       * against the others.
+       */
+      FileSystemTaskQueue: FileSystemTaskQueue;
       /**
        * Wires the framework's build-time features (integrity, AST
        * enrichment) into Langium's build pipeline: owns the build-phase
@@ -210,7 +268,7 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        * `onBuildPhase` sibling of the per-node `AstExtensionService`
        * (`onDocumentPhase`) and `IntegrityService`. {@link BuildPipelineIntegration}
        * drives it from its phase listeners; the framework self-registers its
-       * integrity passes and the Langium profiler flush into it, and adopters
+       * integrity and CST-residency passes into it, and adopters
        * contribute via the shared {@link ServerAddedSharedServices.buildPhasePasses}
        * group. A single priority space orders framework and adopter passes
        * against one another deterministically.
@@ -227,6 +285,16 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        * strategy (`shed-closed-when-idle`) to enable shedding.
        */
       CstResidencyService: CstResidencyService;
+      /** The version of the text each root was parsed from. */
+      ModelLedger: ModelLedger;
+      /** Reconciles each produced root with the store, and owns every build that syncs a root to its text or recovers one. */
+      VersionSyncService: VersionSyncService;
+      /**
+       * What the build keeps for a document {@link HydraniumTextDocuments} has
+       * released, for every head. Bound to {@link DefaultDocumentReleaseHandler},
+       * which reverts it to disk.
+       */
+      DocumentReleaseHandler: DocumentReleaseHandler;
    };
    /**
     * In-process workspace facade ({@link ModelService}) + AST→transfer
@@ -235,15 +303,29 @@ 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 an interface for the same reason.
+    *
+    * 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>;
-      ModelService: ModelService<AstNode, unknown>;
+      TransferEncoder: TransferEncoder<TDiagnostic>;
+      /**
+       * Subscribes to the settled document phase in its constructor, so it is
+       * eagerly constructed via `DEFAULT_EAGER_SERVICES`.
+       */
+      ModelService: ModelService<AstNode>;
+      /** Builds the handle of every session `ModelService.createSession` starts. */
+      ClientSessionFactory: ClientSessionFactory;
    };
    /**
     * Shared contribution group for batch-level build-phase passes (see
@@ -266,6 +348,15 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
     * contribute none never touch it.
     */
    additionalDocuments: Record<string, AdditionalDocumentContribution>;
+   /**
+    * Shared contribution group of file system providers keyed by the URI
+    * scheme each answers for, which {@link FileSystemProviderRegistry}
+    * dispatches to. The framework registers {@link VirtualFileSystemProvider}
+    * under `virtual`; an adopter deep-merges a provider for a scheme of its
+    * own, and an entry under `virtual` replaces the framework's. A scheme with
+    * no entry goes to the registry's `host`.
+    */
+   fileSystemProviders: Record<string, WritableFileSystemProvider>;
 }
 
 /**
@@ -281,10 +372,57 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
  * `ClientTextDocumentChangeEvent` payload (with `clientId`);
  * `ServiceRegistry.getServices(uri)` keeps the
  * {@link ServerLanguageServices} return shape.
+ *
+ * `TDiagnostic` is the diagnostic the bound `model.TransferEncoder` emits. A
+ * head that sends a narrower diagnostic than `TransferDiagnostic` takes
+ * services typed with it, so none of its envelopes claims a shape the encoder
+ * does not produce.
  */
-export type ServerSharedServices<TProject extends Project = Project> = Omit<LangiumSharedServices, 'workspace' | 'ServiceRegistry'> & {
+export type ServerSharedServices<TProject extends Project = Project, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> = Omit<
+   LangiumSharedServices,
+   'workspace' | 'ServiceRegistry'
+> & {
    workspace: Omit<LangiumSharedServices['workspace'], 'TextDocuments' | 'DocumentBuilder'>;
-} & ServerAddedSharedServices<TProject>;
+} & ServerAddedSharedServices<TProject, TDiagnostic>;
+
+/**
+ * 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}.
@@ -334,6 +472,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
@@ -395,9 +535,13 @@ 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.
+         // making it re-read-safe through `VirtualFileSystemProvider`.
          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
@@ -406,52 +550,53 @@ export function createServerSharedModule(
          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(),
+         WorkspaceLock: services => new HydraniumWorkspaceLock(services),
          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
-         //   writable implementation (has `writeFile`) — use it. Honours the
-         //   Langium-conventional context channel for passing a custom backing
-         //   (in-memory, browser, test stub like `DefaultEmptyFileSystemProvider`).
-         // - Otherwise — the portable default `DefaultEmptyFileSystemProvider`
-         //   (no-op writes, no disk access). Node hosts opt into real disk I/O
-         //   by binding `@hydranium/core/node`'s `DefaultFileSystemProvider`
-         //   (Node-backed, wired to `SelfSaveRegistry` so framework `writeFile`
-         //   calls register their mtime and adopters can suppress the
-         //   `didChangeWatchedFiles` echo) — typically via this same
-         //   `context.fileSystemProvider` channel or by rebinding
-         //   the slot. Keeping the `.`-entry default empty is what lets the
-         //   core barrel stay free of `node:fs` (browser-bundleable); see the
-         //   `@hydranium/core/node` carve.
+         // The host is the provider `context.fileSystemProvider` returns
+         // when it is writable (has `writeFile`); anything narrower gets the
+         // empty provider, which is what keeps the core barrel free of
+         // `node:fs`.
          FileSystemProvider: services => {
             const fromContext = context.fileSystemProvider?.(services);
-            if (fromContext && typeof (fromContext as Partial<WritableFileSystemProvider>).writeFile === 'function') {
-               return fromContext as WritableFileSystemProvider;
-            }
-            return new DefaultEmptyFileSystemProvider(services);
+            const writable = typeof (fromContext as Partial<WritableFileSystemProvider> | undefined)?.writeFile === 'function';
+            return new DefaultFileSystemProviderRegistry(services, {
+               host: writable ? (fromContext as WritableFileSystemProvider) : new DefaultEmptyFileSystemProvider(services)
+            });
          },
-         AstDocumentManager: services => new AstDocumentManager(services),
+         // Eagerly constructed, so its build-pipeline and text-store listeners
+         // attach before the first build.
+         AstDocumentManager: services => new DefaultAstDocumentManager(services),
+         FileSystemTaskQueue: services => new DefaultFileSystemTaskQueue(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),
+         ModelLedger: () => new DefaultModelLedger(),
+         VersionSyncService: services => new DefaultVersionSyncService(services),
+         DocumentReleaseHandler: services => new DefaultDocumentReleaseHandler(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),
+         // Eagerly constructed, so its settled-phase listener attaches before
+         // the first build.
+         ModelService: services => new DefaultModelService(services),
+         ClientSessionFactory: services => new DefaultClientSessionFactory(services)
       },
       // Empty default so `services.buildPhasePasses` always resolves (Langium
       // throws on access to an unbound slot). The framework's own integrity /
-      // profiler passes self-register imperatively, not here.
+      // CST-residency passes self-register imperatively, not here.
       buildPhasePasses: {},
       // Empty default so `services.additionalDocuments` always resolves.
-      additionalDocuments: {}
+      additionalDocuments: {},
+      fileSystemProviders: {
+         [VIRTUAL_SCHEME]: services => new VirtualFileSystemProvider(services)
+      }
    };
 }

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[];
 }
@@ -211,6 +221,11 @@ export interface NameProvider extends LangiumNameProvider {
     * walk traverses through the document root: if the root has its own
     * name, that name IS part of the qualified form. Adopters who want a
     * different boundary override this method.
+    *
+    * May answer as of its first read since the last build: the default
+    * memoises per built node, so a name changed in memory after that read
+    * reads as the old one until its document rebuilds. A node in no document
+    * is named afresh on every call.
     */
    getDocumentQualifiedName(node?: AstNode): string | undefined;
 
@@ -226,6 +241,10 @@ export interface NameProvider extends LangiumNameProvider {
     * string) or no project owns the URI — in those cases project-
     * qualified equals document-qualified, and
     * `HydraniumScopeComputation` skips the multi-tier emit.
+    *
+    * The default memoises it as it does {@link getDocumentQualifiedName}, and
+    * for a node in no document answers the document-qualified name: there is
+    * no project to prefix.
     */
    getProjectQualifiedName(node?: AstNode): string | undefined;
 
@@ -244,10 +263,21 @@ export interface NameProvider extends LangiumNameProvider {
    /**
     * Find a unique name for a new node within `container`, using `base`
     * as a stem. Walks the AST subtree rooted at `container` and avoids
-    * names already used by `$type === type` nodes there. Default
-    * generates `${base}1`, `${base}2`, ... until an unused value is
-    * found. Used by create-element operation handlers when the
-    * uniqueness scope is one AST subtree.
+    * names already held there by nodes of `type` or of any subtype of it,
+    * as `AstReflection.isSubtype` reports. Default generates `${base}1`,
+    * `${base}2`, ... until an unused value is found. Used by create-element
+    * operation handlers when the uniqueness scope is one AST subtree.
+    *
+    * Subtype-closed rather than `$type`-exact, because a name space shared by
+    * several concrete types is named by their common supertype and by no
+    * concrete type at all — the shape a cross-reference whose target type is
+    * that supertype produces. An exact filter finds no collisions for such a
+    * call and returns the proposal unchanged, which a caller cannot tell from
+    * a name that was genuinely free.
+    * {@link NameProvider.findNextDocumentQualifiedName} and
+    * {@link NameProvider.findNextProjectQualifiedName} resolve `type` the same
+    * way, through `IndexManager.allElements`, so one type argument does not
+    * mean different sets at different tiers.
     */
    findNextName(type: string, base: string, container: AstNode): string;
 
@@ -305,6 +335,9 @@ export class DefaultNameProvider implements NameProvider {
     * document's lifetime. Evicted automatically when Langium rebuilds
     * the document.
     *
+    * So a built node renamed in memory reads its old name until the rebuild,
+    * as {@link NameProvider.getDocumentQualifiedName} warns.
+    *
     * Only cached when the computed result is a defined string — `undefined`
     * results re-evaluate on each call (cheap path: `getOwnName` returns
     * undefined for unnamed nodes, no chain walk needed).
@@ -313,7 +346,9 @@ export class DefaultNameProvider implements NameProvider {
    /**
     * Per-document memo for {@link getProjectQualifiedName} results.
     * Sibling of {@link documentQualifiedNameCache}; covers the additional
-    * project-reference-name lookup the project-qualified variant performs.
+    * project-reference-name lookup the project-qualified variant performs,
+    * and goes stale on an in-memory rename the same way, as
+    * {@link NameProvider.getDocumentQualifiedName} warns.
     *
     * **Project-rename caveat.** If `Project.referenceName` mutates without
     * a corresponding document rebuild, cached entries become stale. Adopters
@@ -450,8 +485,8 @@ export class DefaultNameProvider implements NameProvider {
     * qualified names.
     *
     * **Within-document references stay keyed by bare names** via
-    * `HydraniumScopeComputation.addLocalSymbol`, which explicitly calls
-    * {@link getOwnName} when populating the local-symbols map (bypassing
+    * `HydraniumScopeComputation.addLocalSymbolByOwnName`, which explicitly
+    * calls {@link getOwnName} when populating the local-symbols map (bypassing
     * Langium's default that goes through this `getName`). The
     * separation lets `getName` carry the workspace-unique form for the
     * linker without forcing qualified names into the per-document
@@ -486,8 +521,9 @@ export class DefaultNameProvider implements NameProvider {
 
    findNextName(type: string, base: string, container: AstNode): string {
       const proposal = base.replaceAll(this.nameSeparator, '_');
+      const reflection = this.services.shared.AstReflection;
       const knownNames = AstUtils.streamAst(container)
-         .filter(node => node.$type === type)
+         .filter(node => reflection.isSubtype(node.$type, type))
          .map(node => this.getOwnName(node))
          .nonNullable()
          .toArray();

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

@@ -10,14 +10,36 @@
 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."
 );
-import { type ServerLanguageServices } from '../language-module.js';
-import { type ValidationCheckContribution, type ValidationCheckRegistry } from '../validation/validation-contribution.js';
-import type { NameProvider } from './name-provider.js';
 
 /**
  * Per-node validation check: flag name-bearing AST nodes whose name

package/src/langium/project/abstract-project-manager.ts

@@ -7,18 +7,19 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred, type Project, type Tracer, UNQUALIFIED_PROJECT_REFERENCE } from '@hydranium/protocol';
+import { Deferred, type Project, type Tracer, UNQUALIFIED_PROJECT_REFERENCE, describeErrorWithStack } from '@hydranium/protocol';
 import {
    type AstNode,
    AstUtils,
    type DocumentBuilder,
+   DocumentState,
    type FileSystemProvider,
    type LangiumDocument,
    type LangiumDocuments,
    type URI,
    UriUtils
 } from '@hydranium/langium';
-import { Disposable } from 'vscode-languageserver';
+import { CancellationToken, Disposable } from 'vscode-languageserver';
 import type { WorkspaceFolder } from 'vscode-languageserver-types';
 import type { LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
@@ -225,7 +226,7 @@ export abstract class AbstractProjectManager<TProject extends Project = Project>
       try {
          entries = await this.fileSystemProvider.readDirectory(folder);
       } catch (error) {
-         this.tracer.warn(`Failed to read directory ${folder.toString()}: ${error}`);
+         this.tracer.warn(`Failed to read directory ${folder.toString()}: ${describeErrorWithStack(error)}`);
          return;
       }
       for (const entry of entries) {
@@ -377,6 +378,13 @@ export abstract class AbstractProjectManager<TProject extends Project = Project>
    protected async loadDescriptor(uri: URI): Promise<TProject | undefined> {
       try {
          const document = await this.langiumDocuments.getOrCreateDocument(uri);
+         if (document.state < DocumentState.Parsed) {
+            // `onUpdate` fires before the build parses, so the AST is still the previous edit's.
+            // The state is restored so the build still runs, and notifies, its own parse phase.
+            const state = document.state;
+            await this.services.workspace.LangiumDocumentFactory.update(document, CancellationToken.None);
+            document.state = state;
+         }
          const project = await this.parseProjectDescriptor(uri, document);
          if (project) {
             this.projects.set(project.id, project);
@@ -387,7 +395,7 @@ export abstract class AbstractProjectManager<TProject extends Project = Project>
          }
          return project;
       } catch (error) {
-         this.tracer.error(`Failed to parse ${this.conceptName()} descriptor at ${uri.toString()}: ${error}`);
+         this.tracer.error(`Failed to parse ${this.conceptName()} descriptor at ${uri.toString()}: ${describeErrorWithStack(error)}`);
          return undefined;
       }
    }
@@ -612,7 +620,7 @@ export abstract class AbstractProjectManager<TProject extends Project = Project>
          try {
             listener(event);
          } catch (error) {
-            this.tracer.error(`Project change listener failed: ${error}`);
+            this.tracer.error(`Project change listener failed: ${describeErrorWithStack(error)}`);
          }
       }
    }

package/src/langium/project/project-change-event.ts

@@ -28,8 +28,8 @@ import type { URI } from '@hydranium/langium';
  * - {@link affectedDocuments} lists URIs whose reachable scope changed. The
  *   default cascade plumbing in `HydraniumWorkspaceManager` subscribes to
  *   this event and re-runs `DocumentBuilder.resetToState` for each entry,
- *   which the next build cycle picks up. Consumers can subscribe
- *   independently for other reactions.
+ *   which the build of the update that changed the descriptor picks up.
+ *   Consumers can subscribe independently for other reactions.
  */
 export interface ProjectChangeEvent<TProject extends Project = Project> {
    /** Ids of projects newly registered since the last event. */