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

package/lib/langium/ast-extension/ast-extension-service.js

@@ -9,6 +9,24 @@
 import { Logger } from '@hydranium/protocol';
 import { AstUtils, DocumentState } from '@hydranium/langium';
 import { Registry } from '../../util/registry.js';
+export var AstExtensionPhase;
+(function (AstExtensionPhase) {
+    /**
+     * Every {@link AstExtensionPhase}, in build order. `BuildPipelineIntegration`
+     * wires one `onDocumentPhase` listener per entry and `register` refuses a
+     * phase outside it, so the two cannot drift apart. A fresh array each call.
+     */
+    function all() {
+        return [
+            DocumentState.Parsed,
+            DocumentState.ComputedScopes,
+            DocumentState.Linked,
+            DocumentState.IndexedReferences,
+            DocumentState.Validated
+        ];
+    }
+    AstExtensionPhase.all = all;
+})(AstExtensionPhase || (AstExtensionPhase = {}));
 /**
  * Default {@link AstExtensionService} implementation. Generic registry for
  * build-phase AST-node enrichment: computed properties and synthetic
@@ -23,19 +41,19 @@ import { Registry } from '../../util/registry.js';
  * owns the registry + per-node logic, not the listener lifecycle.
  *
  * **Performance:** `extendDocument` shares a single `streamAllContents` walk
- * per document per wired phase; cost is O(registrations-for-state × nodes),
- * and it early-outs when no registration targets the state or the document.
+ * per document per wired phase; cost is O(registrations-for-phase × nodes),
+ * and it early-outs when no registration targets the phase or the document.
  */
 export class DefaultAstExtensionService {
     services;
     extensions = new Registry();
     /**
-     * Per-state bucket of registrations targeting each state. Rebuilt lazily
+     * Per-phase bucket of registrations targeting each phase. Rebuilt lazily
      * on the first refresh after a registry mutation — staleness is detected
      * via reference identity of the registry's cached array (see {@link Registry.all}).
      */
-    stateBuckets = new Map();
-    stateBucketsFor;
+    phaseBuckets = new Map();
+    phaseBucketsFor;
     tracer;
     constructor(services, options = {}) {
         this.services = services;
@@ -59,16 +77,24 @@ export class DefaultAstExtensionService {
      * which calls {@link extendDocument} for the wired phases.
      */
     register(extension) {
+        // A phase outside the wired set type-checks only past a cast, and a
+        // registration there is accepted and never fires.
+        if (!AstExtensionPhase.all().includes(extension.phase)) {
+            throw new Error(`AST extension '${extension.id}' registered at phase ${DocumentState[extension.phase]} would never fire. ` +
+                `Allowed phases are ${AstExtensionPhase.all()
+                    .map(phase => DocumentState[phase])
+                    .join(', ')}.`);
+        }
         // Cast: TypeScript can't see that `T extends AstNode` makes the extension
         // assignable to the default-parameter form. The runtime contract is the same.
         return this.extensions.register(extension);
     }
     /**
      * Production code goes through {@link extendDocument} via the
-     * `onDocumentPhase(state)` listener wired by `BuildPipelineIntegration`.
+     * `onDocumentPhase(phase)` listener wired by `BuildPipelineIntegration`.
      */
     extendNode(node, document, phase) {
-        const bucket = this.getStateBucket(phase);
+        const bucket = this.getPhaseBucket(phase);
         for (const extension of bucket) {
             if (extension.documentFilter && !extension.documentFilter(document)) {
                 continue;
@@ -96,7 +122,7 @@ export class DefaultAstExtensionService {
         if (cancelToken?.isCancellationRequested) {
             return;
         }
-        const bucket = this.getStateBucket(phase);
+        const bucket = this.getPhaseBucket(phase);
         if (bucket.length === 0) {
             return;
         }
@@ -129,32 +155,32 @@ export class DefaultAstExtensionService {
         session?.report('debug');
     }
     /**
-     * Bucket-by-state view of {@link extensions}, rebuilt lazily when the
+     * Bucket-by-phase view of {@link extensions}, rebuilt lazily when the
      * registry's cached `all()` reference changes. Replaces per-call allocation
      * on the per-node hot path — for a workspace with many documents at the
-     * same state, the bucket is computed once and reused until the next
+     * same phase, the bucket is computed once and reused until the next
      * register / unregister.
      */
-    getStateBucket(phase) {
+    getPhaseBucket(phase) {
         const current = this.extensions.all();
-        if (this.stateBucketsFor !== current) {
+        if (this.phaseBucketsFor !== current) {
             const next = new Map();
             for (const extension of current) {
-                let bucket = next.get(extension.state);
+                let bucket = next.get(extension.phase);
                 if (!bucket) {
                     bucket = [];
-                    next.set(extension.state, bucket);
+                    next.set(extension.phase, bucket);
                 }
                 bucket.push(extension);
             }
-            this.stateBuckets = next;
-            this.stateBucketsFor = current;
+            this.phaseBuckets = next;
+            this.phaseBucketsFor = current;
         }
-        return this.stateBuckets.get(phase) ?? EMPTY_STATE_BUCKET;
+        return this.phaseBuckets.get(phase) ?? EMPTY_PHASE_BUCKET;
     }
 }
-/** Shared empty result so `getStateBucket` doesn't allocate per call on the cold path. */
-const EMPTY_STATE_BUCKET = Object.freeze([]);
+/** Shared empty result so `getPhaseBucket` doesn't allocate per call on the cold path. */
+const EMPTY_PHASE_BUCKET = Object.freeze([]);
 /**
  * Assign a non-enumerable own property — for synthetic children that must NOT
  * be walked by Langium's `streamContents`.

package/lib/langium/ast-extension/ast-extension-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast-extension-service.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-extension-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ast-extension-service.js","sourceRoot":"","sources":["../../../src/langium/ast-extension/ast-extension-service.ts"],"names":[],"mappings":"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"}

package/lib/langium/bootstrap.d.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { type LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
-import type { ServerSharedServicesMinimal } from './shared-services.js';
+import type { ServerSharedServices } from './module.js';
 /**
  * Verify that the slots `@hydranium/core` is responsible for
  * binding are populated after composition. Throws an error with a
@@ -60,27 +60,34 @@ export declare function warnOnUnexpectedBindings(shared: LangiumSharedServices,
  *   dispatch every build-phase pass and drive AST enrichment, and
  *   registers the framework integrity passes itself. The per-language
  *   feature services it routes to (`ast.AstExtensionService` +
- *   `integrity.IntegrityService`, plus `references.ScopeExtensionService`
- *   read by the scope provider) hold the registries and the logic but own
+ *   `integrity.IntegrityService`) hold the registries and the logic but own
  *   no listeners, so they need not be eager: each language's services
- *   construct lazily when the orchestrator (or scope provider) first
- *   reaches them, and their constructors register that language's rules /
- *   extensions just-in-time.
- * - **`profilers.LangiumProfiler`** — self-registers a `Validated`
- *   BuildPhasePass that flushes the aggregated parse/link/validate profile
- *   once per build. No production cost (the profiler is trace-gated), but
- *   the pass must be registered up front.
+ *   construct lazily when the orchestrator first reaches them, and their
+ *   constructors register that language's rules / extensions just-in-time.
+ *   `references.ScopeExtensionService`, read by the scope provider, does
+ *   subscribe to the builder, but only to report its own calls, so
+ *   constructing it at its first call misses none.
+ * - **`profilers.LangiumProfiler`** — subscribes to
+ *   `documentBuilder.onBuildEnded` to flush the aggregated
+ *   parse/link/validate profile once per build. No production cost (the
+ *   profiler is trace-gated), but the listener must be attached before the
+ *   first build ends.
  * - **`workspace.CstResidencyService`** — self-registers a `Validated`
  *   BuildPhasePass that sheds the CST of closed documents. The framework
  *   default strategy is `always-keep`, so the pass runs but sheds nothing
  *   until an adopter configures a shedding strategy.
+ * - **`workspace.AstDocumentManager`** — subscribes to the build pipeline
+ *   and the text store to track opens, deletions and each build's causes.
+ * - **`model.ModelService`** — subscribes to the settled document phase to
+ *   bring the language client up to date. A tree without an LSP `initialize`,
+ *   such as a headless init, may not resolve it before the first build.
  *
  * Consumers with no additional eager targets can omit the third argument
  * to {@link bootstrapLangium} — the parameter default is this exact set.
  * Adopters needing extra eager targets spread this constant into their own
  * array and append their accessors.
  */
-export declare const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServicesMinimal) => unknown>;
+export declare const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServices) => unknown>;
 /**
  * After `inject(...)` returns, services are constructed lazily on first
  * access. Some framework services attach to the build pipeline in their
@@ -96,36 +103,39 @@ export declare const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerShar
  * 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
  * eager set.
  */
-export declare function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(shared: TShared, language: TLang, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
+export declare function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(shared: TShared, language: TLang, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
     shared: TShared;
     language: TLang;
 };
@@ -139,29 +149,32 @@ export declare function bootstrapLangium<TShared extends LangiumSharedServices &
  * 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
- *     the shared tier, and the framework's eager set is shared-tier only
- *     (`ProjectManager`, `BuildPipelineIntegration`, `LangiumProfiler`,
- *     `CstResidencyService`) — `BuildPipelineIntegration` in particular
- *     routes per document URI to each language's `IntegrityService` /
- *     `AstExtensionService`, so it must be constructed knowing all of
- *     them. Running the set per language would attach its
- *     `documentBuilder` listeners N times and enforce each phase N times.
+ *  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 —
+ *     `BuildPipelineIntegration` in particular routes per document URI to
+ *     each language's `IntegrityService` / `AstExtensionService`, so it
+ *     must be constructed knowing all of them. Running the set per language
+ *     would attach its `documentBuilder` listeners N times and enforce each
+ *     phase N times.
  *
  * Throws when `languages` is empty: a shared tier with no registered
  * language never validates its slots, which silently defers a
  * composition error to the first build.
  */
-export declare function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(shared: TShared, languages: ReadonlyArray<TLang>, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
+export declare function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(shared: TShared, languages: ReadonlyArray<TLang>, eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>): {
     shared: TShared;
     languages: ReadonlyArray<TLang>;
 };
@@ -203,11 +216,11 @@ export declare function assertDistinctFileRouting(languages: ReadonlyArray<Langi
  *
  * 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

package/lib/langium/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/langium/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AA+GxE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAanG;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAmF/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAiBvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,2BAA2B,KAAK,OAAO,CAKpG,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,qBAAqB,GAAG,2BAA2B,EAAE,KAAK,SAAS,eAAe,EAChI,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK,EACf,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,CAGtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACtC,OAAO,SAAS,qBAAqB,GAAG,2BAA2B,EACnE,KAAK,SAAS,eAAe,EAE7B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CAAE,CAiCtD;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CA+BzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CAiC9H"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/langium/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAyHxD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAanG;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAiG/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAiBvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAO7F,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,qBAAqB,GAAG,oBAAoB,EAAE,KAAK,SAAS,eAAe,EACzH,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK,EACf,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,CAGtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,SAAS,qBAAqB,GAAG,oBAAoB,EAAE,KAAK,SAAS,eAAe,EAClI,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,0BAA0B,GAAE,aAAa,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAA0B,GAClG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CAAE,CAsCtD;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CA+BzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,qBAAqB,EAAE,SAAS,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,IAAI,CAkC9H"}

package/lib/langium/bootstrap.js

@@ -7,15 +7,18 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 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';
 function nested(services, ...keys) {
     let current = services;
@@ -46,7 +49,14 @@ const EXPECTED_SHARED_SLOTS = [
         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') }
 ];
 /**
  * Language-side slots bound by `createServerLanguageModule`. If any
@@ -129,6 +139,20 @@ export function assertCoreSlotsBound(shared, language) {
 export const STRICT_BINDINGS_ENV = 'HYDRANIUM_STRICT_BINDINGS';
 const STRICT_SHARED_SLOTS = [
     { 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',
@@ -144,17 +168,17 @@ const STRICT_SHARED_SLOTS = [
     {
         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 = [
     {
@@ -227,20 +251,27 @@ export function warnOnUnexpectedBindings(shared, language) {
  *   dispatch every build-phase pass and drive AST enrichment, and
  *   registers the framework integrity passes itself. The per-language
  *   feature services it routes to (`ast.AstExtensionService` +
- *   `integrity.IntegrityService`, plus `references.ScopeExtensionService`
- *   read by the scope provider) hold the registries and the logic but own
+ *   `integrity.IntegrityService`) hold the registries and the logic but own
  *   no listeners, so they need not be eager: each language's services
- *   construct lazily when the orchestrator (or scope provider) first
- *   reaches them, and their constructors register that language's rules /
- *   extensions just-in-time.
- * - **`profilers.LangiumProfiler`** — self-registers a `Validated`
- *   BuildPhasePass that flushes the aggregated parse/link/validate profile
- *   once per build. No production cost (the profiler is trace-gated), but
- *   the pass must be registered up front.
+ *   construct lazily when the orchestrator first reaches them, and their
+ *   constructors register that language's rules / extensions just-in-time.
+ *   `references.ScopeExtensionService`, read by the scope provider, does
+ *   subscribe to the builder, but only to report its own calls, so
+ *   constructing it at its first call misses none.
+ * - **`profilers.LangiumProfiler`** — subscribes to
+ *   `documentBuilder.onBuildEnded` to flush the aggregated
+ *   parse/link/validate profile once per build. No production cost (the
+ *   profiler is trace-gated), but the listener must be attached before the
+ *   first build ends.
  * - **`workspace.CstResidencyService`** — self-registers a `Validated`
  *   BuildPhasePass that sheds the CST of closed documents. The framework
  *   default strategy is `always-keep`, so the pass runs but sheds nothing
  *   until an adopter configures a shedding strategy.
+ * - **`workspace.AstDocumentManager`** — subscribes to the build pipeline
+ *   and the text store to track opens, deletions and each build's causes.
+ * - **`model.ModelService`** — subscribes to the settled document phase to
+ *   bring the language client up to date. A tree without an LSP `initialize`,
+ *   such as a headless init, may not resolve it before the first build.
  *
  * Consumers with no additional eager targets can omit the third argument
  * to {@link bootstrapLangium} — the parameter default is this exact set.
@@ -251,7 +282,9 @@ export const DEFAULT_EAGER_SERVICES = [
     services => services.workspace.ProjectManager,
     services => services.workspace.BuildPipelineIntegration,
     services => services.profilers.LangiumProfiler,
-    services => services.workspace.CstResidencyService
+    services => services.workspace.CstResidencyService,
+    services => services.workspace.AstDocumentManager,
+    services => services.model.ModelService
 ];
 /**
  * After `inject(...)` returns, services are constructed lazily on first
@@ -268,30 +301,33 @@ export const DEFAULT_EAGER_SERVICES = [
  * 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
@@ -311,23 +347,26 @@ export function bootstrapLangium(shared, language, eagerlyConstructedServices =
  * 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
- *     the shared tier, and the framework's eager set is shared-tier only
- *     (`ProjectManager`, `BuildPipelineIntegration`, `LangiumProfiler`,
- *     `CstResidencyService`) — `BuildPipelineIntegration` in particular
- *     routes per document URI to each language's `IntegrityService` /
- *     `AstExtensionService`, so it must be constructed knowing all of
- *     them. Running the set per language would attach its
- *     `documentBuilder` listeners N times and enforce each phase N times.
+ *  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 —
+ *     `BuildPipelineIntegration` in particular routes per document URI to
+ *     each language's `IntegrityService` / `AstExtensionService`, so it
+ *     must be constructed knowing all of them. Running the set per language
+ *     would attach its `documentBuilder` listeners N times and enforce each
+ *     phase N times.
  *
  * Throws when `languages` is empty: a shared tier with no registered
  * language never validates its slots, which silently defers a
@@ -339,6 +378,11 @@ export function bootstrapLangiumLanguages(shared, languages, eagerlyConstructedS
             'registered language cannot validate its slots. Pass the language(s) produced by your ' +
             '`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
@@ -441,11 +485,11 @@ export function assertDistinctFileRouting(languages) {
  *
  * 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
@@ -486,8 +530,9 @@ export function assertReflectionCoversLanguages(shared, languages) {
         throw new Error(`[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.');
     }
 }
 /** Maximum missing type names spelled out before the message elides the rest. */
@@ -500,7 +545,8 @@ function warnPartialReflectionCoverage(logger, languageId, missing, producedCoun
         '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);