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

package/src/browser/indexeddb-file-system-store.ts

@@ -0,0 +1,192 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 type { FileSystemSeed } from '../langium/workspace/in-memory-file-system-provider.js';
+import type { FileSystemStore } from '../langium/workspace/persistent-file-system-provider.js';
+
+/** Out-of-line keys, so a key is the store path and the value is the content. */
+const OBJECT_STORE_NAME = 'files';
+
+/**
+ * The schema version. A bump needs a migration in `onupgradeneeded`, or every
+ * returning visitor's rows are left in a store the new code never reads.
+ */
+const DATABASE_VERSION = 1;
+
+/**
+ * A {@link FileSystemStore} in `IndexedDB`, so an edit survives a reload.
+ *
+ * # Why IndexedDB and not OPFS
+ *
+ * OPFS is the tempting answer, because `createSyncAccessHandle` gives
+ * SYNCHRONOUS file reads in a worker, which is what Langium's
+ * `FileSystemProvider` needs. It buys nothing here: directory enumeration
+ * (`FileSystemDirectoryHandle.entries()`) is async-only, so a directory index
+ * still has to live in memory, and once it does the file reads are being served
+ * from memory too. IndexedDB is the smaller dependency for the same shape.
+ *
+ * # It holds the DELTA, not the workspace
+ *
+ * Only what has been written lands here, and `PersistentFileSystemProvider` lays
+ * it over the host's seed. So a fixture edited in the host's bundle still
+ * reaches a returning visitor, and this database stays a few kilobytes rather
+ * than a copy of the workspace.
+ *
+ * # A failure is loud, deliberately
+ *
+ * Nothing here degrades to non-persistent operation. A refused open, a blocked
+ * upgrade or an aborted transaction, which is what a quota overrun looks like,
+ * rejects the call, which fails the worker's bootstrap or the save that asked.
+ * The alternative, carrying on without a store, would report a saved workspace
+ * and lose it on the next load. An origin EVICTED between visits is not a
+ * failure this class can see: its database opens empty, which is a first visit,
+ * and the provider is correct in that state. Evicted mid-session, the next
+ * transaction rejects like any other failure.
+ *
+ * # The database is origin-scoped
+ *
+ * Every page on the origin shares a database of the same name, and the user
+ * agent may evict it. The name is the one per-app value and is REQUIRED for
+ * that reason: a default would let two apps on one origin overwrite each
+ * other's edits with nothing reporting it.
+ */
+export class IndexedDbFileSystemStore implements FileSystemStore {
+   /**
+    * Opened once and shared, and NOT kept when it fails: a refused or blocked
+    * open rejects the call that needed it and the next call opens again, so a
+    * cause that has cleared, such as the other tab closing, does not fail every
+    * later save with the first error.
+    */
+   protected connection?: Promise<IDBDatabase>;
+
+   constructor(protected readonly databaseName: string) {}
+
+   async load(): Promise<FileSystemSeed> {
+      const database = await this.open();
+      return new Promise<FileSystemSeed>((resolve, reject) => {
+         const transaction = database.transaction(OBJECT_STORE_NAME, 'readonly');
+         const files = transaction.objectStore(OBJECT_STORE_NAME);
+         const keyRequest = files.getAllKeys();
+         const valueRequest = files.getAll();
+         // Resolved on the TRANSACTION rather than on either request, which is
+         // what guarantees both have landed, and `getAllKeys` and `getAll`
+         // enumerate in the same key order, so they zip.
+         transaction.oncomplete = () => {
+            const keys: IDBValidKey[] = keyRequest.result;
+            const values: unknown[] = valueRequest.result;
+            const seed: Record<string, string> = {};
+            keys.forEach((key, index) => {
+               const value = values[index];
+               // Guarded rather than cast: this database outlives the code that
+               // wrote it, so a row from an older shape must be skipped instead
+               // of reaching the filesystem as non-string content.
+               if (typeof key === 'string' && typeof value === 'string') {
+                  seed[key] = value;
+               }
+            });
+            resolve(seed);
+         };
+         transaction.onabort = () => reject(this.failure(transaction, 'read the stored workspace'));
+      });
+   }
+
+   async write(path: string, content: string): Promise<void> {
+      await this.mutate('store', files => files.put(content, path));
+   }
+
+   async remove(path: string): Promise<void> {
+      await this.mutate('drop', files => files.delete(path));
+   }
+
+   /**
+    * Drop everything, returning the next load to the seed.
+    *
+    * The escape hatch a persistent host needs and a seeded one does not: a saved
+    * document that no longer parses is otherwise restored on every load, and
+    * clearing site data is the only other way out. Not on {@link FileSystemStore},
+    * which the provider never clears.
+    */
+   async clear(): Promise<void> {
+      await this.mutate('clear', files => files.clear());
+   }
+
+   /**
+    * Run one write transaction and settle on its COMPLETION.
+    *
+    * Not on the request's `success`: a request can succeed inside a transaction
+    * that then aborts, which is exactly what a quota overrun looks like, so
+    * resolving early would report a save the database never kept.
+    */
+   protected async mutate(operation: string, act: (files: IDBObjectStore) => void): Promise<void> {
+      const database = await this.open();
+      return new Promise<void>((resolve, reject) => {
+         const transaction = database.transaction(OBJECT_STORE_NAME, 'readwrite');
+         transaction.oncomplete = () => resolve();
+         transaction.onabort = () => reject(this.failure(transaction, operation));
+         act(transaction.objectStore(OBJECT_STORE_NAME));
+      });
+   }
+
+   protected open(): Promise<IDBDatabase> {
+      this.connection ??= this.openDatabase().catch((error: unknown) => {
+         this.connection = undefined;
+         throw error;
+      });
+      return this.connection;
+   }
+
+   protected openDatabase(): Promise<IDBDatabase> {
+      return new Promise<IDBDatabase>((resolve, reject) => {
+         const request = indexedDB.open(this.databaseName, DATABASE_VERSION);
+         let blocked = false;
+         request.onupgradeneeded = () => {
+            // Runs on a first visit and on a version bump. `createObjectStore`
+            // throws if it already exists, so the guard is not defensive: a page
+            // opened twice with the store created once gets here only when the
+            // version moved.
+            if (!request.result.objectStoreNames.contains(OBJECT_STORE_NAME)) {
+               request.result.createObjectStore(OBJECT_STORE_NAME);
+            }
+         };
+         request.onsuccess = () => {
+            const database = request.result;
+            if (blocked) {
+               // Went through once the other tab closed, after this call had
+               // rejected. Nobody holds it, so it is closed rather than left
+               // open to block the NEXT upgrade.
+               database.close();
+               return;
+            }
+            // A newer version opening in another tab asks this one to let go,
+            // and holding on would block that upgrade for as long as this tab
+            // lives. Dropped, so every later call here rejects, which is loud.
+            database.onversionchange = () => {
+               database.close();
+               this.connection = undefined;
+            };
+            resolve(database);
+         };
+         request.onerror = () => reject(request.error ?? new Error(`Cannot open ${this.databaseName}`));
+         // A tab at an older version that lacks the close above holds the
+         // upgrade indefinitely. Reported rather than waited on: the host can say
+         // so, where a hung open looks like a worker that never started.
+         request.onblocked = () => {
+            blocked = true;
+            reject(new Error(`${this.databaseName} is open in another tab at an older version`));
+         };
+      });
+   }
+
+   protected failure(transaction: IDBTransaction, operation: string): Error {
+      // `transaction.error` names the real cause (`QuotaExceededError` above
+      // all); an abort with no error is a caller-side abort, which nothing here
+      // does.
+      return transaction.error ?? new Error(`Failed to ${operation} in ${this.databaseName}`);
+   }
+}

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

@@ -15,6 +15,35 @@ import { type ServerLanguageServices } from '../language-module.js';
 import { Registry, type RegistryItem } from '../../util/registry.js';
 import { type AstExtensionRegistry } from './ast-extension-contribution.js';
 
+/**
+ * The document-build phases an {@link AstExtension} may fire at. `Changed` has
+ * no AST yet, and `IndexedContent` carries the same per-document information
+ * as `Parsed`, so neither is one.
+ */
+export type AstExtensionPhase =
+   | DocumentState.Parsed
+   | DocumentState.ComputedScopes
+   | DocumentState.Linked
+   | DocumentState.IndexedReferences
+   | DocumentState.Validated;
+
+export namespace 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.
+    */
+   export function all(): readonly AstExtensionPhase[] {
+      return [
+         DocumentState.Parsed,
+         DocumentState.ComputedScopes,
+         DocumentState.Linked,
+         DocumentState.IndexedReferences,
+         DocumentState.Validated
+      ];
+   }
+}
+
 /**
  * A registration that derives data from an AST node and attaches it to the
  * node at a declared document-build phase.
@@ -29,13 +58,13 @@ import { type AstExtensionRegistry } from './ast-extension-contribution.js';
  * are stored as non-enumerable own properties. Otherwise symbol providers,
  * folding, semantic tokens, and validators will treat them as real children.
  *
- * **Phase semantics:** {@link state} declares the single phase at which
+ * **Phase semantics:** {@link phase} declares the single phase at which
  * {@link compute} fires. The framework wires one `onDocumentPhase` listener per
- * useful state unconditionally, rather than deriving the set from the states
- * registrations declare — so a registration's state must be one of those, and
- * adding one is a framework change, not a registration-time choice.
+ * {@link AstExtensionPhase} unconditionally, rather than deriving the set from
+ * the phases registrations declare — so `register` refuses any other phase,
+ * and adding one is a framework change, not a registration-time choice.
  *
- * **`.ref`-dependent derivations: declare `state: ComputedScopes`, not `Linked`.**
+ * **`.ref`-dependent derivations: declare `phase: ComputedScopes`, not `Linked`.**
  * Lazy reference resolution is available from `ComputedScopes` onward — the
  * global scope is built by `IndexedContent` (which runs before
  * `ComputedScopes`), so reading a reference's `.ref` inside a `ComputedScopes`
@@ -44,8 +73,8 @@ import { type AstExtensionRegistry } from './ast-extension-contribution.js';
  * {@link DocumentBuilderOptions.refreshCrossDocumentComputedScopes} is set, so
  * one that reads another document's node goes stale when that node changes.
  *
- * **DO NOT** stage a `state: ComputedScopes` placeholder hoping to refine it
- * via a separate `state: Linked` registration when a downstream consumer
+ * **DO NOT** stage a `phase: ComputedScopes` placeholder hoping to refine it
+ * via a separate `phase: Linked` registration when a downstream consumer
  * (typically a `ScopeExtension.addDescriptions` firing during link)
  * iterates the derived value to build a scope: `onDocumentPhase(Linked)` fires
  * AFTER Langium's `Linker.link()` has already walked the document, by which
@@ -63,32 +92,26 @@ export interface AstExtension<T extends AstNode = AstNode> extends RegistryItem
    /**
     * Per-document early-out. When set, the framework only invokes the
     * registration's callback for documents the filter accepts. If every
-    * registration at a given state rejects the document, the framework skips
+    * registration at a given phase rejects the document, the framework skips
     * the `streamAllContents` walk entirely — important for large workspaces
     * where most documents carry none of the AST shapes a given extension
     * targets.
     *
-    * Default: no filter (registration applies to every document at its state).
+    * Default: no filter (registration applies to every document at its phase).
     */
    documentFilter?: (document: LangiumDocument) => boolean;
    /**
-    * The single document-build state at which {@link compute} fires.
+    * The single document-build phase at which {@link compute} fires.
     *
-    * Useful values:
     * - `Parsed` — derivations from AST shape only, no `.ref` reads.
-    * - `ComputedScopes` — lazy `.ref` resolution available; the most common state.
+    * - `ComputedScopes` — lazy `.ref` resolution available; the most common.
     * - `Linked` — derivations needing fully resolved cross-references.
     * - `IndexedReferences` — cross-document reverse-lookup derivations.
     * - `Validated` — derivations depending on diagnostics (rare).
-    *
-    * Any other state type-checks but never fires: the framework wires a
-    * listener only for the states above. `Changed` has no AST yet, and
-    * `IndexedContent` carries the same per-document information as `Parsed`,
-    * so neither is wired.
     */
-   state: DocumentState;
+   phase: AstExtensionPhase;
    /**
-    * Mutate `node` for this registration at {@link state}. The framework hands
+    * Mutate `node` for this registration at {@link phase}. The framework hands
     * `node` typed as {@link Mutable} so computed / synthetic property
     * assignments (`node._foo = ...`) compile without per-callback
     * `asMutable(...)` casts.
@@ -112,18 +135,18 @@ export interface AstExtension<T extends AstNode = AstNode> extends RegistryItem
  *
  * Adopter overrides go through {@link DefaultAstExtensionService}; the
  * interface keeps the public API stable while internals (the bucket-
- * by-state cache) stay `protected` on the default class.
+ * by-phase cache) stay `protected` on the default class.
  */
 export interface AstExtensionService extends AstExtensionRegistry {
    /**
     * Run a single AST node through every registration declaring
-    * `phase` as its state. Honours `documentFilter` and `nodeFilter`.
+    * `phase`. Honours `documentFilter` and `nodeFilter`.
     * Primarily for tests that need to invoke an extension callback without
     * driving Langium's full document-build pipeline.
     */
    extendNode(node: AstNode, document: LangiumDocument, phase: DocumentState): void;
    /**
-    * Re-run all `compute` callbacks declaring `phase` as their state against
+    * Re-run all `compute` callbacks declaring `phase` against
     * every node in the document. Single-pass. Called by
     * `BuildPipelineIntegration` from an `onDocumentPhase` listener;
     * not for general adopter use.
@@ -148,18 +171,18 @@ export type AstExtensionServiceOptions = LogNameOptions;
  * 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 implements AstExtensionService {
    protected readonly extensions = new Registry<AstExtension>();
    /**
-    * 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}).
     */
-   protected stateBuckets = new Map<DocumentState, readonly AstExtension[]>();
-   protected stateBucketsFor: readonly AstExtension[] | undefined;
+   protected phaseBuckets = new Map<DocumentState, readonly AstExtension[]>();
+   protected phaseBucketsFor: readonly AstExtension[] | undefined;
 
    protected readonly tracer: Tracer;
 
@@ -189,6 +212,16 @@ export class DefaultAstExtensionService implements AstExtensionService {
     * which calls {@link extendDocument} for the wired phases.
     */
    register<T extends AstNode>(extension: AstExtension<T>): Disposable {
+      // 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 as AstExtension);
@@ -196,10 +229,10 @@ export class DefaultAstExtensionService implements AstExtensionService {
 
    /**
     * Production code goes through {@link extendDocument} via the
-    * `onDocumentPhase(state)` listener wired by `BuildPipelineIntegration`.
+    * `onDocumentPhase(phase)` listener wired by `BuildPipelineIntegration`.
     */
    extendNode(node: AstNode, document: LangiumDocument, phase: DocumentState): void {
-      const bucket = this.getStateBucket(phase);
+      const bucket = this.getPhaseBucket(phase);
       for (const extension of bucket) {
          if (extension.documentFilter && !extension.documentFilter(document)) {
             continue;
@@ -228,7 +261,7 @@ export class DefaultAstExtensionService implements AstExtensionService {
       if (cancelToken?.isCancellationRequested) {
          return;
       }
-      const bucket = this.getStateBucket(phase);
+      const bucket = this.getPhaseBucket(phase);
       if (bucket.length === 0) {
          return;
       }
@@ -261,33 +294,33 @@ export class DefaultAstExtensionService implements AstExtensionService {
    }
 
    /**
-    * 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.
     */
-   protected getStateBucket(phase: DocumentState): readonly AstExtension[] {
+   protected getPhaseBucket(phase: DocumentState): readonly AstExtension[] {
       const current = this.extensions.all();
-      if (this.stateBucketsFor !== current) {
+      if (this.phaseBucketsFor !== current) {
          const next = new Map<DocumentState, AstExtension[]>();
          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: readonly AstExtension[] = Object.freeze([]);
+/** Shared empty result so `getPhaseBucket` doesn't allocate per call on the cold path. */
+const EMPTY_PHASE_BUCKET: readonly AstExtension[] = Object.freeze([]);
 
 /**
  * Assign a non-enumerable own property — for synthetic children that must NOT

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
@@ -31,7 +31,7 @@ import { type BuildPhasePass, type BuildPhasePassRegistry } from './build-phase-
  */
 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