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

package/src/langium/scope/fallback-scope.ts

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * 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 AstNodeDescription, type Scope, type Stream } from '@hydranium/langium';
+
+/**
+ * A scope that answers from `primary`, and from `fallback` only for a name
+ * `primary` does not hold.
+ *
+ * Langium fixes a scope's outer scope when the scope is built, so a tier cannot
+ * be put below a scope that already exists, such as a cached one. Re-wrapping
+ * that scope's elements instead would turn its keyed lookup into a scan of
+ * every element; chaining keeps each scope's own lookup.
+ */
+export class FallbackScope implements Scope {
+   constructor(
+      protected readonly primary: Scope,
+      protected readonly fallback: Scope
+   ) {}
+
+   getElement(name: string): AstNodeDescription | undefined {
+      return this.primary.getElement(name) ?? this.fallback.getElement(name);
+   }
+
+   getElements(name: string): Stream<AstNodeDescription> {
+      return this.primary.getElements(name).concat(this.fallback.getElements(name));
+   }
+
+   getAllElements(): Stream<AstNodeDescription> {
+      return this.primary.getAllElements().concat(this.fallback.getAllElements());
+   }
+}

package/src/langium/scope/hydranium-scope-computation.ts

@@ -10,15 +10,13 @@
 import {
    type AstNode,
    type AstNodeDescription,
-   AstUtils,
    DefaultScopeComputation,
-   interruptAndCheck,
    type LangiumDocument,
    type LocalSymbols,
-   MultiMap,
+   type MultiMap,
    UriUtils
 } from '@hydranium/langium';
-import { Logger, type Tracer } from '@hydranium/protocol';
+import { Logger, type ProfileSession, type Tracer } from '@hydranium/protocol';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
 import type { LogNameOptions } from '../diagnostics/logger.js';
 import type { HydraniumLanguageServices } from '../language-module.js';
@@ -35,8 +33,9 @@ import { type HydraniumAstNodeDescriptionProvider } from './ast-node-description
  *   `NameProvider.getName` defaults to the workspace-unique
  *   `getProjectQualifiedName`. Routing the local-symbols pass through
  *   `getName` would put qualified names in the per-document symbol map
- *   and break within-document bare-name references. {@link addLocalSymbol}
- *   bypasses the default and calls {@link NameProvider.getOwnName}
+ *   and break within-document bare-name references.
+ *   {@link addLocalSymbolByOwnName} bypasses the default and calls
+ *   {@link NameProvider.getOwnName}
  *   directly so local symbols stay keyed by bare names regardless of
  *   what `getName` returns.
  *
@@ -55,11 +54,15 @@ import { type HydraniumAstNodeDescriptionProvider } from './ast-node-description
  *
  * Performance: piggybacks on the existing single AST walk Langium does
  * for local-symbol collection — the AST-extension dispatch and the
- * own-name read both happen in `addLocalSymbol`, no extra traversal.
+ * own-name read both happen in `addLocalSymbolByOwnName`, no extra traversal.
  * The exported-symbol pass reads both name tiers once per node, no
  * duplicated walks.
  */
 export class HydraniumScopeComputation extends DefaultScopeComputation {
+   /** The framework's name provider, which its language module binds to the slot. */
+   declare protected readonly nameProvider: NameProvider;
+   /** The framework's description provider, which its language module binds to the slot. */
+   declare protected readonly descriptions: HydraniumAstNodeDescriptionProvider;
    protected readonly tracer: Tracer;
 
    constructor(
@@ -70,38 +73,30 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
       this.tracer = services.shared.Tracer.for(options.logName ?? 'ScopeComputation').trace('instantiated');
    }
 
+   /** The session {@link addLocalSymbol} records into while a `debug`-level walk runs. */
+   protected localSymbolsProfile: ProfileSession | undefined;
+
    /**
-    * Local-symbol collection with optional per-`$type` self-time profiling.
-    *
-    * Langium's default walks the full AST and calls {@link addLocalSymbol} per
-    * node. At the default `info` level this delegates straight to `super` (zero
-    * cost). At `debug` it reproduces the same walk under a `ProfileSession`
-    * so each `$type`'s contribution to the heaviest scope-computation pass is
-    * aggregated and reported line-based — the walk is gated rather than the
-    * per-node `scope`, since `ProfileSession.scope` is not itself level-gated.
-    *
-    * The instance carries no profiling state: the session is local to the call,
-    * which is safe because Langium's document builder runs `collectLocalSymbols`
-    * strictly one document at a time (`runCancelable`'s sequential `for…await`).
+    * Langium's local-symbol walk, with per-`$type` self-time profiling at
+    * `debug`. The walk is Langium's at every level: a copy run only at `debug`
+    * would drift from the one every other level runs. Overlapping builds share
+    * the session and blur each other's report.
     */
    override async collectLocalSymbols(document: LangiumDocument, cancelToken?: CancellationToken): Promise<LocalSymbols> {
       if (!Logger.isLevelEnabled('debug')) {
          return super.collectLocalSymbols(document, cancelToken);
       }
-      // Faithfully reproduces Langium's local-symbol walk (root's full-AST stream
-      // → addLocalSymbol per node) under a session. The MultiMap conforms to
-      // LocalSymbols. interruptAndCheck only when a token is supplied (the base
-      // defaults to CancellationToken.None, a no-op token).
-      const rootNode = document.parseResult.value;
-      const symbols = new MultiMap<AstNode, AstNodeDescription>();
-      const session = this.tracer.profile(`scope-local ${UriUtils.basename(document.uri)}`);
-      for (const node of AstUtils.streamAllContents(rootNode)) {
-         if (cancelToken) {
-            await interruptAndCheck(cancelToken);
+      const profile = this.tracer.profile(`scope-local ${UriUtils.basename(document.uri)}`);
+      this.localSymbolsProfile = profile;
+      let symbols: LocalSymbols;
+      try {
+         symbols = await super.collectLocalSymbols(document, cancelToken);
+      } finally {
+         if (this.localSymbolsProfile === profile) {
+            this.localSymbolsProfile = undefined;
          }
-         session.scope(node.$type, () => this.addLocalSymbol(node, document, symbols));
       }
-      session.report('debug');
+      profile.report('debug');
       return symbols;
    }
 
@@ -164,17 +159,15 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * workspace-visible rather than being filtered out everywhere.
     */
    protected exportProject(node: AstNode, exports: AstNodeDescription[], document: LangiumDocument): void {
-      const nameProvider = this.nameProvider as NameProvider;
-      const documentName = nameProvider.getDocumentQualifiedName(node);
+      const documentName = this.nameProvider.getDocumentQualifiedName(node);
       if (!documentName) {
          return;
       }
       const projectId = this.getProjectIdForDocument(document);
-      const descriptions = this.descriptions as HydraniumAstNodeDescriptionProvider;
       exports.push(
          projectId !== undefined
-            ? descriptions.createProject({ node, name: documentName, document, projectId })
-            : descriptions.createUniversal({ node, name: documentName, document })
+            ? this.descriptions.createProject({ node, name: documentName, document, projectId })
+            : this.descriptions.createUniversal({ node, name: documentName, document })
       );
    }
 
@@ -191,16 +184,14 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * document-qualified name.
     */
    protected exportPublic(node: AstNode, exports: AstNodeDescription[], document: LangiumDocument): void {
-      const nameProvider = this.nameProvider as NameProvider;
       const projectId = this.getProjectIdForDocument(document);
       if (projectId === undefined) {
          return;
       }
-      const documentName = nameProvider.getDocumentQualifiedName(node);
-      const projectName = nameProvider.getProjectQualifiedName(node);
+      const documentName = this.nameProvider.getDocumentQualifiedName(node);
+      const projectName = this.nameProvider.getProjectQualifiedName(node);
       if (projectName && projectName !== documentName) {
-         const descriptions = this.descriptions as HydraniumAstNodeDescriptionProvider;
-         exports.push(descriptions.createPublic({ node, name: projectName, document, projectId }));
+         exports.push(this.descriptions.createPublic({ node, name: projectName, document, projectId }));
       }
    }
 
@@ -218,6 +209,16 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
       return this.services.shared.workspace.ProjectManager.getProject(document.uri)?.id;
    }
 
+   /** {@link addLocalSymbolByOwnName}, timed per `$type` while {@link localSymbolsProfile} is set. */
+   protected override addLocalSymbol(node: AstNode, document: LangiumDocument, symbols: MultiMap<AstNode, AstNodeDescription>): void {
+      const profile = this.localSymbolsProfile;
+      if (profile) {
+         profile.scope(node.$type, () => this.addLocalSymbolByOwnName(node, document, symbols));
+      } else {
+         this.addLocalSymbolByOwnName(node, document, symbols);
+      }
+   }
+
    /**
     * Bypasses Langium's `super.addLocalSymbol` (which would key the
     * local-symbols map by `nameProvider.getName(node)`, qualified by
@@ -233,14 +234,14 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * extension `compute` callbacks fire after this `addLocalSymbol` pass
     * completes for the whole document.
     */
-   protected override addLocalSymbol(node: AstNode, document: LangiumDocument, symbols: MultiMap<AstNode, AstNodeDescription>): void {
+   protected addLocalSymbolByOwnName(node: AstNode, document: LangiumDocument, symbols: MultiMap<AstNode, AstNodeDescription>): void {
       const container = node.$container;
       if (!container) {
          return;
       }
-      const name = (this.nameProvider as NameProvider).getOwnName(node);
+      const name = this.nameProvider.getOwnName(node);
       if (name) {
-         symbols.add(container, (this.descriptions as HydraniumAstNodeDescriptionProvider).createLocal({ node, name, document }));
+         symbols.add(container, this.descriptions.createLocal({ node, name, document }));
       }
    }
 }

package/src/langium/scope/hydranium-scope-provider.ts

@@ -24,11 +24,12 @@ import {
    type AstNodeLocator,
    AstUtils,
    DefaultScopeProvider,
+   type LocalSymbols,
    MapScope,
+   MultiMapScope,
    type ReferenceInfo,
    type Scope,
    type ScopeOptions,
-   StreamScope,
    type URI,
    UriUtils,
    WorkspaceCache,
@@ -39,8 +40,10 @@ import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumLanguageServices } from '../language-module.js';
 import { type NameProvider } from '../naming/name-provider.js';
 import { type HydraniumDocumentRegistry } from '../workspace/langium-documents.js';
-import { type ScopeExtensionService } from './scope-extension-service.js';
-import { isTieredDescription } from './scoped-ast-node-description.js';
+import { builtLocalSymbols } from './built-local-symbols.js';
+import { FallbackScope } from './fallback-scope.js';
+import { type ScopeExtensionDescriptions, type ScopeExtensionService } from './scope-extension-service.js';
+import { type TieredAstNodeDescription, isTieredDescription } from './scoped-ast-node-description.js';
 
 /**
  * Construction-time options for {@link HydraniumScopeProvider}. Extends
@@ -95,7 +98,7 @@ export interface ScopeContext {
 /**
  * Per-language scope provider that owns the full scope chain in ONE
  * class. Bridges the protocol-layer {@link ReferenceContext} to
- * Langium's {@link ReferenceInfo}, layers per-context scope-extension
+ * Langium's {@link ReferenceInfo}, layers scope-extension
  * contributions ({@link ScopeExtensionService}) at their declared tier,
  * and composes the cached project-tier chain (own-project → dependency
  * → universal) on top of Langium's unfiltered global index.
@@ -103,16 +106,16 @@ export interface ScopeContext {
  * ## Scope chain (high → low, inner shadows outer)
  *
  * ```
- *   document-local (Langium precomputed)        [DefaultScopeProvider.getScope]
- *     extension:local                           [layerLocalExtension, per-context]
+ *   document-local (Langium precomputed)        [getScope, CACHED per build in localScope]
+ *     extension:local                           [layerLocalExtension, CACHED per descriptions]
  *       own-project → dependency → universal-index   [createGlobalScope default, CACHED per ${project}::${refType}]
- *         extension:universal                   [layerUniversalExtension, per-context, outermost]
+ *         extension:universal                   [layerUniversalExtension, CACHED per descriptions, outermost]
  * ```
  *
- * Implementation: Langium's `getScope` layers document-local on top of
- * whatever `getGlobalScope` returns. The framework owns `getGlobalScope`
- * and uses it to assemble everything *below* document-local, with the
- * adopter-overridable {@link createGlobalScope} in the middle.
+ * Implementation: {@link getScope} layers document-local on top of
+ * whatever `getGlobalScope` returns, as Langium's does. The framework owns
+ * `getGlobalScope` and uses it to assemble everything *below* document-local,
+ * with the adopter-overridable {@link createGlobalScope} in the middle.
  *
  * ## Adopter override surface
  *
@@ -132,7 +135,8 @@ export interface ScopeContext {
  * - **{@link createScopeForNodes}** — inherited from Langium and re-keyed by
  *   the framework to bare own-names, so it is the helper a `getScope`
  *   override uses to resolve a dotted member reference against a container
- *   the reference chain cannot reach.
+ *   the reference chain cannot reach. Override {@link createNodeScope} to
+ *   change the scope it builds.
  *
  * **Do NOT override `getGlobalScope` itself** — that is the framework's
  * extension-assembly seam. Overriding it would hide the scope-extension
@@ -161,6 +165,24 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * the workspace-global `DocumentBuilder.onUpdate`.
     */
    protected readonly scopeCache: WorkspaceCache<string, Scope>;
+   /**
+    * Each container's local scope per reference type, keyed by the local
+    * symbols it was built from. A build replaces a document's local symbols
+    * when it recomputes them, so a rebuilt document never reads a stale entry.
+    */
+   protected readonly localScopes = new WeakMap<LocalSymbols, Map<AstNode, Map<string, Scope>>>();
+   /**
+    * {@link createScopeForNodes}' scope per list of nodes, keyed by the local
+    * symbols of the document the nodes belong to, which a rebuild of that
+    * document replaces.
+    */
+   protected readonly nodeScopes = new WeakMap<LocalSymbols, WeakMap<readonly AstNode[], Scope>>();
+   /**
+    * The scope of each scope extension's descriptions of one tier, keyed by
+    * the array: an extension with a cache key answers every reference of that
+    * key with the same one.
+    */
+   protected readonly extensionScopes = new WeakMap<readonly TieredAstNodeDescription[], Scope>();
    protected readonly tracer: Tracer;
    /**
     * Narrows the inherited Langium {@link NameProvider} field to the framework's
@@ -183,19 +205,115 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
       this.tracer = services.shared.Tracer.for(options.logName ?? 'ScopeProvider').trace('instantiated');
    }
 
+   /**
+    * Drop every cached scope — the framework's project-tier chain and the
+    * inherited global scope it is filtered from.
+    *
+    * **Called from outside the class**, by the build pipeline once the batch is
+    * re-indexed. The caches' own eviction does not cover this:
+    * `DocumentBuilder.onUpdate` fires after the build has taken every changed
+    * document's symbols out of the index and before it puts them back, so a
+    * scope built in that gap denies those symbols exist and every document the
+    * same build links afterwards resolves against it.
+    *
+    * Both go together because the second is derived from the first: clearing
+    * only {@link scopeCache} refills it from a stale `globalScopeCache`, and
+    * clearing only `globalScopeCache` leaves the filtered copy standing.
+    */
+   clearScopeCaches(): void {
+      this.scopeCache.clear();
+      this.globalScopeCache.clear();
+   }
+
+   /**
+    * Langium's, with each container's local scope built once per build through
+    * {@link localScope} rather than once per reference. Linking a document then
+    * costs its references plus its declarations, not their product.
+    */
+   override getScope(context: ReferenceInfo): Scope {
+      const referenceType = this.reflection.getReferenceType(context);
+      const localSymbols = this.localSymbolsOf(context.container);
+      let result = this.getGlobalScope(referenceType, context);
+      if (localSymbols === undefined) {
+         return result;
+      }
+      const containers: AstNode[] = [];
+      for (let container: AstNode | undefined = context.container; container; container = container.$container) {
+         if (localSymbols.has(container)) {
+            containers.push(container);
+         }
+      }
+      // Outermost first, so the innermost container's symbols shadow the rest.
+      for (let i = containers.length - 1; i >= 0; i--) {
+         result = new FallbackScope(this.localScope(localSymbols, containers[i], referenceType), result);
+      }
+      return result;
+   }
+
+   /**
+    * The local symbols of the build that `node`'s root came from: the
+    * document's while they are set for that root, else the ones the build
+    * pipeline recorded for it when its document computed scopes. A rebuild
+    * clears the document's, then keys them by the new root's nodes.
+    */
+   protected localSymbolsOf(node: AstNode): LocalSymbols | undefined {
+      const root = AstUtils.findRootNode(node);
+      const document = AstUtils.getDocument(root);
+      const recorded = builtLocalSymbols.get(root);
+      if (recorded === undefined || (document.parseResult.value === root && document.localSymbols !== undefined)) {
+         return document.localSymbols;
+      }
+      return recorded;
+   }
+
+   /**
+    * The symbols `container` declares that a `referenceType` reference can
+    * reach, through {@link createScope}, built once per `localSymbols`.
+    */
+   protected localScope(localSymbols: LocalSymbols, container: AstNode, referenceType: string): Scope {
+      let byContainer = this.localScopes.get(localSymbols);
+      if (byContainer === undefined) {
+         byContainer = new Map();
+         this.localScopes.set(localSymbols, byContainer);
+      }
+      let byType = byContainer.get(container);
+      if (byType === undefined) {
+         byType = new Map();
+         byContainer.set(container, byType);
+      }
+      let scope = byType.get(referenceType);
+      if (scope === undefined) {
+         scope = this.createScope(
+            localSymbols.getStream(container).filter(description => this.reflection.isSubtype(description.type, referenceType))
+         );
+         byType.set(referenceType, scope);
+      }
+      return scope;
+   }
+
+   /**
+    * Keyed by name, where Langium's walks every element on each lookup. Every
+    * description of a name is kept and the first answers, as in Langium's;
+    * `getAllElements` lists them in order, but with a description following
+    * the first of its name.
+    */
+   protected override createScope(elements: Iterable<AstNodeDescription>, outerScope?: Scope, options?: ScopeOptions): Scope {
+      return new MultiMapScope(elements, outerScope, options);
+   }
+
    /**
     * Framework-owned assembly seam. **Adopters do NOT override this** —
     * override {@link createGlobalScope} instead. This method layers the
     * scope-extension tiers around the adopter-overridable global scope.
     *
-    * Langium's `DefaultScopeProvider.getScope` then layers document-local
-    * on top of this result, yielding the full chain documented on the
-    * class.
+    * {@link getScope} then layers document-local on top of this result,
+    * yielding the full chain documented on the class.
     */
    protected override getGlobalScope(referenceType: string, context: ReferenceInfo): Scope {
       const projectChain = this.createGlobalScope(referenceType, context);
-      const withUniversal = this.layerUniversalExtension(referenceType, context, projectChain);
-      return this.layerLocalExtension(referenceType, context, withUniversal);
+      const extensions = this.scopeExtensionService.getDescriptions(referenceType, context.container);
+      const withUniversal = this.layerUniversalExtension(extensions, projectChain, referenceType, context);
+      return this.layerLocalExtension(extensions, withUniversal, referenceType, context);
    }
 
    /**
@@ -230,22 +348,66 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
-    * Layer scope-extension `local`-tier descriptions on top of `inner`.
-    * Returns `inner` unchanged when no extension contributes for the
-    * reference type (zero-cost common path).
+    * Layer each scope extension's `local`-tier descriptions on top of `inner`,
+    * an earlier extension's above a later one's, through {@link extensionScope}.
+    * Returns `inner` unchanged when there are none.
     */
-   protected layerLocalExtension(referenceType: string, context: ReferenceInfo, inner: Scope): Scope {
-      return this.scopeExtensionService.getLocalExtensionScope(referenceType, context.container, inner);
+   protected layerLocalExtension(
+      extensions: readonly ScopeExtensionDescriptions[],
+      inner: Scope,
+      _referenceType: string,
+      _context: ReferenceInfo
+   ): Scope {
+      return (
+         this.chainExtensionScopes(
+            extensions.map(extension => extension.local),
+            inner
+         ) ?? inner
+      );
+   }
+
+   /**
+    * Layer each scope extension's `universal`-tier descriptions below `inner`,
+    * which shadows them, an earlier extension's above a later one's, through
+    * {@link extensionScope}. Returns `inner` unchanged when there are none.
+    */
+   protected layerUniversalExtension(
+      extensions: readonly ScopeExtensionDescriptions[],
+      inner: Scope,
+      _referenceType: string,
+      _context: ReferenceInfo
+   ): Scope {
+      const below = this.chainExtensionScopes(extensions.map(extension => extension.universal));
+      return below ? new FallbackScope(inner, below) : inner;
+   }
+
+   /**
+    * Chain the scope of each non-empty array above `outer`, an earlier array's
+    * above a later one's; `undefined` when there is neither.
+    */
+   protected chainExtensionScopes(tiers: ReadonlyArray<readonly TieredAstNodeDescription[]>, outer?: Scope): Scope | undefined {
+      let result = outer;
+      for (let i = tiers.length - 1; i >= 0; i--) {
+         if (tiers[i].length > 0) {
+            const scope = this.extensionScope(tiers[i]);
+            result = result ? new FallbackScope(scope, result) : scope;
+         }
+      }
+      return result;
    }
 
    /**
-    * Layer scope-extension `universal`-tier descriptions BELOW `inner`
-    * (extensions appear last in the chain, shadowed by inner). Returns
-    * `inner` unchanged when no extension contributes for the reference
-    * type.
+    * The scope of one extension's descriptions of one tier, through
+    * {@link createScope}, built once per array and shared by every reference
+    * it answers, so an override of `createScope` sees no reference context.
     */
-   protected layerUniversalExtension(referenceType: string, context: ReferenceInfo, inner: Scope): Scope {
-      return this.scopeExtensionService.getUniversalExtensionScope(referenceType, context.container, inner);
+   protected extensionScope(descriptions: readonly TieredAstNodeDescription[]): Scope {
+      let scope = this.extensionScopes.get(descriptions);
+      if (scope === undefined) {
+         scope = this.createScope(descriptions);
+         this.extensionScopes.set(descriptions, scope);
+      }
+      return scope;
    }
 
    /**
@@ -286,7 +448,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * closure).
     *
     * Contrast {@link getGlobalScope}, which applies the framework's
-    * tier filter to this set, and `getScope` (Langium default), which
+    * tier filter to this set, and {@link getScope}, which
     * additionally merges in the local scope.
     */
    protected getAllElementsGlobalScope(referenceType: string, context: ReferenceInfo): Scope {
@@ -344,11 +506,11 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * Includes own-project `'public'`-tier descriptions when
     * {@link HydraniumScopeProviderOptions.includeOwnProjectPublic} is set
     * (routed to the own-project bucket by {@link bucketFor}). Returns a
-    * {@link StreamScope} (not {@link MapScope}) so same-name siblings are
+    * {@link MultiMapScope} (not {@link MapScope}) so same-name siblings are
     * preserved rather than collapsed.
     */
    protected createOwnProjectScope(context: ScopeContext): Scope {
-      return new StreamScope(stream(context.ownProjectEntries));
+      return new MultiMapScope(context.ownProjectEntries);
    }
 
    /**
@@ -357,7 +519,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * (own-project canonical filter applied by {@link bucketFor}).
     */
    protected createDependencyScope(context: ScopeContext): Scope {
-      return new StreamScope(stream(context.dependencyEntries));
+      return new MultiMapScope(context.dependencyEntries);
    }
 
    /**
@@ -369,13 +531,13 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
-    * Chain three tier sub-scopes inner-first. The `outerScope` argument
-    * of {@link StreamScope} is consulted only when the inner stream has
-    * no match, so a more specific tier shadows a less specific one of
-    * the same name.
+    * Chain three tier sub-scopes inner-first through {@link FallbackScope},
+    * which consults an outer tier only when the inner one has no match, so a
+    * more specific tier shadows a less specific one of the same name, and each
+    * tier keeps its own lookup.
     */
    protected chainScopes(ownScope: Scope, dependencyScope: Scope, universalScope: Scope): Scope {
-      return new StreamScope(ownScope.getAllElements(), new StreamScope(dependencyScope.getAllElements(), universalScope));
+      return new FallbackScope(ownScope, new FallbackScope(dependencyScope, universalScope));
    }
 
    /**
@@ -442,9 +604,51 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
+    * Langium's, with the scope cached: a member scope is asked for once per
+    * reference, and building it each time makes linking cost references times
+    * members.
+    *
+    * - Cached: the scope for a list of a built document's nodes, passed with
+    *   no `outerScope` or `options`, built once through {@link createNodeScope}.
+    * - Dropped: when that document's local symbols are replaced; a build that
+    *   leaves its nodes in place keeps it.
+    * - Any other list gets a scope per call.
+    *
+    * Override {@link createNodeScope} to change the scope; an override of this
+    * method keeps the cache only by calling `super`. The list must hold nodes
+    * of one document, which it is keyed by; a list changed in place between
+    * builds is answered as it was.
+    */
+   protected override createScopeForNodes(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope {
+      if (!Array.isArray(elements) || elements.length === 0 || outerScope !== undefined || options !== undefined) {
+         return this.createNodeScope(elements, outerScope, options);
+      }
+      const nodes: readonly AstNode[] = elements;
+      const root = AstUtils.findRootNode(nodes[0]);
+      const localSymbols = root.$document?.parseResult.value === root ? root.$document.localSymbols : undefined;
+      if (localSymbols === undefined) {
+         return this.createNodeScope(nodes);
+      }
+      let byList = this.nodeScopes.get(localSymbols);
+      if (byList === undefined) {
+         byList = new WeakMap();
+         this.nodeScopes.set(localSymbols, byList);
+      }
+      let scope = byList.get(nodes);
+      if (scope === undefined) {
+         scope = this.createNodeScope(nodes);
+         byList.set(nodes, scope);
+      }
+      return scope;
+   }
+
+   /**
+    * The scope {@link createScopeForNodes} answers with, keyed by name.
+    *
     * Keys the scope by {@link NameProvider.getOwnName} instead of Langium's
-    * `getName`. Same correction `HydraniumScopeComputation.addLocalSymbol`
-    * makes to the local-symbols pass, for the same reason: `getName` defaults
+    * `getName`. Same correction
+    * `HydraniumScopeComputation.addLocalSymbolByOwnName` makes to the
+    * local-symbols pass, for the same reason: `getName` defaults
     * to the project-qualified form here, so the base would key a member scope
     * by the fully qualified `Container.member` while the reference text after
     * the dot is the bare `member` — and nothing reports the mismatch, because
@@ -454,7 +658,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * reference to a member the container does not have must fail rather than
     * fall through to a same-named member on an unrelated type.
     */
-   protected override createScopeForNodes(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope {
+   protected createNodeScope(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope {
       const descriptions = stream(elements)
          .map(node => {
             const name = this.nameProvider.getOwnName(node);
@@ -463,7 +667,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
             return name ? this.descriptions.createDescription(node, name, AstUtils.getDocument(node)) : undefined;
          })
          .nonNullable();
-      return new StreamScope(descriptions, outerScope, options);
+      return new MultiMapScope(descriptions, outerScope, options);
    }
 
    /**

package/src/langium/scope/index.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 export * from './ast-node-description-provider.js';
+export * from './fallback-scope.js';
 export * from './reference-builder.js';
 export * from './reference-candidate-provider.js';
 export * from './hydranium-scope-computation.js';