@hydranium/core 1.0.0-next.23 → 1.0.0-next.230

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

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { asMutable, type Clock, Debouncer, Format, type Tracer } from '@hydranium/protocol';
+import { asMutable, type Clock, Debouncer, Format, type Tracer, UNRECORDED_VERSION } from '@hydranium/protocol';
 import {
    type AstNode,
    AstUtils,
@@ -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;
 
@@ -181,8 +185,10 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
 }
 
 /**
- * Residency policy that reclaims memory by shedding the concrete syntax tree
- * (CST) of closed documents while keeping their AST resident. Each build refreshes
+ * 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.
+ *
+ * Each build refreshes
  * the idle window of the documents in its batch; when a closed, sheddable
  * document's window elapses, every AST node's `$cstNode` and every reference's
  * `$refNode` are nulled, and the CST root, `Range`s and `Position`s become
@@ -225,9 +231,25 @@ 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`.
  */
-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 +299,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 +309,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 +375,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();
       }
@@ -383,6 +405,15 @@ export class CstResidencyService {
       if (root === undefined || root.$cstNode === undefined) {
          return 0;
       }
+      // Readers of the parsed text, the `'text-diagnostics'` fingerprint among
+      // them, otherwise see none once the CST is gone. Recorded in the ledger
+      // directly: no root is produced, and reconciling it with the store would
+      // step a closed document's sequence for a root behind its text.
+      const ledger = this.services.workspace.ModelLedger;
+      const version = ledger.versionOf(root);
+      if (version !== UNRECORDED_VERSION) {
+         ledger.record(root, version, ledger.textOf(root));
+      }
       let cleared = 0;
       for (const node of AstUtils.streamAst(root)) {
          if (node.$cstNode) {

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

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

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

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

package/src/langium/service-registry.ts

@@ -209,6 +209,19 @@ export class ExtendedServiceRegistry<
       return super.getServices(arg);
    }
 
+   /**
+    * Every registered language's services, typed as `TServices` like the
+    * lookups here rather than as Langium's base shape, so a sweep of the whole
+    * set reaches what a URI or a typed handle would have given it.
+    *
+    * The cast is sound because {@link register} is the only way a language
+    * enters and takes `TServices`; the inherited accessor is typed to Langium's
+    * base, which is the only reason one is needed.
+    */
+   override get all(): readonly TServices[] {
+      return super.all as readonly TServices[];
+   }
+
    /**
     * Lookup by anything that identifies a document — an AST node (routed by
     * the document it lives in), a `URI`, or a URI string. `undefined` when the
@@ -255,9 +268,13 @@ export class ExtendedServiceRegistry<
     * inherited Langium semantics, which throws on miss). Used for
     * dynamically-routed lookups where the language id comes from
     * external input.
+    *
+    * The cast is sound because {@link register} is the only way a language
+    * enters and takes `TServices`; `languageIdMap` is inherited and typed to
+    * Langium's base, which is the only reason one is needed.
     */
-   getServicesById(languageId: string): LangiumCoreServices | undefined {
-      return this.languageIdMap.get(languageId);
+   getServicesById(languageId: string): TServices | undefined {
+      return this.languageIdMap.get(languageId) as TServices | undefined;
    }
 
    /**
@@ -299,6 +316,28 @@ export class ExtendedServiceRegistry<
       return owners.length === 1 ? owners[0] : undefined;
    }
 
+   /**
+    * The language the strongest signal given names: a declared `languageId`,
+    * then `target`'s document, then the only registered language, then the sole
+    * producer of `type`. `undefined` when none answers, which leaves the
+    * fallback to the caller, since it differs per caller.
+    *
+    * A declared id comes first because every later signal is inferred, and an
+    * inference must not override a caller that said which grammar it means.
+    */
+   getLanguageFor(hint: { readonly languageId?: string; readonly target?: LanguageTarget; readonly type?: string }): TServices | undefined {
+      const declared = hint.languageId === undefined ? undefined : this.getServicesById(hint.languageId);
+      const located = declared ?? this.getServicesFor(hint.target);
+      if (located) {
+         return located;
+      }
+      const all = this.all;
+      if (all.length === 1) {
+         return all[0];
+      }
+      return hint.type === undefined ? undefined : this.soleServicesByType(hint.type);
+   }
+
    /**
     * Drop the memoised type index, so a language registered after the first
     * type lookup is accounted for. The reason this index belongs on the

package/src/langium/shared-services.ts

@@ -9,8 +9,13 @@
 
 import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
-import type { SelfSaveRegistry } from '../documents/self-save-registry.js';
-import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import type { ServerLocale } from '../locale/server-locale.js';
+import type { MessageRenderer } from '../messages/renderer.js';
+import type { SelfSaveRegistry } from './workspace/self-save-registry.js';
+import type { ModelLedger } from '../documents/model-ledger.js';
+import type { VersionSyncService } from '../documents/version-sync-service.js';
+import type { WritableFileSystemProvider } from './workspace/file-system-provider.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,12 +32,13 @@ 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
- * {@link DocumentUriPolicy}.
+ * {@link BuildPhasePassService}, {@link CstResidencyService},
+ * {@link DocumentUriPolicy}, {@link ModelLedger} and {@link VersionSyncService}.
  *
  * Declared structurally (interface extends + intersection on nested slots)
  * so the full `ServerSharedServices` and any consumer-extended variant
@@ -57,6 +63,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,12 +89,19 @@ 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;
       BuildPhasePassService: BuildPhasePassService;
       CstResidencyService: CstResidencyService;
       DocumentUriPolicy: DocumentUriPolicy;
+      ModelLedger: ModelLedger;
+      VersionSyncService: VersionSyncService;
    };
 }
 

package/src/langium/single-langium-copy.ts

@@ -0,0 +1,42 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { AbstractAstReflection, type AstReflection } from '@hydranium/langium';
+
+/**
+ * Fail fast when `reflection` extends `AbstractAstReflection` from a second
+ * copy of `langium`, which the files `langium-cli` generates run on: a second
+ * install, or one install a bundler or test runner loads twice.
+ *
+ * A reflection whose prototype chain misses this copy's base is taken to come
+ * from another copy when it carries the `subtypes` and `allSubtypes` fields that
+ * base creates, which `AstReflection` does not declare. Fields rather than the
+ * class name, because bundlers and minifiers rename classes; a hand-written
+ * reflection passes unless it declares both fields itself.
+ */
+export function assertSingleLangiumCopy(
+   reflection: AstReflection,
+   subject: () => string = () => `the shared AstReflection (${reflection.constructor?.name ?? 'no constructor'})`
+): void {
+   if (reflection instanceof AbstractAstReflection) {
+      return;
+   }
+   if (Object.hasOwn(reflection, 'subtypes') && Object.hasOwn(reflection, 'allSubtypes')) {
+      throw new Error(
+         `[hydranium] ${subject()} extends \`AbstractAstReflection\` from another instance of \`langium\` than ` +
+            'the one `@hydranium/langium` loads, a second physical copy or one install loaded twice, so the generated ' +
+            'code runs on one and the framework on the other. Values Langium compares by identity, such as its ' +
+            'cancellation signal, are not recognised across the two. `npm explain langium` lists each installed copy ' +
+            'and what requires it. If your package resolves another version, declare `langium` at the version ' +
+            '`@hydranium/langium` pins and reinstall from scratch, without the lockfile; in a workspace, declare the ' +
+            'same pins in the root as well. If a test runner or bundler inlines `langium` but not `@hydranium/*`, ' +
+            'load both the same way.'
+      );
+   }
+}