@hydranium/core 1.0.0-next.25 → 1.0.0-next.251

package/src/documents/version-sync-service.ts

@@ -0,0 +1,267 @@
+/********************************************************************************
+ * 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 { DocumentState, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type Tracer, UNRECORDED_VERSION } from '@hydranium/protocol';
+import { Disposable, Emitter, type Event } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import { type ServerSharedServices } from '../langium/module.js';
+import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
+import { HydraniumTextDocuments } from './hydranium-text-documents.js';
+
+/** A build {@link VersionSyncService.requestRecoveryBuild} schedules. */
+export interface RecoveryBuildRequest {
+   /** Remove the document instead of building it. */
+   readonly deleted?: boolean;
+   /** Staged for the build, as `HydraniumDocumentBuilder.scheduleUpdate` takes it. */
+   readonly reason?: string;
+   /** Asked again inside the lock, where a build that ran meanwhile may have made the request moot. */
+   readonly stillNeeded: () => boolean;
+   /** Build even while a {@link VersionSyncService.registerDeferredBuilds} check holds the URI back. */
+   readonly ignoreDeferred?: boolean;
+}
+
+/**
+ * Keeps each workspace root's `ModelLedger` record in step with the
+ * text store, and owns every build that syncs a root to its text or recovers
+ * one a build left behind.
+ */
+export interface VersionSyncService {
+   /**
+    * Report a root a factory, registry, integrity repair or other producer
+    * made. Below `Parsed` it is marked a placeholder. Otherwise `origin.version`,
+    * the store's version read before the parse, is recorded; a registered
+    * document is then reconciled with the store, re-versioned and recorded at
+    * the store's version of its text, built if behind, and announced on
+    * {@link onDidRecordModel}. `origin.text` stands for a root whose CST is not
+    * the text it describes.
+    */
+   modelProduced(document: LangiumDocument, origin?: { version?: number; text?: string }): void;
+   /**
+    * Build `uri` from a `WorkspaceLock` read, so the build queues behind a
+    * running one rather than cancelling it. Requests made while one for `uri`
+    * is pending share its next build. Resolves `true` once a build that carried
+    * this request completed, or once a check before a build found it no longer
+    * needed or deferred. A build a later write cancelled does not count: the
+    * request rides the next one. Resolves `false` once builds carrying this
+    * request have failed more often than it may retry, so a caller waiting on
+    * the build can stop. Never rejects.
+    */
+   requestRecoveryBuild(uri: URI, request: RecoveryBuildRequest): Promise<boolean>;
+   /**
+    * Build `uri` unless it is {@link isSyncedTo synced to} `textVersion`, asked
+    * again inside the lock. `undefined` when no build is needed, else the
+    * {@link requestRecoveryBuild} answer.
+    */
+   syncTo(uri: URI, textVersion: number): Promise<boolean> | undefined;
+   /**
+    * Whether `uri`'s root was parsed from text at `textVersion` or later; requests
+    * nothing. A root with no recorded version or a placeholder counts as synced,
+    * since no build records a version for it, and so does a URI with no document.
+    */
+   isSyncedTo(uri: URI, textVersion: number): boolean;
+   /**
+    * Register `isDeferred`, which answers whether its caller holds back a build
+    * of a URI it will request later, as the update handler does for a debounced
+    * editor change. A caller that drops a held change has to leave the URI to
+    * another build.
+    */
+   registerDeferredBuilds(isDeferred: (uri: URI) => boolean): Disposable;
+   /**
+    * Fires for every reconciled root. A cancel cannot skip it, unlike a
+    * `Parsed` phase listener. It can fire inside a build's write lock, so a
+    * listener that requests a build must not await it.
+    */
+   readonly onDidRecordModel: Event<LangiumDocument>;
+}
+
+/** A request waiting in {@link PendingRecoveryBuilds}, with the failed builds that carried it. */
+export interface QueuedRecoveryBuild {
+   readonly request: RecoveryBuildRequest;
+   failures: number;
+   readonly answer: (built: boolean) => void;
+}
+
+/** The requests waiting on one URI's builds in {@link DefaultVersionSyncService}. */
+export interface PendingRecoveryBuilds {
+   readonly queued: QueuedRecoveryBuild[];
+}
+
+/**
+ * Collaborators are resolved per call: the registry and its document factory,
+ * which construct each other, report roots to this service.
+ */
+export class DefaultVersionSyncService implements VersionSyncService {
+   protected readonly tracer: Tracer;
+   protected readonly recordedEmitter = new Emitter<LangiumDocument>();
+   protected readonly deferredBuildChecks = new Set<(uri: URI) => boolean>();
+   protected readonly pendingBuilds = new Map<string, PendingRecoveryBuilds>();
+   /** Retries of each request after a failed build before it is answered `false`. */
+   protected readonly maxBuildRetries: number = 1;
+
+   constructor(
+      protected readonly services: ServerSharedServices,
+      options: LogNameOptions = {}
+   ) {
+      this.tracer = services.Tracer.for(options.logName ?? 'VersionSyncService').trace('instantiated');
+   }
+
+   get onDidRecordModel(): Event<LangiumDocument> {
+      return this.recordedEmitter.event;
+   }
+
+   modelProduced(document: LangiumDocument, origin: { version?: number; text?: string } = {}): void {
+      const workspace = this.services.workspace;
+      const ledger = workspace.ModelLedger;
+      const root = document.parseResult.value;
+      if (document.state < DocumentState.Parsed) {
+         ledger.markPlaceholder(root);
+         return;
+      }
+      if (origin.version !== undefined) {
+         ledger.record(root, origin.version, origin.text);
+      }
+      const store = workspace.TextDocuments;
+      // Unregistered, it is a probe or a load whose registration reports it again.
+      if (!(store instanceof HydraniumTextDocuments) || workspace.LangiumDocuments.getDocument(document.uri) !== document) {
+         return;
+      }
+      const uri = document.uri.toString();
+      // Against the parsed text: the text document may already hold a newer edit.
+      const version = store.reconcileExternalContent(uri, origin.text ?? this.parsedText(document));
+      if (version !== undefined) {
+         if (document.textDocument.version !== version) {
+            // An empty-changes update only re-stamps the version.
+            store.update(document.textDocument, [], version);
+         }
+         ledger.record(root, version, origin.text);
+      }
+      void this.syncTo(document.uri, store.version(uri));
+      this.recordedEmitter.fire(document);
+   }
+
+   syncTo(uri: URI, textVersion: number): Promise<boolean> | undefined {
+      const behind = (): boolean => !this.isSyncedTo(uri, textVersion);
+      return behind() ? this.requestRecoveryBuild(uri, { stillNeeded: behind }) : undefined;
+   }
+
+   requestRecoveryBuild(uri: URI, request: RecoveryBuildRequest): Promise<boolean> {
+      return new Promise<boolean>(answer => {
+         const key = uri.toString();
+         const queued: QueuedRecoveryBuild = { request, failures: 0, answer };
+         const pending = this.pendingBuilds.get(key);
+         if (pending) {
+            // Not dropped: the pending build may have read the text before this request's change.
+            pending.queued.push(queued);
+            return;
+         }
+         const entry: PendingRecoveryBuilds = { queued: [queued] };
+         this.pendingBuilds.set(key, entry);
+         void this.runBuilds(key, uri, entry);
+      });
+   }
+
+   registerDeferredBuilds(isDeferred: (uri: URI) => boolean): Disposable {
+      this.deferredBuildChecks.add(isDeferred);
+      return Disposable.create(() => this.deferredBuildChecks.delete(isDeferred));
+   }
+
+   isSyncedTo(uri: URI, textVersion: number): boolean {
+      const root = this.services.workspace.LangiumDocuments.getDocument(uri)?.parseResult.value;
+      if (root === undefined) {
+         return true;
+      }
+      const ledger = this.services.workspace.ModelLedger;
+      const recorded = ledger.versionOf(root);
+      return recorded === UNRECORDED_VERSION || ledger.isPlaceholder(root) || recorded >= textVersion;
+   }
+
+   /** The text `document`'s root was parsed from, or for a root built without either record or CST, the document's own. */
+   protected parsedText(document: LangiumDocument): string {
+      return this.services.workspace.ModelLedger.textOf(document.parseResult.value) ?? document.textDocument.getText();
+   }
+
+   /**
+    * Run `entry`'s requests, one build per batch, until none is queued, and
+    * answer each. A request a failed build carried is queued again
+    * {@link maxBuildRetries} times, then answered `false`; one a cancelled
+    * build carried is queued again without counting. The entry is dropped
+    * in the same tick as the last check of the queue, so no request lands in
+    * an entry nothing runs any more.
+    */
+   protected async runBuilds(key: string, uri: URI, entry: PendingRecoveryBuilds): Promise<void> {
+      const tracer = this.tracer.withUri(key);
+      const lock = this.services.workspace.WorkspaceLock;
+      // Any other lock resolves a cancelled write as if it had completed, unnoticed.
+      const counting = lock instanceof HydraniumWorkspaceLock ? lock : undefined;
+      while (entry.queued.length > 0) {
+         let carried: QueuedRecoveryBuild[] = [];
+         let build: Promise<void> | undefined;
+         let cancellations: number | undefined;
+         try {
+            // The read waits until no write runs or is queued. It must not await
+            // the build, a write that queues behind it.
+            await lock.read(() => {
+               carried = entry.queued.splice(0);
+               const needed = carried.filter(queued => this.isStillNeeded(uri, queued.request));
+               carried.filter(queued => !needed.includes(queued)).forEach(queued => queued.answer(true));
+               carried = needed;
+               if (needed.length > 0) {
+                  build = this.scheduleBatch(
+                     uri,
+                     needed.map(queued => queued.request)
+                  );
+                  // Read after the build is queued, which cancels the write before it.
+                  cancellations = counting?.writeCancellations;
+               }
+            });
+            await build;
+            // A write cancelled the build, before it ran or while it did.
+            if (cancellations !== undefined && counting?.writeCancellations !== cancellations) {
+               entry.queued.unshift(...carried);
+               continue;
+            }
+            carried.forEach(queued => queued.answer(true));
+         } catch (err: unknown) {
+            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            const retried = carried.filter(queued => queued.failures++ < this.maxBuildRetries);
+            const givenUp = carried.filter(queued => !retried.includes(queued));
+            if (retried.length > 0) {
+               tracer.warn(`Requested build failed; retrying. ${detail}`);
+               entry.queued.unshift(...retried);
+            }
+            if (givenUp.length > 0) {
+               tracer.error(`Requested build failed again; giving up. ${detail}`);
+               givenUp.forEach(queued => queued.answer(false));
+            }
+         }
+      }
+      this.pendingBuilds.delete(key);
+   }
+
+   /** Whether `request` still needs its build, and no deferral it heeds holds it back. Runs inside the lock read. */
+   protected isStillNeeded(uri: URI, request: RecoveryBuildRequest): boolean {
+      return request.stillNeeded() && (request.ignoreDeferred === true || !this.isDeferred(uri));
+   }
+
+   /**
+    * One build for every request of `batch`, removing the document when the
+    * latest of them asks to, as `HydraniumDocumentBuilder.scheduleUpdate`
+    * merges a change and a deletion. Runs inside the lock read.
+    */
+   protected scheduleBatch(uri: URI, batch: readonly RecoveryBuildRequest[]): Promise<void> {
+      const deleted = batch.at(-1)?.deleted === true;
+      const reason = batch.find(request => request.reason !== undefined)?.reason;
+      return this.services.workspace.DocumentBuilder.scheduleUpdate(deleted ? [] : [uri], deleted ? [uri] : [], reason);
+   }
+
+   protected isDeferred(uri: URI): boolean {
+      return [...this.deferredBuildChecks].some(isDeferred => isDeferred(uri));
+   }
+}

package/src/index.ts

@@ -28,12 +28,20 @@ export * from './langium/project/index.js';
 export * from './langium/residency/index.js';
 export * from './langium/scope/index.js';
 export * from './langium/serialization/index.js';
+export * from './langium/trivia/index.js';
 export * from './langium/transfer/index.js';
 export * from './langium/update-rewrite/index.js';
 export * from './langium/validation/index.js';
 export * from './langium/workspace/index.js';
 export * from './langium/service-registry.js';
 export * from './langium/language-types.js';
+export * from './langium/composite-ast-reflection.js';
+export * from './langium/single-langium-copy.js';
 export * from './launcher/index.js';
+export * from './locale/index.js';
+// The renderer only. The `./messages` subpath additionally enumerates this
+// package's own declarations, which the root barrel already re-exports through
+// the modules that raise them.
+export * from './messages/renderer.js';
 export * from './documents/index.js';
 export * from './util/index.js';

package/src/langium/ast-extension/ast-node-builder.ts

@@ -78,15 +78,13 @@ export type AstNodeBuilder<TMap> = <TType extends string & keyof TMap>(
  * AST-interface mapping, so call sites get full inference from the type
  * constant alone — no explicit generic parameter at every call site.
  *
- * Runtime behaviour: reads `reflection.getTypeMetaData(type).properties` and,
- * for every property whose metadata carries a `defaultValue`, pre-fills the
- * result before merging the caller's `init`. Array defaults are materialised
- * as a fresh `[]` per call (never shared with the metadata's array instance,
- * which downstream callers mutate); scalar defaults (`false`, `0`, `''`, …)
- * are copied as-is since they're immutable. Grammar-generated containment
- * lists and `?=`-style boolean flags therefore default automatically;
- * TS-augmented fields (declared via `declare module './generated/ast.js'`)
- * are unaffected by the runtime defaulting but remain typed at call sites.
+ * Runtime behaviour: pre-fills every grammar-declared default (see
+ * {@link withTypeDefaults}) before merging the caller's `init`, so containment
+ * lists and `?=`-style boolean flags default automatically. TS-augmented fields
+ * (declared via `declare module './generated/ast.js'`) are unaffected by the
+ * runtime defaulting but remain typed at call sites.
+ *
+ * Use {@link buildAstNode} instead when the type name is only known at runtime.
  *
  * The init shape only relaxes array-typed fields to optional (via
  * {@link ArrayKeys}) — there is no equivalent structural signal for "this
@@ -101,19 +99,7 @@ export function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuil
       init: AstNodeInit<Extract<TMap[TType], AstNode>>,
       extras?: Record<string, unknown>
    ): Extract<TMap[TType], AstNode> {
-      const meta = reflection.getTypeMetaData(typeConstant.$type);
-      const result: Record<string, unknown> = { $type: typeConstant.$type };
-      if (meta?.properties) {
-         for (const [propName, propInfo] of Object.entries(meta.properties)) {
-            const defaultValue = propInfo.defaultValue;
-            if (defaultValue === undefined) {
-               continue;
-            }
-            // Arrays are duplicated so each node carries its own mutable instance;
-            // scalars are immutable and safe to copy by reference.
-            result[propName] = Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
-         }
-      }
+      const result = withTypeDefaults(reflection, typeConstant.$type);
       Object.assign(result, init);
       if (extras) {
          // Extras win over init: this is the explicit escape hatch, so when a
@@ -123,3 +109,61 @@ export function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuil
       return result as unknown as Extract<TMap[TType], AstNode>;
    };
 }
+
+/**
+ * Build a node whose type is only known as a RUNTIME string.
+ *
+ * The typed {@link makeAstNodeBuilder} cannot express this: its `TMap` generic
+ * resolves the AST interface from a `$type` literal, and a type name that
+ * arrives over the wire — a protocol-layer reference request naming a node that
+ * does not exist yet — has no literal to resolve from. Callers that DO know the
+ * type at compile time want the typed builder, which checks their mandatory
+ * fields; this one checks nothing beyond the reflection lookup.
+ *
+ * Applies the same reflection-driven defaulting, so a node built here carries
+ * grammar-declared containment arrays rather than leaving them `undefined`. An
+ * unknown type name yields a node with `$type` and whatever `init` supplied,
+ * because reflection answers no metadata for it and refusing would turn a
+ * permissive lookup into a throw at a call site that can only guess.
+ *
+ * **The `type` argument is authoritative: `init` cannot rebind `$type`.** The
+ * typed builder gets this for free — `AstNodeInit` omits `$type`, so a call site
+ * cannot reach it — but here `init` is loosely typed, and the case that needs
+ * the guarantee is RETYPING: a caller spreading an existing node to produce one
+ * of a different type (`{ ...source }`) carries the SOURCE's `$type` in, which
+ * would silently win over the type actually requested and hand back a node of
+ * the wrong type with no error anywhere.
+ */
+export function buildAstNode<TAst extends AstNode = AstNode>(
+   reflection: AstReflection,
+   type: string,
+   init?: Partial<AstNode> & Record<string, unknown>
+): TAst {
+   const result = withTypeDefaults(reflection, type);
+   if (init) {
+      Object.assign(result, init);
+      result.$type = type;
+   }
+   return result as unknown as TAst;
+}
+
+/**
+ * Seed a node with `$type` plus every property the grammar declares a default
+ * for. Array defaults are materialised as a fresh `[]` per call — never shared
+ * with the metadata's own array instance, which downstream callers mutate —
+ * while scalar defaults are copied as-is since they are immutable.
+ */
+function withTypeDefaults(reflection: AstReflection, type: string): Record<string, unknown> {
+   const result: Record<string, unknown> = { $type: type };
+   const meta = reflection.getTypeMetaData(type);
+   if (meta?.properties) {
+      for (const [propName, propInfo] of Object.entries(meta.properties)) {
+         const defaultValue = propInfo.defaultValue;
+         if (defaultValue === undefined) {
+            continue;
+         }
+         result[propName] = Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
+      }
+   }
+   return result;
+}

package/src/langium/bootstrap.ts

@@ -12,15 +12,18 @@ import { type LangiumSharedCoreServices } from '@hydranium/langium';
 import { type LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
 import type { ServerSharedServicesMinimal } from './shared-services.js';
 import { collectProducibleTypes } from './language-types.js';
-import { AstDocumentManager } from '../documents/ast-document-manager.js';
+import { assertSingleLangiumCopy } from './single-langium-copy.js';
+import { DefaultAstDocumentManager } from '../documents/ast-document-manager.js';
 import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
-import { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
+import { DefaultBuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
 import { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
-import { ModelService } from './model-service/model-service.js';
+import { DefaultModelService } from './model-service/model-service.js';
 import { HydraniumScopeComputation } from './scope/hydranium-scope-computation.js';
 import { HydraniumScopeProvider } from './scope/hydranium-scope-provider.js';
 import { processEnv } from '../util/environment.js';
-import { TransferEncoder } from './transfer/transfer-encoder.js';
+import { DefaultTransferEncoder } from './transfer/transfer-encoder.js';
+import { HydraniumLangiumDocumentFactory } from './workspace/hydranium-langium-document-factory.js';
+import { HydraniumLangiumDocuments } from './workspace/langium-documents.js';
 import { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
 
 /**
@@ -73,7 +76,14 @@ const EXPECTED_SHARED_SLOTS: readonly ExpectedSlot[] = [
       side: 'shared',
       path: 'workspace.BuildPipelineIntegration',
       get: services => nested(services, 'workspace', 'BuildPipelineIntegration')
-   }
+   },
+   // Unbound, this fails where the cause is least visible: the render pass runs
+   // inside the `Validated` phase, so a `TypeError` there propagates out of
+   // `notifyDocumentPhase` and the document reaches `Validated` with Langium's
+   // publisher never invoked — the client receives no diagnostics for the file
+   // and the stack names the document builder.
+   { side: 'shared', path: 'MessageRenderer', get: services => nested(services, 'MessageRenderer') },
+   { side: 'shared', path: 'ServerLocale', get: services => nested(services, 'ServerLocale') }
 ];
 
 /**
@@ -184,6 +194,20 @@ interface StrictSlot {
 
 const STRICT_SHARED_SLOTS: readonly StrictSlot[] = [
    { side: 'shared', path: 'workspace.TextDocuments', base: HydraniumTextDocuments, get: s => nested(s, 'workspace', 'TextDocuments') },
+   // Every root it builds records no version, so every write gated on one conflicts.
+   {
+      side: 'shared',
+      path: 'workspace.LangiumDocumentFactory',
+      base: HydraniumLangiumDocumentFactory,
+      get: s => nested(s, 'workspace', 'LangiumDocumentFactory')
+   },
+   // It reports no registered root, so none is reconciled with the text store or announced.
+   {
+      side: 'shared',
+      path: 'workspace.LangiumDocuments',
+      base: HydraniumLangiumDocuments,
+      get: s => nested(s, 'workspace', 'LangiumDocuments')
+   },
    {
       side: 'shared',
       path: 'workspace.WorkspaceManager',
@@ -199,17 +223,17 @@ const STRICT_SHARED_SLOTS: readonly StrictSlot[] = [
    {
       side: 'shared',
       path: 'workspace.AstDocumentManager',
-      base: AstDocumentManager,
+      base: DefaultAstDocumentManager,
       get: s => nested(s, 'workspace', 'AstDocumentManager')
    },
    {
       side: 'shared',
       path: 'workspace.BuildPipelineIntegration',
-      base: BuildPipelineIntegration,
+      base: DefaultBuildPipelineIntegration,
       get: s => nested(s, 'workspace', 'BuildPipelineIntegration')
    },
-   { side: 'shared', path: 'model.TransferEncoder', base: TransferEncoder, get: s => nested(s, 'model', 'TransferEncoder') },
-   { side: 'shared', path: 'model.ModelService', base: ModelService, get: s => nested(s, 'model', 'ModelService') }
+   { side: 'shared', path: 'model.TransferEncoder', base: DefaultTransferEncoder, get: s => nested(s, 'model', 'TransferEncoder') },
+   { side: 'shared', path: 'model.ModelService', base: DefaultModelService, get: s => nested(s, 'model', 'ModelService') }
 ];
 
 const STRICT_LANGUAGE_SLOTS: readonly StrictSlot[] = [
@@ -329,30 +353,33 @@ export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServic
  * discarded.
  *
  * Bootstrap responsibilities, in order:
- *  1. Hand the shared services to `shared.ServiceRegistry` if it accepts
+ *  1. {@link assertSingleLangiumCopy} — fail fast when the shared
+ *     `AstReflection` is built on a second copy of `langium`, before any
+ *     later check can fail first and name the wrong cause.
+ *  2. Hand the shared services to `shared.ServiceRegistry` if it accepts
  *     them after construction, so Langium's declared-languageId lookup
  *     rung works however the adopter's registry binding was built.
- *  2. {@link assertDistinctFileRouting} — before registration, because
+ *  3. {@link assertDistinctFileRouting} — before registration, because
  *     `register` resolves a routing collision by last-wins and afterwards
  *     the evidence is gone.
- *  3. Register `language` against `shared.ServiceRegistry`, the
+ *  4. Register `language` against `shared.ServiceRegistry`, the
  *     required final step of any Langium DI bootstrap. Done before slot
  *     validation so subclassed registries (typed-accessor extensions)
  *     populate any side state before validation walks construct services
  *     that read from the registry.
- *  4. {@link assertCoreSlotsBound} — fail fast if the consumer's
+ *  5. {@link assertCoreSlotsBound} — fail fast if the consumer's
  *     `inject(...)` composition is missing a `@hydranium/core` module. May
  *     trigger lazy service construction as side effect of walking the
  *     slots; that construction expects a populated `ServiceRegistry`,
  *     hence the order.
- *  5. {@link warnOnUnexpectedBindings} — opt-in (gated by
+ *  6. {@link warnOnUnexpectedBindings} — opt-in (gated by
  *     {@link STRICT_BINDINGS_ENV}); warns when a framework slot is bound
  *     to a non-subclass of its framework base. No-op unless the env is set.
- *  6. {@link assertReflectionCoversLanguages} — catch a clobbered shared
+ *  7. {@link assertReflectionCoversLanguages} — catch a clobbered shared
  *     `AstReflection` before it starts silently answering `isSubtype`
  *     false for a registered language's types. Skipped here, since a lone
  *     language has no sibling that could clobber it.
- *  7. Invoke eager-construction accessors in array order.
+ *  8. Invoke eager-construction accessors in array order.
  *
  * Multi-grammar adopters use {@link bootstrapLangiumLanguages}, which
  * registers every language before validating slots or constructing the
@@ -377,16 +404,20 @@ export function bootstrapLangium<TShared extends LangiumSharedServices & ServerS
  * ORDER across languages is what makes this a distinct function rather
  * than a loop the caller could write:
  *
- *  1. **Every** language is registered against `shared.ServiceRegistry`
- *     first. Slot validation and eager construction both build services
+ *  1. {@link assertSingleLangiumCopy} runs **once**, before anything else,
+ *     since every language shares the one `AstReflection`.
+ *  2. **Every** language is registered against `shared.ServiceRegistry`
+ *     next. Slot validation and eager construction both build services
  *     that read the registry — a per-language
  *     register-then-validate-then-eager loop would run them while later
  *     languages were still missing, so a shared service that walks
  *     `ServiceRegistry.all` (or resolves by extension) would see a
  *     half-populated registry and cache the wrong answer.
- *  2. `assertCoreSlotsBound` / `warnOnUnexpectedBindings` per language —
+ *  3. `assertCoreSlotsBound` / `warnOnUnexpectedBindings` per language —
  *     each language composes its own module chain, so each is checked.
- *  3. Eager accessors run **once**, after all registrations. They take
+ *  4. {@link assertReflectionCoversLanguages} runs **once**, on the one
+ *     shared `AstReflection`.
+ *  5. Eager accessors run **once**, after all registrations. They take
  *     the shared tier, and the framework's eager set is shared-tier only
  *     (`ProjectManager`, `BuildPipelineIntegration`, `LangiumProfiler`,
  *     `CstResidencyService`) — `BuildPipelineIntegration` in particular
@@ -414,6 +445,11 @@ export function bootstrapLangiumLanguages<
             '`inject(...)` composition.'
       );
    }
+   // First, because a second copy of `langium` can make a later check fail
+   // first and name the wrong cause.
+   if (shared.AstReflection) {
+      assertSingleLangiumCopy(shared.AstReflection);
+   }
    // Back-fill the shared services onto a registry that was constructed
    // without them, so Langium's declared-languageId lookup rung works no
    // matter how the adopter's `ServiceRegistry` binding built it. An adopter
@@ -521,11 +557,11 @@ export function assertDistinctFileRouting(languages: ReadonlyArray<LangiumServic
  *
  * The check is per language, on the types its grammar can produce, and costs
  * one grammar walk per language at boot; a single-language composition, which
- * nothing can clobber, is skipped entirely. It cannot repair the situation — a
- * reflection that spans independently generated grammars is a real design piece
- * (a composite reflection dispatching per owning language) and is not attempted
- * here; the point is to turn a silent runtime misbehaviour into a boot failure
- * that names the language and the mistake.
+ * nothing can clobber, is skipped entirely. It cannot repair the situation, since
+ * the losing reflection is already gone; the point is to turn a silent runtime
+ * misbehaviour into a boot failure that names the language and the mistake. The
+ * repair is the adopter's: bind a `CompositeAstReflection` over every package's
+ * generated reflection, or generate all grammars in one `langium-cli` run.
  *
  * **Two severities, because a clobber is not always total.** Throwing only when
  * NONE of a language's types are known misses the realistic case: two grammars
@@ -567,8 +603,9 @@ export function assertReflectionCoversLanguages(shared: LangiumSharedServices, l
          `[hydranium] the shared AstReflection knows NONE of the ${produced.size} types the language ` +
             `'${languageId}' can produce (e.g. ${missing.slice(0, 3).join(', ')}). ` +
             'AstReflection is a single shared slot, so composing two independently generated language ' +
-            'packages leaves only the last one bound. Generate all grammars in ONE langium-cli run (one ' +
-            'langium-config with several entry grammars) so a single combined reflection covers them all.'
+            "packages leaves only the last one bound. Bind a CompositeAstReflection over every package's " +
+            'generated reflection, or generate all grammars in ONE langium-cli run (one langium-config with ' +
+            'several entry grammars) so a single combined reflection covers them all.'
       );
    }
 }
@@ -590,7 +627,8 @@ function warnPartialReflectionCoverage(
       'For those types `isSubtype` answers false and `getTypeMetaData` is empty, so `IndexManager.allElements` ' +
       'finds nothing, reference routing misses, and the encoder emits nothing. Most likely two independently ' +
       'generated language packages each bound the single shared AstReflection slot and the last one won — ' +
-      'generate all grammars in ONE langium-cli run so a single combined reflection covers them. If instead ' +
+      "bind a CompositeAstReflection over every package's generated reflection, or generate all grammars in " +
+      'ONE langium-cli run so a single combined reflection covers them. If instead ' +
       'these are rules your generator legitimately folded away, this warning is expected.';
    if (logger) {
       logger.warn(message);