@hydranium/core 1.0.0-next.36 → 1.0.0-next.361

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

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import type { AstNode, AstReflection } from '@hydranium/langium';
+import type { ConcreteTypeName, SingleTypeName } from '@hydranium/protocol';
 
 /**
  * Shape of the per-type constants Langium emits alongside each
@@ -55,14 +56,18 @@ export type AstNodeInit<T extends AstNode> = Omit<T, keyof AstNode | ArrayKeys<T
  * the AST interface from a constant's `$type` literal alone, so call sites do
  * not have to write the type name twice.
  *
+ * The constant must name one type its own `$type` lists: a union's or an
+ * abstract type's constant, or one typed by a union of type names, would let
+ * an incomplete node through.
+ *
  * @param typeConstant the per-type constant Langium emits (drives `$type`).
  * @param init typed fields — TS enforces mandatory non-array fields here.
  * @param extras explicitly-unchecked escape hatch for properties not declared
  *               on the AST interface. Use sparingly; lives in a separate
  *               argument so typos can't silently pass into the typed slot.
  */
-export type AstNodeBuilder<TMap> = <TType extends string & keyof TMap>(
-   typeConstant: AstTypeConstant<TType>,
+export type AstNodeBuilder<TMap> = <TType extends ConcreteTypeName<TMap>>(
+   typeConstant: AstTypeConstant<TType> & SingleTypeName<TType>,
    init: AstNodeInit<Extract<TMap[TType], AstNode>>,
    extras?: Record<string, unknown>
 ) => Extract<TMap[TType], AstNode>;
@@ -94,18 +99,21 @@ export type AstNodeBuilder<TMap> = <TType extends string & keyof TMap>(
  * rather than a way to drop fields from the typed call site.
  */
 export function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuilder<TMap> {
-   return function astNode<TType extends string & keyof TMap>(
-      typeConstant: AstTypeConstant<TType>,
+   return function astNode<TType extends ConcreteTypeName<TMap>>(
+      typeConstant: AstTypeConstant<TType> & SingleTypeName<TType>,
       init: AstNodeInit<Extract<TMap[TType], AstNode>>,
       extras?: Record<string, unknown>
    ): Extract<TMap[TType], AstNode> {
       const result = withTypeDefaults(reflection, typeConstant.$type);
-      Object.assign(result, init);
+      assignOverDefaults(result, init);
       if (extras) {
          // Extras win over init: this is the explicit escape hatch, so when a
          // call site uses it, treat that as deliberate override intent.
-         Object.assign(result, extras);
+         assignOverDefaults(result, extras);
       }
+      // Last, so neither can rebind it: `AstNodeInit` keeps out only a `$type`
+      // written in the call, and a spread of another node carries its own.
+      result.$type = typeConstant.$type;
       return result as unknown as Extract<TMap[TType], AstNode>;
    };
 }
@@ -127,12 +135,12 @@ export function makeAstNodeBuilder<TMap>(reflection: AstReflection): AstNodeBuil
  * 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.
+ * typed builder holds the same rule, since its init type keeps out only a
+ * `$type` written in the call. 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,
@@ -141,7 +149,7 @@ export function buildAstNode<TAst extends AstNode = AstNode>(
 ): TAst {
    const result = withTypeDefaults(reflection, type);
    if (init) {
-      Object.assign(result, init);
+      assignOverDefaults(result, init);
       result.$type = type;
    }
    return result as unknown as TAst;
@@ -167,3 +175,17 @@ function withTypeDefaults(reflection: AstReflection, type: string): Record<strin
    }
    return result;
 }
+
+/**
+ * `Object.assign`, except that an `undefined` does not replace a value already
+ * there: an optional field the caller names as `undefined` keeps its grammar
+ * default, where a plain assign would leave a node typed complete without it.
+ * Any other `undefined` is written, so the key stays present.
+ */
+function assignOverDefaults(target: Record<string, unknown>, source: object): void {
+   for (const [key, value] of Object.entries(source)) {
+      if (value !== undefined || !Object.hasOwn(target, key)) {
+         target[key] = value;
+      }
+   }
+}

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';
 
 /**
@@ -191,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',
@@ -206,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[] = [
@@ -294,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
 ];
 
 /**
@@ -336,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
@@ -384,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
@@ -421,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
@@ -528,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
@@ -574,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.'
       );
    }
 }
@@ -597,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;