@hydranium/core 1.0.0-next.29 → 1.0.0-next.298

package/src/langium/bootstrap.ts

@@ -10,17 +10,20 @@
 import { type Logger } from '@hydranium/protocol';
 import { type LangiumSharedCoreServices } from '@hydranium/langium';
 import { type LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
-import type { ServerSharedServicesMinimal } from './shared-services.js';
+import type { ServerSharedServices } from './module.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[] = [
@@ -287,31 +311,40 @@ export function warnOnUnexpectedBindings(shared: LangiumSharedServices, 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.
  * Adopters needing extra eager targets spread this constant into their own
  * array and append their accessors.
  */
-export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServicesMinimal) => unknown> = [
+export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServices) => unknown> = [
    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
 ];
 
 /**
@@ -329,36 +362,39 @@ 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
  * eager set.
  */
-export function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(
+export function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(
    shared: TShared,
    language: TLang,
    eagerlyConstructedServices: ReadonlyArray<(services: TShared) => unknown> = DEFAULT_EAGER_SERVICES
@@ -377,32 +413,32 @@ 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
- *     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 function bootstrapLangiumLanguages<
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
-   TLang extends LangiumServices
->(
+export function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(
    shared: TShared,
    languages: ReadonlyArray<TLang>,
    eagerlyConstructedServices: ReadonlyArray<(services: TShared) => unknown> = DEFAULT_EAGER_SERVICES
@@ -414,6 +450,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 +562,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 +608,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 +632,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);

package/src/langium/build-phase-pass/build-phase-pass-service.ts

@@ -13,7 +13,7 @@ import { type CancellationToken, type Disposable } from 'vscode-languageserver';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServices } from '../module.js';
 import { Registry } from '../../util/registry.js';
-import { type BuildPhasePass, type BuildPhasePassRegistry } from './build-phase-pass.js';
+import { type BuildPhasePass, type BuildPhasePassRegistry, BuildPassPhase } from './build-phase-pass.js';
 
 /**
  * Public contract for the shared build-phase-pass runner. Extends the
@@ -27,11 +27,11 @@ import { type BuildPhasePass, type BuildPhasePassRegistry } from './build-phase-
  * per-language work (integrity) fans out by language *inside* its pass. This
  * also keeps one priority space per phase across framework and adopter passes,
  * which is the point — `runPasses` orders the framework's integrity and
- * profiler-flush passes against adopter passes deterministically.
+ * CST-residency passes against adopter passes deterministically.
  */
 export interface BuildPhasePassService extends BuildPhasePassRegistry {
    /**
-    * Run every pass declaring `phase` as its state, in priority order,
+    * Run every pass declaring `phase`, in priority order,
     * sequentially — each pass is awaited before the next begins. The cancel
     * token is checked before each pass so a preempted build stops cleanly.
     * No-ops when no pass targets the phase. Called by
@@ -52,8 +52,8 @@ export type BuildPhasePassServiceOptions = LogNameOptions;
  * `BuildPipelineIntegration`,
  * which calls {@link runPasses} from its `onBuildPhase` listeners.
  *
- * **Performance:** {@link runPasses} shares the bucket-by-state cache pattern
- * with the AST-extension service — the per-state pass list is rebuilt lazily
+ * **Performance:** {@link runPasses} shares the bucket-by-phase cache pattern
+ * with the AST-extension service — the per-phase pass list is rebuilt lazily
  * only after a register / unregister, so steady-state dispatch allocates
  * nothing and early-outs when no pass targets the phase.
  *
@@ -64,9 +64,9 @@ export type BuildPhasePassServiceOptions = LogNameOptions;
  */
 export class DefaultBuildPhasePassService implements BuildPhasePassService {
    protected readonly passes = new Registry<BuildPhasePass>();
-   /** Per-state bucket of passes targeting each state, rebuilt lazily on the first run after a registry mutation. */
-   protected stateBuckets = new Map<DocumentState, readonly BuildPhasePass[]>();
-   protected stateBucketsFor: readonly BuildPhasePass[] | undefined;
+   /** Per-phase bucket of passes targeting each phase, rebuilt lazily on the first run after a registry mutation. */
+   protected phaseBuckets = new Map<DocumentState, readonly BuildPhasePass[]>();
+   protected phaseBucketsFor: readonly BuildPhasePass[] | undefined;
 
    protected readonly tracer: Tracer;
 
@@ -84,11 +84,21 @@ export class DefaultBuildPhasePassService implements BuildPhasePassService {
    }
 
    register(pass: BuildPhasePass): Disposable {
+      // A phase outside the wired set type-checks only past a cast, and a pass
+      // there is accepted and never fires.
+      if (!BuildPassPhase.all().includes(pass.phase)) {
+         throw new Error(
+            `Build-phase pass '${pass.id}' registered at phase ${DocumentState[pass.phase]} would never fire. ` +
+               `Allowed phases are ${BuildPassPhase.all()
+                  .map(phase => DocumentState[phase])
+                  .join(', ')}.`
+         );
+      }
       return this.passes.register(pass);
    }
 
    async runPasses(documents: readonly LangiumDocument[], phase: DocumentState, cancelToken: CancellationToken): Promise<void> {
-      const bucket = this.getStateBucket(phase);
+      const bucket = this.getPhaseBucket(phase);
       if (bucket.length === 0) {
          return;
       }
@@ -114,28 +124,28 @@ export class DefaultBuildPhasePassService implements BuildPhasePassService {
    }
 
    /**
-    * Bucket-by-state view of {@link passes}, rebuilt lazily when the registry's
+    * Bucket-by-phase view of {@link passes}, rebuilt lazily when the registry's
     * cached `all()` reference changes. Each bucket preserves the registry's
     * priority order (`Registry.all()` is already priority-sorted).
     */
-   protected getStateBucket(phase: DocumentState): readonly BuildPhasePass[] {
+   protected getPhaseBucket(phase: DocumentState): readonly BuildPhasePass[] {
       const current = this.passes.all();
-      if (this.stateBucketsFor !== current) {
+      if (this.phaseBucketsFor !== current) {
          const next = new Map<DocumentState, BuildPhasePass[]>();
          for (const pass of current) {
-            let bucket = next.get(pass.state);
+            let bucket = next.get(pass.phase);
             if (!bucket) {
                bucket = [];
-               next.set(pass.state, bucket);
+               next.set(pass.phase, bucket);
             }
             bucket.push(pass);
          }
-         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: readonly BuildPhasePass[] = Object.freeze([]);
+/** Shared empty result so `getPhaseBucket` doesn't allocate per call on the cold path. */
+const EMPTY_PHASE_BUCKET: readonly BuildPhasePass[] = Object.freeze([]);

package/src/langium/build-phase-pass/build-phase-pass.ts

@@ -7,10 +7,43 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type DocumentState, type LangiumCoreServices, type LangiumDocument, type URI } from '@hydranium/langium';
+import { DocumentState, type LangiumCoreServices, type LangiumDocument, type URI } from '@hydranium/langium';
 import { type CancellationToken, type Disposable } from 'vscode-languageserver';
 import { type RegistryItem } from '../../util/registry.js';
 
+/**
+ * The build phases a {@link BuildPhasePass} may fire at: every phase after
+ * `Changed`, which has no AST yet. `IndexedContent` is one, unlike for an
+ * `AstExtension`: per document it carries nothing `Parsed` does, but per
+ * batch it is the only phase meaning the global index is whole again, which
+ * batch work keyed on a complete index has nowhere else to run.
+ */
+export type BuildPassPhase =
+   | DocumentState.Parsed
+   | DocumentState.IndexedContent
+   | DocumentState.ComputedScopes
+   | DocumentState.Linked
+   | DocumentState.IndexedReferences
+   | DocumentState.Validated;
+
+export namespace BuildPassPhase {
+   /**
+    * Every {@link BuildPassPhase}, in build order. `BuildPipelineIntegration`
+    * wires one `onBuildPhase` listener per entry and `register` refuses a phase
+    * outside it, so the two cannot drift apart. A fresh array each call.
+    */
+   export function all(): readonly BuildPassPhase[] {
+      return [
+         DocumentState.Parsed,
+         DocumentState.IndexedContent,
+         DocumentState.ComputedScopes,
+         DocumentState.Linked,
+         DocumentState.IndexedReferences,
+         DocumentState.Validated
+      ];
+   }
+}
+
 /**
  * A unit of whole-batch work run once per build when the batch reaches a
  * declared build phase, ordered by {@link RegistryItem.priority}.
@@ -46,12 +79,8 @@ import { type RegistryItem } from '../../util/registry.js';
  * rather than running the remaining passes against a doomed build.
  */
 export interface BuildPhasePass extends RegistryItem {
-   /**
-    * The single build phase whose `onBuildPhase` fires this pass. The framework
-    * wires a listener for the same phase set as AST extension; a pass declaring
-    * any other state type-checks but never fires.
-    */
-   state: DocumentState;
+   /** The single build phase whose `onBuildPhase` fires this pass. */
+   phase: BuildPassPhase;
    /**
     * Run this pass against the whole built batch. May mutate and reparse
     * documents — the framework's integrity pass does — or derive cross-document
@@ -102,7 +131,7 @@ export function groupDocumentsByLanguage<TLanguage extends LangiumCoreServices>(
  * Registry handed to a {@link BuildPhasePassContribution}. Implemented by the
  * `BuildPhasePassService`; doubles
  * as the low-level imperative API the framework uses to self-register its own
- * passes (integrity, the Langium profiler flush).
+ * passes (integrity, CST residency).
  */
 export interface BuildPhasePassRegistry {
    register(pass: BuildPhasePass): Disposable;

package/src/langium/composite-ast-reflection.ts

@@ -0,0 +1,112 @@
+/********************************************************************************
+ * 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 AstMetaData, type AstReflection, type PropertyMetaData, type TypeMetaData } from '@hydranium/langium';
+import { assertSingleLangiumCopy } from './single-langium-copy.js';
+
+/**
+ * One `AstReflection` over the reflections of separately generated language
+ * packages. The shared `AstReflection` slot holds a single reflection, so
+ * binding each package's generated shared module keeps only the last one's
+ * types; bind this over all of them instead.
+ *
+ * A name several reflections share is taken to be one type, reached through a
+ * shared imported grammar, and keeps every super type any of them gives it:
+ * each grammar may declare its own union over the type. Only properties that
+ * differ in name, reference type or default value throw; two unrelated unions,
+ * or same-shaped interfaces, that share a name merge silently, so keep other
+ * type names distinct across packages.
+ *
+ * Only each reflection's `types` is read, so behaviour a reflection overrides
+ * is lost. Each package's generated `isX` guards keep using that package's own
+ * reflection and answer false for subtypes only another package declares.
+ *
+ * Each reflection is checked with {@link assertSingleLangiumCopy}, because the
+ * composite itself extends the framework copy's base whichever copy they use.
+ *
+ * The protected merge methods run from the constructor, so an override cannot
+ * read its own class's fields.
+ */
+export class CompositeAstReflection extends AbstractAstReflection {
+   override readonly types: AstMetaData = {};
+
+   constructor(reflections: readonly AstReflection[]) {
+      super();
+      const firstDefinedAt = new Map<string, number>();
+      reflections.forEach((reflection, index) => {
+         assertSingleLangiumCopy(reflection, () => this.formatReflection(reflections, index));
+         for (const [type, metaData] of Object.entries(reflection.types)) {
+            const ownerIndex = firstDefinedAt.get(type);
+            if (ownerIndex === undefined) {
+               this.types[type] = metaData;
+               firstDefinedAt.set(type, index);
+            } else {
+               this.types[type] = this.mergeTypeMetaData(
+                  this.types[type],
+                  metaData,
+                  this.formatReflection(reflections, ownerIndex),
+                  this.formatReflection(reflections, index)
+               );
+            }
+         }
+      });
+   }
+
+   protected mergeTypeMetaData(known: TypeMetaData, added: TypeMetaData, knownFrom: string, addedFrom: string): TypeMetaData {
+      const properties: TypeMetaData['properties'] = {};
+      const propertyNames = new Set([...Object.keys(known.properties), ...Object.keys(added.properties)]);
+      for (const property of propertyNames) {
+         const knownProperty = known.properties[property];
+         const addedProperty = added.properties[property];
+         if (!knownProperty || !addedProperty || !this.sameProperty(knownProperty, addedProperty)) {
+            throw new Error(
+               `[hydranium] ${knownFrom} and ${addedFrom} define the type ` +
+                  `'${known.name}' differently (property '${property}'). A name the composed reflections share must ` +
+                  'denote one type, so rename one of them, or have every grammar take the type unchanged from one ' +
+                  'shared imported grammar.'
+            );
+         }
+         properties[property] = addedProperty.optional && !knownProperty.optional ? addedProperty : knownProperty;
+      }
+      // `Required` so a field Langium adds fails compilation until this merge decides on it.
+      const merged: Required<TypeMetaData> = {
+         name: known.name,
+         properties,
+         superTypes: [...new Set([...known.superTypes, ...added.superTypes])]
+      };
+      return merged;
+   }
+
+   protected sameProperty(left: PropertyMetaData, right: PropertyMetaData): boolean {
+      return COMPARED_PROPERTY_FIELDS.every(field => JSON.stringify(left[field]) === JSON.stringify(right[field]));
+   }
+
+   /**
+    * Names `reflections[index]` for the composite's errors: its position and
+    * class name. The position is needed because minified bundles and scaffolds
+    * sharing a project name leave class names that do not tell reflections
+    * apart. An override can name the package each reflection came from.
+    */
+   protected formatReflection(reflections: readonly AstReflection[], index: number): string {
+      return `reflections[${index}] (${reflections[index].constructor?.name ?? 'no constructor'})`;
+   }
+}
+
+/** How the merge treats each property field; a field Langium adds fails compilation here until decided. */
+const PROPERTY_FIELDS = {
+   name: 'compared',
+   referenceType: 'compared',
+   defaultValue: 'compared',
+   // Older generators emit no `optional`, so its absence proves nothing.
+   optional: 'merged'
+} as const satisfies Record<keyof PropertyMetaData, 'compared' | 'merged'>;
+
+const COMPARED_PROPERTY_FIELDS = (Object.keys(PROPERTY_FIELDS) as Array<keyof PropertyMetaData>).filter(
+   field => PROPERTY_FIELDS[field] === 'compared'
+);