@hydranium/core 1.0.0-next.33 → 1.0.0-next.331

package/src/langium/scope/scope-extension-service.ts

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNode, AstUtils, type LangiumDocument, MapScope, type Scope, StreamScope, stream } from '@hydranium/langium';
+import { type AstNode, AstUtils, type LangiumDocument } from '@hydranium/langium';
 import { type Disposable } from 'vscode-languageserver';
-import { type Tracer } from '@hydranium/protocol';
+import { Format, Logger, type ProfileRecord, type ProfileSession, type Tracer } from '@hydranium/protocol';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerLanguageServices } from '../language-module.js';
 import { Registry, type RegistryItem } from '../../util/registry.js';
@@ -49,8 +49,7 @@ export interface ScopeDescriptionAcceptor {
     * descriptions are constructed ahead of time, to avoid per-query
     * allocation. The pushed description's `tier` must be `'local'` or
     * `'universal'`; a description of any other tier is silently dropped,
-    * because the per-tier query methods only return descriptions matching
-    * the tier they were asked for.
+    * because {@link ScopeExtensionDescriptions} holds only those two.
     */
    push(description: TieredAstNodeDescription): void;
 }
@@ -87,38 +86,32 @@ export interface ScopeExtension extends RegistryItem {
    addDescriptions(context: AstNode, referenceType: string, document: LangiumDocument, accept: ScopeDescriptionAcceptor): void;
 }
 
+/** The scope-extension descriptions for one reference, split by tier. */
+export interface ScopeExtensionDescriptions {
+   readonly local: readonly TieredAstNodeDescription[];
+   readonly universal: readonly TieredAstNodeDescription[];
+}
+
 /**
  * Public contract for the per-language scope-extension service. Extends
  * the {@link ScopeExtensionRegistry} (the imperative `register` surface
- * contributions use) with the per-tier query methods called cross-class
- * from `HydraniumScopeProvider`'s `layerLocalExtension` /
- * `layerUniversalExtension` helpers, which layer scope-extension
- * contributions around the cached project chain.
- *
- * Adopter overrides go through {@link DefaultScopeExtensionService}; the
- * interface keeps the public API stable while internals
- * (`collectExtensionDescriptions` walk) stay `protected` on the default
- * class.
+ * contributions use) with the query `HydraniumScopeProvider` builds its
+ * extension tiers from.
  */
 export interface ScopeExtensionService extends ScopeExtensionRegistry {
    /**
-    * Layer this language's `local`-tier scope-extension descriptions on
-    * top of `outerScope` for the given reference type. Returns
-    * `outerScope` unchanged when no extension contributes a `local`-tier
-    * description for the type (zero-cost common path).
+    * Run every extension registered for `referenceType` once against
+    * `context`, and answer its descriptions by tier. A caller that needs
+    * both tiers takes them from one call: a call per tier runs every
+    * extension twice.
     */
-   getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
-   /**
-    * Layer this language's `universal`-tier scope-extension descriptions
-    * BELOW `outerScope` for the given reference type. Returns `outerScope`
-    * unchanged when no extension contributes a `universal`-tier
-    * description for the type.
-    */
-   getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope;
+   getDescriptions(referenceType: string, context: AstNode): ScopeExtensionDescriptions;
 }
 
 export type ScopeExtensionServiceOptions = LogNameOptions;
 
+const NO_DESCRIPTIONS: ScopeExtensionDescriptions = { local: [], universal: [] };
+
 /**
  * Default {@link ScopeExtensionService} implementation. Per-language
  * registry for dynamic scope contributions: extra resolvable descriptions
@@ -128,13 +121,19 @@ export type ScopeExtensionServiceOptions = LogNameOptions;
  * separate from the query-time scope-resolution concern (which only reads).
  *
  * Lives in the per-language `references` group alongside `ScopeProvider`,
- * which consumes the per-tier query methods ({@link getLocalExtensionScope}
- * / {@link getUniversalExtensionScope}). Designed as a base class; adopters
+ * which consumes {@link getDescriptions}. Designed as a base class; adopters
  * extend it and call `register` in their constructor.
+ *
+ * At `debug`, each extension's calls and self-time go into one profile
+ * session, reported when a build starts and when it ends. A report thus
+ * covers one build, validation included, or the calls made between two
+ * builds, such as a reference picker's.
  */
 export class DefaultScopeExtensionService implements ScopeExtensionService {
    protected readonly scopeExtensions = new Registry<ScopeExtension>();
    protected readonly tracer: Tracer;
+   /** Open from the first profiled call until {@link reportProfile}. */
+   protected profileSession?: ProfileSession;
 
    constructor(
       protected readonly services: ServerLanguageServices,
@@ -150,6 +149,10 @@ export class DefaultScopeExtensionService implements ScopeExtensionService {
       for (const contribution of Object.values(contributions)) {
          contribution.registerScopeExtensions(this);
       }
+      // Optional for the same reason: a stub tree may carry no builder.
+      const builder = services.shared.workspace.DocumentBuilder;
+      builder?.onUpdate(() => this.reportProfile());
+      builder?.onBuildEnded(() => this.reportProfile());
    }
 
    /**
@@ -162,46 +165,58 @@ export class DefaultScopeExtensionService implements ScopeExtensionService {
       return this.scopeExtensions.register(extension);
    }
 
-   getLocalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope {
-      const local = this.collectExtensionDescriptions(referenceType, context, 'local');
-      if (local.length === 0) {
-         return outerScope;
-      }
-      return new StreamScope(stream(local), outerScope);
-   }
-
-   getUniversalExtensionScope(referenceType: string, context: AstNode, outerScope: Scope): Scope {
-      const universal = this.collectExtensionDescriptions(referenceType, context, 'universal');
-      if (universal.length === 0) {
-         return outerScope;
-      }
-      return new StreamScope(outerScope.getAllElements(), new MapScope(universal));
-   }
-
    /**
-    * Walk this language's registered scope extensions matching
-    * `referenceType` and collect descriptions of the requested `tier`.
-    * `push`-ed descriptions of other tiers are silently dropped here —
-    * the per-tier query methods only return descriptions matching their
-    * tier. (`local` and `universal` are the only acceptor entry points;
-    * `push` is the escape hatch for pre-built descriptions and is the
-    * only path that could carry other tiers.)
+    * Holds the profile wrap, which an override would have to copy; to change
+    * which extensions run, override {@link extensionsFor}.
     */
-   protected collectExtensionDescriptions(
-      referenceType: string,
-      context: AstNode,
-      tier: 'local' | 'universal'
-   ): TieredAstNodeDescription[] {
-      const extensionsForType = this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+   getDescriptions(referenceType: string, context: AstNode): ScopeExtensionDescriptions {
+      const extensionsForType = this.extensionsFor(referenceType, context);
       if (extensionsForType.length === 0) {
-         return [];
+         return NO_DESCRIPTIONS;
       }
       const document = AstUtils.getDocument(context);
       const collected: TieredAstNodeDescription[] = [];
       const accept = createScopeDescriptionAcceptor(collected, this.services.workspace.AstNodeDescriptionProvider);
+      const session = Logger.isLevelEnabled('debug') ? (this.profileSession ??= this.tracer.profile('scope-extension')) : undefined;
       for (const extension of extensionsForType) {
-         extension.addDescriptions(context, referenceType, document, accept);
+         if (session) {
+            session.scope(extension.id, () => extension.addDescriptions(context, referenceType, document, accept));
+         } else {
+            extension.addDescriptions(context, referenceType, document, accept);
+         }
+      }
+      return {
+         local: collected.filter(description => description.tier === 'local'),
+         universal: collected.filter(description => description.tier === 'universal')
+      };
+   }
+
+   /** The extensions that run for one reference: by default, those registered for `referenceType`. */
+   protected extensionsFor(referenceType: string, _context: AstNode): ScopeExtension[] {
+      return this.scopeExtensions.all().filter(extension => extension.referenceTypes.includes(referenceType));
+   }
+
+   /**
+    * Report the profile session, if one is open, and start the next one fresh:
+    * one line per extension, its calls and self-time. Not a share of the
+    * session's time, which runs from the first call to the report and so takes
+    * in whatever happened between the calls.
+    */
+   protected reportProfile(): void {
+      const session = this.profileSession;
+      this.profileSession = undefined;
+      for (const record of session?.records() ?? []) {
+         this.tracer.debug(this.formatProfileRecord(record));
       }
-      return collected.filter(description => description.tier === tier);
+   }
+
+   /**
+    * The log line of one extension's {@link reportProfile} entry. It names the
+    * language: each has its own session, and an extension id is unique only
+    * within its language.
+    */
+   protected formatProfileRecord(record: ProfileRecord): string {
+      const language = this.services.LanguageMetaData.languageId;
+      return `[profile scope-extension ${language}] ${record.id} ×${record.count} ${Format.elapsed(record.selfMs)}`;
    }
 }

package/src/langium/scope/scoped-ast-node-description.ts

@@ -157,9 +157,7 @@ export function isUniversalTier(description: AstNodeDescription): description is
  * URI's project, the public-tier sibling belonging to that
  * same project is redundant (the project-tier sibling under a shorter
  * name is already in scope) and should be hidden from completion /
- * linking. The framework's
- * `HydraniumScopeProvider.bucketFor` uses this
- * predicate to enforce the own-project canonical filter on the typed scope path.
+ * linking.
  *
  * `projectId` accepts `string | undefined` for adopter-call-site
  * ergonomics: when the source has no resolvable project (standalone

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;
 }
 
 /**
@@ -110,8 +100,11 @@ export interface AbstractSerializerOptions extends LogNameOptions {
  * **Extension points** (override in a subclass):
  * - {@link serializeReferenceText} — extract the textual form of a
  *   cross-reference; defaults to the value's `$refText`.
+ * - {@link formatString} — quote a string, as a primitive or a reference, for
+ *   the grammar's string terminal; the one override for a grammar whose
+ *   terminal or value converter differs from Langium's default.
  * - {@link formatReferenceValue} — format a cross-reference value for emission;
- *   defaults to `JSON.stringify`.
+ *   defaults to {@link formatString}.
  * - {@link serializeCustomValue} — type-specific serialization for values
  *   that don't fit the generic paths. Runs after all reference detection, so
  *   references never reach this hook. Returns `undefined` to fall through to
@@ -124,6 +117,25 @@ export abstract class AbstractSerializer<
    TAst extends AstNode = AstNode,
    TTransfer extends TransferElement = TransferElement
 > implements Serializer<TAst, TTransfer> {
+   /**
+    * The escapes {@link formatString} writes, read through the subclass, so a
+    * grammar adding one overrides this table alone. Langium's
+    * `ValueConverter.convertString` decodes the short escapes here and reads
+    * any other escaped character as itself, which is how `\\` and `\"` read
+    * back, and why a `\u` escape would read back as `u`.
+    */
+   protected static readonly STRING_ESCAPES: ReadonlyMap<string, string> = new Map([
+      ['\\', '\\\\'],
+      ['"', '\\"'],
+      ['\b', '\\b'],
+      ['\f', '\\f'],
+      ['\n', '\\n'],
+      ['\r', '\\r'],
+      ['\t', '\\t'],
+      ['\v', '\\v'],
+      ['\0', '\\0']
+   ]);
+
    protected readonly reflection: AstReflection;
    protected readonly tracer: Tracer;
 
@@ -139,29 +151,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);
    }
 
    /**
@@ -426,29 +429,42 @@ export abstract class AbstractSerializer<
    }
 
    /**
-    * Format a cross-reference value for emission. Defaults to `JSON.stringify`.
-    * Override to apply language-specific reference quoting — e.g. an
-    * id-reference formatter that mirrors the grammar's id convention.
+    * Format a cross-reference value for emission. Defaults to
+    * {@link formatString}. Override to apply language-specific reference
+    * quoting — e.g. an id-reference formatter that mirrors the grammar's id
+    * convention.
     *
     * Returns {@link MaybePromise} so adopters with async formatting needs
     * (remote schema lookup, external canonical-id resolution) can return a
     * `Promise<string>`. Sync overrides remain valid.
     */
    protected formatReferenceValue(value: string): MaybePromise<string> {
-      return JSON.stringify(value);
+      return this.formatString(value);
    }
 
    /**
-    * Format a primitive value (string, number, boolean) for emission. Defaults
-    * to `JSON.stringify`, which quotes strings, formats numbers/booleans, and
-    * is valid both as a YAML scalar and a JSON value.
+    * Format a primitive value (string, number, boolean) for emission. A string
+    * goes through {@link formatString}, any other value through
+    * `JSON.stringify`.
     *
     * Returns {@link MaybePromise} so adopters with async formatting needs
     * (e.g. delegating to `prettier.format` for a specific value class) can
     * return a `Promise<string>`.
     */
    protected formatPrimitive(value: unknown): MaybePromise<string> {
-      return JSON.stringify(value);
+      return typeof value === 'string' ? this.formatString(value) : JSON.stringify(value);
+   }
+
+   /**
+    * Quote a string, as a primitive or a reference, for its reader: the
+    * grammar's string terminal and value converter. Defaults to the inverse of
+    * Langium's default `STRING` terminal and converter: double quotes, `\` and
+    * `"` escaped, the converter's short escapes, every other character as it
+    * is. A grammar with another terminal or converter overrides this.
+    */
+   protected formatString(value: string): string {
+      const escapes = (this.constructor as typeof AbstractSerializer).STRING_ESCAPES;
+      return `"${Array.from(value, char => escapes.get(char) ?? char).join('')}"`;
    }
 
    /**

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

@@ -224,13 +224,24 @@ export class JsonSerializer<TAst extends AstNode = AstNode, TTransfer extends Tr
     * encodings.
     */
    protected override formatReferenceValue(value: string): MaybePromise<string> {
+      const quoted = this.formatString(value);
       if (this.referenceEncoding === 'string') {
-         return JSON.stringify(value);
+         return quoted;
       }
       if (this.compact) {
-         return `{${JSON.stringify('$ref')}:${JSON.stringify(value)}}`;
+         return `{${JSON.stringify('$ref')}:${quoted}}`;
       }
-      return `{ ${JSON.stringify('$ref')}: ${JSON.stringify(value)} }`;
+      return `{ ${JSON.stringify('$ref')}: ${quoted} }`;
+   }
+
+   /**
+    * `JSON.stringify`, so the output stays valid JSON for other tools. The
+    * grammar reading it back needs a terminal and value converter that decode
+    * the `\u` escape JSON writes for a control character without a short
+    * escape; Langium's default converter reads `\u0001` as `u0001`.
+    */
+   protected override formatString(value: string): string {
+      return JSON.stringify(value);
    }
 
    protected composeObject(entries: readonly (readonly [string, string])[], indentationLevel: number): string {

package/src/langium/serialization/serializer.ts

@@ -34,7 +34,7 @@ import type { AstNode } from '@hydranium/langium';
  * Neither method requires the input to be the grammar root — the walker is
  * recursive and shape-agnostic, so any element from either tree serializes
  * correctly. Callers typically pass a root (that's what
- * `ModelService.serialize`
+ * `DefaultModelService.serialize`
  * and the GLSP source-model flows hand in), but sub-tree serialization works
  * for unit tests, snippet rendering, and tooling.
  */

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

@@ -87,6 +87,10 @@ export interface YamlSerializerOptions extends AbstractSerializerOptions {
  * points. YAML's one addition is unquoted-terminal emission, handled by its
  * {@link serializeCustomValue} override driven by
  * {@link YamlSerializerOptions.unquotedProperties}.
+ *
+ * The grammar, not a YAML parser, reads its quoted strings back, so a control
+ * character without a short escape is written raw, which a strict YAML parser
+ * such as js-yaml refuses.
  */
 export class YamlSerializer<TAst extends AstNode = AstNode, TTransfer extends TransferElement = TransferElement> extends AbstractSerializer<
    TAst,

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

@@ -10,9 +10,11 @@
 import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
 import type { ServerLocale } from '../locale/server-locale.js';
-import type { ServerMessageRenderer } from '../messages/renderer.js';
-import type { SelfSaveRegistry } from '../documents/self-save-registry.js';
-import type { WritableFileSystemProvider } from '../documents/ast-document-manager.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';
@@ -21,6 +23,7 @@ import type { ProjectManager } from './project/project-manager.js';
 import type { ExtendedServiceRegistry } from './service-registry.js';
 import type { DocumentUriPolicy } from './workspace/document-uri-policy.js';
 import type { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
+import type { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
 import type { AdditionalDocumentContribution } from './workspace/additional-document-contribution.js';
 
 /**
@@ -31,12 +34,12 @@ import type { AdditionalDocumentContribution } from './workspace/additional-docu
  * {@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, the
- * {@link ServerMessageRenderer} and the {@link ServerLocale} it renders in,
+ * {@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
@@ -66,7 +69,7 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
     * shared tier with no workspace dependency, because all three heads'
     * messages pass through it.
     */
-   MessageRenderer: ServerMessageRenderer;
+   MessageRenderer: MessageRenderer;
    /** The locale an init handed the server, for whoever renders in it. */
    ServerLocale: ServerLocale;
    /**
@@ -92,12 +95,18 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
       // only through this narrowing — a scope provider querying a URI before
       // the file exists is the caller that needs it.
       /* override */ LangiumDocuments: HydraniumDocumentRegistry;
+      // Same, for the builder: only the framework's has `onBuildEnded`, which a
+      // per-build report needs because Langium's phases stay silent for a
+      // build that validates nothing.
+      /* override */ DocumentBuilder: HydraniumDocumentBuilder;
       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.'
+      );
+   }
+}