@hydranium/core 1.0.0-next.38 → 1.0.0-next.380

package/src/documents/text-ledger.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 { type CanonicalUri, type TextVersion, textHash } from '@hydranium/protocol';
+import { type TextDocument } from 'vscode-languageserver-textdocument';
+
+/** What {@link TextLedger} holds for a document: where its version sequence stands, kept across closes and reopens. */
+export interface TextRecord {
+   readonly version: TextVersion;
+   /** {@link textHash} of the text at that version. */
+   readonly hash: string;
+}
+
+/**
+ * Where each document's {@link TextVersion} sequence stands, and who authored
+ * each version; the text-side counterpart of `ModelLedger`.
+ *
+ * A record survives the document's release and is never pruned, not even when
+ * the file is deleted: a sequence that restarts lets a write based on the old
+ * text pass the base-version gate. Authors last only until the release.
+ */
+export interface TextLedger {
+   /**
+    * The version a first open of `key` with `text` starts at: the record's
+    * version when the text is unchanged, one step on when it changed;
+    * `undefined` without a record.
+    */
+   openingVersion(key: CanonicalUri, text: string): TextVersion | undefined;
+   /** Keep where the sequence of the released `document` stands. */
+   record(key: CanonicalUri, document: TextDocument): void;
+   recordOf(key: CanonicalUri): TextRecord | undefined;
+   /**
+    * Text reached the closed document `key` outside the store's write paths.
+    * Steps the record iff `text` differs from it, and starts one at `0` when
+    * there is none.
+    */
+   reconcile(key: CanonicalUri, text: string): TextVersion;
+   /** {@link textHash} of `document`'s text, taken once per version. */
+   hashOf(document: TextDocument): string;
+   setAuthor(key: CanonicalUri, version: TextVersion, author: string): void;
+   /** The author of `version`, or of the latest version when `version` is omitted. */
+   authorOf(key: CanonicalUri, version?: TextVersion): string | undefined;
+   clearAuthors(key: CanonicalUri): void;
+}
+
+export class DefaultTextLedger implements TextLedger {
+   protected readonly records = new Map<CanonicalUri, TextRecord>();
+   protected readonly authors = new Map<CanonicalUri, string[]>();
+   protected readonly hashes = new WeakMap<TextDocument, { readonly version: number; readonly hash: string }>();
+
+   openingVersion(key: CanonicalUri, text: string): TextVersion | undefined {
+      const recorded = this.records.get(key);
+      if (recorded === undefined) {
+         return undefined;
+      }
+      return recorded.hash === textHash(text) ? recorded.version : recorded.version + 1;
+   }
+
+   record(key: CanonicalUri, document: TextDocument): void {
+      this.records.set(key, { version: document.version, hash: this.hashOf(document) });
+   }
+
+   recordOf(key: CanonicalUri): TextRecord | undefined {
+      return this.records.get(key);
+   }
+
+   reconcile(key: CanonicalUri, text: string): TextVersion {
+      const hash = textHash(text);
+      const recorded = this.records.get(key);
+      if (recorded?.hash === hash) {
+         return recorded.version;
+      }
+      const version = recorded === undefined ? 0 : recorded.version + 1;
+      this.records.set(key, { version, hash });
+      return version;
+   }
+
+   hashOf(document: TextDocument): string {
+      const taken = this.hashes.get(document);
+      if (taken?.version === document.version) {
+         return taken.hash;
+      }
+      const hash = textHash(document.getText());
+      this.hashes.set(document, { version: document.version, hash });
+      return hash;
+   }
+
+   setAuthor(key: CanonicalUri, version: TextVersion, author: string): void {
+      let history = this.authors.get(key);
+      if (!history) {
+         history = [];
+         this.authors.set(key, history);
+      }
+      history[version] = author;
+   }
+
+   authorOf(key: CanonicalUri, version?: TextVersion): string | undefined {
+      const history = this.authors.get(key);
+      // `!== undefined` so version 0 is not read as "latest".
+      return version !== undefined ? history?.[version] : history?.at(-1);
+   }
+
+   clearAuthors(key: CanonicalUri): void {
+      this.authors.delete(key);
+   }
+}

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

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

package/src/index.ts

@@ -28,12 +28,15 @@ export * from './langium/project/index.js';
 export * from './langium/residency/index.js';
 export * from './langium/scope/index.js';
 export * from './langium/serialization/index.js';
+export * from './langium/trivia/index.js';
 export * from './langium/transfer/index.js';
 export * from './langium/update-rewrite/index.js';
 export * from './langium/validation/index.js';
 export * from './langium/workspace/index.js';
 export * from './langium/service-registry.js';
 export * from './langium/language-types.js';
+export * from './langium/composite-ast-reflection.js';
+export * from './langium/single-langium-copy.js';
 export * from './launcher/index.js';
 export * from './locale/index.js';
 // The renderer only. The `./messages` subpath additionally enumerates this

package/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,20 +58,23 @@ 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`
  * callback triggers Langium's lazy lookup and returns the resolved target node.
+ * A cascade rebuild does not re-run such a derivation unless
+ * {@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
@@ -60,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.
@@ -109,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.
@@ -145,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;
 
@@ -186,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);
@@ -193,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;
@@ -225,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;
       }
@@ -258,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