@hydranium/core 1.0.0-next.10

package/src/documents/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './client-ids.js';
+export * from './language-client-text-shadow.js';
+export * from './hydranium-text-documents.js';
+export * from './ast-document-manager.js';
+export * from './self-save-registry.js';

package/src/documents/language-client-text-shadow.ts

@@ -0,0 +1,175 @@
+/********************************************************************************
+ * 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 { diffLines } from 'diff';
+import { Range, type TextEdit, uinteger } from 'vscode-languageserver';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+
+/**
+ * The minimum surface the shadow needs from a `HydraniumTextDocuments`:
+ * a `create` method that materialises a fresh text document via the
+ * configured `TextDocumentsConfiguration`. Declared as a narrow
+ * structural interface so the manager satisfies it without an explicit
+ * import (sidestepping the circular `HydraniumTextDocuments → shadow → manager`
+ * dependency) and so tests can stub it with a minimal object literal.
+ */
+export interface ShadowDocumentSource {
+   create(uri: string, languageId: string, version: number, content: string): TextDocument;
+}
+
+/** The range every full-document replace emitted here carries. */
+const FULL_RANGE = Range.create(0, 0, uinteger.MAX_VALUE, uinteger.MAX_VALUE);
+
+/**
+ * Whether `edits` is the single full-document replace {@link LanguageClientTextShadow.computeEdits}
+ * emits when it has no usable baseline.
+ *
+ * The distinction matters at the `workspace/applyEdit` egress: a full replace is
+ * position-INDEPENDENT and therefore lands correctly on any client buffer, while
+ * a line-keyed diff only lands correctly on the exact text it was diffed
+ * against. Only the latter needs a client-version gate.
+ */
+export function isFullReplace(edits: readonly TextEdit[]): boolean {
+   if (edits.length !== 1) {
+      return false;
+   }
+   const { start, end } = edits[0].range;
+   return start.line === FULL_RANGE.start.line && start.character === FULL_RANGE.start.character && end.line === FULL_RANGE.end.line;
+}
+
+/**
+ * Tracks the text content the language client (typically Monaco) is believed to
+ * currently hold so outgoing `workspace/applyEdit` requests can ship minimal
+ * diffs instead of full-document replaces.
+ *
+ * Why it matters: a full-range replace on a moderately-sized YAML or DSL source
+ * forces Monaco to re-tokenise the entire document (observed multi-second hangs
+ * on large diagrams), whereas line-level diffs usually reduce that to a handful
+ * of small edits.
+ *
+ * Update points the caller is responsible for:
+ *  - {@link computeEdits} after each outgoing server→client sync (updates the shadow optimistically).
+ *  - {@link set} when the server receives a `didChange` from the language client (the client now
+ *    holds that text; we shouldn't resend it).
+ *  - {@link invalidate} when the client rejects an edit (`applied=false`) or a doc is closed —
+ *    the shadow is now stale and the next sync must fall back to a full replace.
+ */
+export class LanguageClientTextShadow {
+   protected shadow = new Map<string, string>();
+
+   /**
+    * @param onFallback invoked when {@link computeEdits} falls back to a full-range replace due to
+    *    apply-verify mismatch. Useful for logging regressions.
+    * @param documents the {@link ShadowDocumentSource} used to materialise the throwaway probe
+    *    document in {@link computeEdits}. In production this is the owning
+    *    `HydraniumTextDocuments` (whose `create` threads through its configured
+    *    `TextDocumentsConfiguration`); tests pass a minimal stub. Routing
+    *    through the manager rather than `TextDocument.create` directly avoids the
+    *    `instanceof FullTextDocument` gate in the bare LSP `TextDocument.update`,
+    *    keeping the verifier honest for adopters with a custom text-document type.
+    */
+   constructor(
+      protected onFallback: (uri: string, reason: string) => void,
+      protected documents: ShadowDocumentSource
+   ) {}
+
+   /** Record the text the language client is known to hold (e.g. after a `didChange` echo). */
+   set(uri: string, text: string): void {
+      this.shadow.set(uri, text);
+   }
+
+   /**
+    * The text the language client is believed to hold, or `undefined` when
+    * there is no baseline (first sync, or after an {@link invalidate}).
+    *
+    * Read at the `workspace/applyEdit` egress BEFORE {@link computeEdits},
+    * which overwrites it: a push's minimal edits are keyed to this text, so an
+    * echo of that push carries ranges addressing it and nothing else. Losing
+    * it is what makes an incremental echo unreconstructable, and applying such
+    * an echo to the already-advanced synced text duplicates every inserted
+    * line.
+    */
+   get(uri: string): string | undefined {
+      return this.shadow.get(uri);
+   }
+
+   /** Forget the shadow for a URI; next {@link computeEdits} falls back to a full-document replace. */
+   invalidate(uri: string): void {
+      this.shadow.delete(uri);
+   }
+
+   /**
+    * Return the minimal LSP {@link TextEdit}s required to bring the language client's content from
+    * the tracked shadow to `newText`. Updates the shadow to `newText` so subsequent calls diff
+    * against it.
+    *
+    *  - Empty array when the shadow already equals `newText` (caller should skip the RPC).
+    *  - Full-range replace when there is no shadow (first sync or post-{@link invalidate}).
+    *  - Line-level diff otherwise. Before returning, we locally reconstruct `newText` by applying
+    *    the diff to `old`; if that doesn't match, we fall back to a full-range replace and notify
+    *    the fallback callback. This catches any algorithmic regression in {@link diffToEdits}
+    *    without risking client corruption.
+    */
+   computeEdits(uri: string, newText: string): TextEdit[] {
+      const old = this.shadow.get(uri);
+      if (old === newText) {
+         return [];
+      }
+      this.shadow.set(uri, newText);
+      const fullReplace: TextEdit = { range: FULL_RANGE, newText };
+      if (old === undefined) {
+         return [fullReplace];
+      }
+      const edits = diffToEdits(old, newText);
+      const verifyDoc = this.documents.create(uri, 'plaintext', 0, old);
+      if (TextDocument.applyEdits(verifyDoc, edits) !== newText) {
+         this.onFallback(uri, 'apply-verify-mismatch');
+         return [fullReplace];
+      }
+      return edits;
+   }
+}
+
+/**
+ * Convert a {@link diffLines} result to a list of LSP {@link TextEdit}s keyed on line positions
+ * in the *old* text. Contiguous added/removed hunks are coalesced into a single replace so the
+ * client sees one edit per changed region.
+ */
+export function diffToEdits(oldText: string, newText: string): TextEdit[] {
+   const hunks = diffLines(oldText, newText);
+   const edits: TextEdit[] = [];
+   let oldLine = 0;
+   let i = 0;
+   while (i < hunks.length) {
+      const hunk = hunks[i];
+      if (!hunk.added && !hunk.removed) {
+         oldLine += hunk.count ?? 0;
+         i++;
+         continue;
+      }
+      // Coalesce a run of add/remove hunks into a single replace for this region.
+      let removedLines = 0;
+      let addedText = '';
+      while (i < hunks.length && (hunks[i].added || hunks[i].removed)) {
+         if (hunks[i].removed) {
+            removedLines += hunks[i].count ?? 0;
+         }
+         if (hunks[i].added) {
+            addedText += hunks[i].value;
+         }
+         i++;
+      }
+      edits.push({
+         range: Range.create(oldLine, 0, oldLine + removedLines, 0),
+         newText: addedText
+      });
+      oldLine += removedLines;
+   }
+   return edits;
+}

package/src/documents/self-save-registry.ts

@@ -0,0 +1,81 @@
+/********************************************************************************
+ * 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 Clock } from '@hydranium/protocol';
+import { isCaseInsensitiveFileSystem } from '../util/environment.js';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+
+/** Default eligibility window for a self-save entry. */
+const DEFAULT_TTL_MS = 30_000;
+
+export interface SelfSaveRegistryOptions {
+   /** How long a self-save entry stays eligible to match a watcher event. Default {@link DEFAULT_TTL_MS}. */
+   ttlMs?: number;
+}
+
+/**
+ * Tracks `mtime` of files written by the server itself so the echo
+ * `didChangeWatchedFiles` event from the OS file watcher can be suppressed,
+ * avoiding redundant rebuilds after each save. Entries are matched by mtime
+ * (not by a time window) and expire after a TTL.
+ */
+export class SelfSaveRegistry {
+   protected readonly entries = new Map<string, { mtimeMs: number; registeredAt: number }>();
+   /**
+    * Read time through the shared {@link Clock} rather than `Date.now()`: the
+    * TTL gates whether an incoming watcher event still counts as a self-save
+    * echo, so tests advance a fake clock to exercise expiry without a real
+    * wait. Wall-clock `now()` is correct here — entries are compared against a
+    * file's `mtime`.
+    */
+   protected readonly clock: Clock;
+   protected readonly ttlMs: number;
+
+   constructor(services: Pick<ServerSharedServicesMinimal, 'Clock'>, options: SelfSaveRegistryOptions = {}) {
+      this.clock = services.Clock;
+      this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+   }
+
+   /**
+    * Key a path the way the host filesystem compares it.
+    *
+    * Registering and matching happen on different paths for the same file: the
+    * write path comes from the server, the echo from the OS watcher, and on a
+    * case-insensitive filesystem those two can disagree in case for one file.
+    * A raw key then misses the suppression and the server's own write is
+    * rebuilt as a foreign change.
+    *
+    * Folded ONLY where the filesystem folds. On Linux two paths differing in
+    * case are two files, and collapsing them would suppress a real change to
+    * the other one — a correctness bug traded for an optimisation.
+    */
+   protected key(fsPath: string): string {
+      return isCaseInsensitiveFileSystem() ? fsPath.toLowerCase() : fsPath;
+   }
+
+   /** Record a self-write. Key by `fsPath` (not URI string) to avoid URI-form mismatches. */
+   register(fsPath: string, mtimeMs: number): void {
+      this.entries.set(this.key(fsPath), { mtimeMs, registeredAt: this.clock.now() });
+   }
+
+   /** True if `mtimeMs` matches a recent self-write. Evicts stale entries. Not consumed on match. */
+   matches(fsPath: string, mtimeMs: number): boolean {
+      const key = this.key(fsPath);
+      const entry = this.entries.get(key);
+      if (!entry) {
+         return false;
+      }
+      if (this.clock.now() - entry.registeredAt > this.ttlMs) {
+         this.entries.delete(key);
+         return false;
+      }
+      // Accept mtime equality (some filesystems have 1-second precision).
+      return entry.mtimeMs === mtimeMs;
+   }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Public API barrel for the head-neutral `.` entry point.
+export * from './langium/ast-extension/index.js';
+export * from './langium/build-phase-pass/index.js';
+export * from './langium/bootstrap.js';
+export * from './langium/config/index.js';
+export * from './langium/integration-services.js';
+export * from './langium/diagnostics/index.js';
+export * from './langium/document-builder/index.js';
+export * from './langium/integrity/index.js';
+export * from './langium/language-module.js';
+export * from './langium/model-service/index.js';
+export * from './langium/module.js';
+export * from './langium/shared-services.js';
+export * from './langium/keys/index.js';
+export * from './langium/documentation/index.js';
+export * from './langium/labeling/index.js';
+export * from './langium/naming/index.js';
+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/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 './launcher/index.js';
+export * from './documents/index.js';
+export * from './util/index.js';

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

@@ -0,0 +1,35 @@
+/********************************************************************************
+ * 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 AstNode } from '@hydranium/langium';
+import { type Disposable } from 'vscode-languageserver';
+import { type AstExtension } from './ast-extension-service.js';
+
+/**
+ * Registry handed to an {@link AstExtensionContribution}. Implemented by the
+ * AST-extension service; a contribution receives it and registers one or many
+ * AST extensions (build-phase computed / synthetic properties). Doubles as
+ * the low-level imperative API.
+ */
+export interface AstExtensionRegistry {
+   register<T extends AstNode>(extension: AstExtension<T>): Disposable;
+}
+
+/**
+ * Declarative registration of AST extensions. Bound under the module's
+ * `ast.extensions` contribution group; the AST-extension service reads that
+ * group at construction and calls this method, handing itself in as the
+ * registry.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface AstExtensionContribution {
+   registerAstExtensions(registry: AstExtensionRegistry): void;
+}

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

@@ -0,0 +1,311 @@
+/********************************************************************************
+ * 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 { Logger, type Mutable, type Tracer } from '@hydranium/protocol';
+import { type AstNode, AstUtils, DocumentState, type LangiumDocument } from '@hydranium/langium';
+import type { CancellationToken, Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { Registry, type RegistryItem } from '../../util/registry.js';
+import { type AstExtensionRegistry } from './ast-extension-contribution.js';
+
+/**
+ * A registration that derives data from an AST node and attaches it to the
+ * node at a declared document-build phase.
+ *
+ * **Storage:** plain assignment (`node._foo = value`) is correct for primitives,
+ * objects, and arrays of non-AstNode values — Langium's `streamContents` walks
+ * own *enumerable* properties whose values are AstNodes (or arrays of them) and
+ * skips everything else.
+ *
+ * **Synthetic children** (AstNode-shaped values that should *not* be walked as
+ * containment children) must be assigned via {@link setHiddenProperty} so they
+ * 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
+ * {@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.
+ *
+ * **`.ref`-dependent derivations: declare `state: 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.
+ *
+ * **DO NOT** stage a `state: ComputedScopes` placeholder hoping to refine it
+ * via a separate `state: 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
+ * time the linker has resolved references against the placeholder and cached
+ * them as `LinkingError`. Populate at `ComputedScopes` via lazy `.ref`
+ * resolution instead.
+ *
+ * **Description contribution.** This hook does not return descriptions — it
+ * mutates the node only. Per-reference-type description contribution lives on
+ * `ScopeExtension.addDescriptions` (the acceptor-style sibling).
+ */
+export interface AstExtension<T extends AstNode = AstNode> extends RegistryItem {
+   /** Type-guard predicate — `compute` runs only on nodes for which this returns `true`. */
+   nodeFilter: (node: AstNode) => node is T;
+   /**
+    * 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
+    * 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).
+    */
+   documentFilter?: (document: LangiumDocument) => boolean;
+   /**
+    * The single document-build state 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.
+    * - `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;
+   /**
+    * Mutate `node` for this registration at {@link state}. The framework hands
+    * `node` typed as {@link Mutable} so computed / synthetic property
+    * assignments (`node._foo = ...`) compile without per-callback
+    * `asMutable(...)` casts.
+    *
+    * Sync-only by Langium contract: `ScopeComputation.collectLocalSymbols`
+    * iterates without awaiting, and `onDocumentPhase(ComputedScopes)` fires
+    * right after — async work returned would resolve out of order vs the
+    * local-symbol table read. Adopters needing async derivation must build
+    * the data ahead of time and hand a sync callback.
+    */
+   compute(node: Mutable<T>, document: LangiumDocument): void;
+}
+
+/**
+ * Public contract for the per-language AST-extension service. Extends the
+ * {@link AstExtensionRegistry} (the imperative `register` surface
+ * contributions use) with the dispatch entry points. Only
+ * {@link AstExtensionService.extendDocument} is called cross-class from
+ * `BuildPipelineIntegration`, as documents reach each wired phase;
+ * {@link AstExtensionService.extendNode} has no production caller.
+ *
+ * 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.
+ */
+export interface AstExtensionService extends AstExtensionRegistry {
+   /**
+    * Run a single AST node through every registration declaring
+    * `phase` as its state. 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
+    * every node in the document. Single-pass. Called by
+    * `BuildPipelineIntegration` from an `onDocumentPhase` listener;
+    * not for general adopter use.
+    */
+   extendDocument(document: LangiumDocument, phase: DocumentState, cancelToken?: CancellationToken): void;
+}
+
+/** Construction options for {@link DefaultAstExtensionService}. */
+export type AstExtensionServiceOptions = LogNameOptions;
+
+/**
+ * Default {@link AstExtensionService} implementation. Generic registry for
+ * build-phase AST-node enrichment: computed properties and synthetic
+ * children. The sibling scope-contribution concern (extra resolvable
+ * descriptions at query time) lives in `ScopeExtensionService`.
+ *
+ * Designed as a base class; consumers extend it and call `register` in
+ * their constructor.
+ *
+ * Build-phase invocation is driven by `BuildPipelineIntegration`,
+ * which calls {@link extendDocument} for the wired phases — this class
+ * 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.
+ */
+export class DefaultAstExtensionService implements AstExtensionService {
+   protected readonly extensions = new Registry<AstExtension>();
+   /**
+    * Per-state bucket of registrations targeting each state. 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 readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerLanguageServices,
+      options: AstExtensionServiceOptions = {}
+   ) {
+      this.tracer = services.shared.Tracer.for(options.logName ?? 'AstExtension').trace('instantiated');
+
+      // Read the language's AstExtensionContribution group and let each
+      // contribution register one or many extensions through this service.
+      // Optional chaining tolerates incomplete test stubs; production
+      // wiring always provides the slot via `createServerLanguageModule`.
+      const contributions = services.ast?.extensions ?? {};
+      for (const contribution of Object.values(contributions)) {
+         contribution.registerAstExtensions(this);
+      }
+   }
+
+   /**
+    * Register a single AST extension. Doubles as the imperative low-level
+    * API and as the {@link AstExtensionRegistry} entry point that
+    * `AstExtensionContribution.registerAstExtensions` hands to
+    * contributions. Throws on duplicate id.
+    *
+    * Build-phase invocation is driven by `BuildPipelineIntegration`,
+    * which calls {@link extendDocument} for the wired phases.
+    */
+   register<T extends AstNode>(extension: AstExtension<T>): Disposable {
+      // 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);
+   }
+
+   /**
+    * Production code goes through {@link extendDocument} via the
+    * `onDocumentPhase(state)` listener wired by `BuildPipelineIntegration`.
+    */
+   extendNode(node: AstNode, document: LangiumDocument, phase: DocumentState): void {
+      const bucket = this.getStateBucket(phase);
+      for (const extension of bucket) {
+         if (extension.documentFilter && !extension.documentFilter(document)) {
+            continue;
+         }
+         if (!extension.nodeFilter(node)) {
+            continue;
+         }
+         extension.compute(node as Mutable<AstNode>, document);
+      }
+   }
+
+   /**
+    * Skips the walk entirely when no registration applies to this document
+    * (either no registration declares `phase`, or every applicable
+    * registration's `documentFilter` rejects the document).
+    *
+    * `cancelToken` is checked at entry — `onDocumentPhase` is invoked once per
+    * document by Langium, so an entry-check skips the `streamAllContents`
+    * walk for any document arriving after the build is preempted. The
+    * per-registration / per-node loops stay sync (no inner `interruptAndCheck`)
+    * to avoid async coloring through the property-walk callbacks; the
+    * downstream throughput hit from running one extra document's walk is
+    * smaller than the microtask cost of yielding inside the walk.
+    */
+   extendDocument(document: LangiumDocument, phase: DocumentState, cancelToken?: CancellationToken): void {
+      if (cancelToken?.isCancellationRequested) {
+         return;
+      }
+      const bucket = this.getStateBucket(phase);
+      if (bucket.length === 0) {
+         return;
+      }
+      // Per-document filter: registrations without `documentFilter` always apply.
+      // If every registration rejects the document, skip the streamAllContents walk.
+      const applicable = bucket.filter(extension => !extension.documentFilter || extension.documentFilter(document));
+      if (applicable.length === 0) {
+         return;
+      }
+      // Per-registration self-time profiling is opt-in: only open a session when
+      // the debug threshold is active, so the production path allocates nothing
+      // and the per-(node×registration) loop stays a single const-branch off
+      // `session`. `ProfileSession.scope` is NOT itself level-gated.
+      const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`ast-extension ${DocumentState[phase]}`) : undefined;
+      for (const node of AstUtils.streamAllContents(document.parseResult.value)) {
+         for (const extension of applicable) {
+            if (extension.nodeFilter(node)) {
+               // Scope per registration id so the session aggregates self-time by
+               // extension across every node; off the profiling path call directly.
+               if (session) {
+                  session.scope(extension.id, () => extension.compute(node as Mutable<AstNode>, document));
+               } else {
+                  extension.compute(node as Mutable<AstNode>, document);
+               }
+            }
+         }
+      }
+      // One line per registration (count + self-% + self-ms), sorted — only when profiling.
+      session?.report('debug');
+   }
+
+   /**
+    * Bucket-by-state 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
+    * register / unregister.
+    */
+   protected getStateBucket(phase: DocumentState): readonly AstExtension[] {
+      const current = this.extensions.all();
+      if (this.stateBucketsFor !== current) {
+         const next = new Map<DocumentState, AstExtension[]>();
+         for (const extension of current) {
+            let bucket = next.get(extension.state);
+            if (!bucket) {
+               bucket = [];
+               next.set(extension.state, bucket);
+            }
+            bucket.push(extension);
+         }
+         this.stateBuckets = next;
+         this.stateBucketsFor = current;
+      }
+      return this.stateBuckets.get(phase) ?? EMPTY_STATE_BUCKET;
+   }
+}
+
+/** Shared empty result so `getStateBucket` doesn't allocate per call on the cold path. */
+const EMPTY_STATE_BUCKET: readonly AstExtension[] = Object.freeze([]);
+
+/**
+ * Assign a non-enumerable own property — for synthetic children that must NOT
+ * be walked by Langium's `streamContents`.
+ *
+ * Direct reads (`node._foo`) still work. In its default `full` transfer mode
+ * the encoder enumerates via `Object.getOwnPropertyNames`, so the property
+ * still crosses to the wire shape; `grammar` mode enumerates the reflection's
+ * declared-property allowlist instead and therefore drops it.
+ *
+ * Use when assigning AstNode-shaped values that should not appear as
+ * containment children to symbol providers, folding, semantic tokens, or
+ * validators. Plain non-AstNode values (strings, booleans, plain objects) can
+ * be assigned with `node._foo = value` directly — Langium's iteration only
+ * yields AstNode-shaped values, so non-AST data is naturally invisible.
+ */
+export function setHiddenProperty<V>(node: object, property: string, value: V): void {
+   Object.defineProperty(node, property, {
+      value,
+      writable: true,
+      configurable: true,
+      enumerable: false
+   });
+}