@hydranium/core 1.0.0-next.37 → 1.0.0-next.370

package/lib/langium/scope/hydranium-scope-provider.d.ts

@@ -7,12 +7,13 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { type Tracer, type ReferenceContext, type ReferenceRequest, type ReferenceSource, type SyntheticSource } from '@hydranium/protocol';
-import { type AstNode, type AstNodeDescription, type AstNodeLocator, DefaultScopeProvider, type ReferenceInfo, type Scope, type ScopeOptions, type URI, WorkspaceCache } from '@hydranium/langium';
+import { type AstNode, type AstNodeDescription, type AstNodeLocator, DefaultScopeProvider, type LocalSymbols, type ReferenceInfo, type Scope, type ScopeOptions, type URI, WorkspaceCache } from '@hydranium/langium';
 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 { type ScopeExtensionDescriptions, type ScopeExtensionService } from './scope-extension-service.js';
+import { type TieredAstNodeDescription } from './scoped-ast-node-description.js';
 /**
  * Construction-time options for {@link HydraniumScopeProvider}. Extends
  * {@link LogNameOptions} so the standard `logName?` field
@@ -64,7 +65,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.
@@ -72,16 +73,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
  *
@@ -101,7 +102,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
@@ -131,6 +133,24 @@ export declare 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: 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: 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: WeakMap<readonly TieredAstNodeDescription[], Scope>;
     protected readonly tracer: Tracer;
     /**
      * Narrows the inherited Langium {@link NameProvider} field to the framework's
@@ -140,14 +160,54 @@ export declare class HydraniumScopeProvider extends DefaultScopeProvider {
      */
     protected readonly nameProvider: NameProvider;
     constructor(services: HydraniumLanguageServices, options?: HydraniumScopeProviderOptions);
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    getScope(context: ReferenceInfo): Scope;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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 createScope(elements: Iterable<AstNodeDescription>, outerScope?: Scope, options?: ScopeOptions): Scope;
     /**
      * 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 getGlobalScope(referenceType: string, context: ReferenceInfo): Scope;
     /**
@@ -177,18 +237,28 @@ export declare class HydraniumScopeProvider extends DefaultScopeProvider {
      */
     protected createGlobalScope(referenceType: string, context: ReferenceInfo): Scope;
     /**
-     * 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(extensions: readonly ScopeExtensionDescriptions[], inner: Scope, _referenceType: string, _context: ReferenceInfo): Scope;
+    /**
+     * 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;
+    /**
+     * 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 layerLocalExtension(referenceType: string, context: ReferenceInfo, inner: Scope): Scope;
+    protected chainExtensionScopes(tiers: ReadonlyArray<readonly TieredAstNodeDescription[]>, outer?: Scope): Scope | undefined;
     /**
-     * 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;
+    protected extensionScope(descriptions: readonly TieredAstNodeDescription[]): Scope;
     /**
      * Project-tier scope filter. Given a source URI and a global scope,
      * returns the subset of descriptions whose owning project is visible
@@ -215,7 +285,7 @@ export declare 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;
@@ -240,7 +310,7 @@ export declare 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;
@@ -256,10 +326,10 @@ export declare class HydraniumScopeProvider extends DefaultScopeProvider {
      */
     protected createUniversalScope(context: ScopeContext): Scope;
     /**
-     * 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;
     /**
@@ -291,9 +361,29 @@ export declare class HydraniumScopeProvider extends DefaultScopeProvider {
      */
     protected getProjectIdForDescription(description: AstNodeDescription): string | undefined;
     /**
+     * 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 createScopeForNodes(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): 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
@@ -303,7 +393,7 @@ export declare 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 createScopeForNodes(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope;
+    protected createNodeScope(elements: Iterable<AstNode>, outerScope?: Scope, options?: ScopeOptions): Scope;
     /**
      * Convert a protocol-layer {@link ReferenceContext} into a Langium
      * {@link ReferenceInfo} the rest of the scope/linking machinery accepts.

package/lib/langium/scope/hydranium-scope-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydranium-scope-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/hydranium-scope-provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hydranium-scope-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/scope/hydranium-scope-provider.ts"],"names":[],"mappings":"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"}

package/lib/langium/scope/hydranium-scope-provider.js

@@ -7,13 +7,15 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { isDocumentSource, isElementSource, isReferenceContext, isSyntheticSource } from '@hydranium/protocol';
-import { AstUtils, DefaultScopeProvider, MapScope, StreamScope, UriUtils, WorkspaceCache, stream } from '@hydranium/langium';
+import { AstUtils, DefaultScopeProvider, MapScope, MultiMapScope, UriUtils, WorkspaceCache, stream } from '@hydranium/langium';
 import { buildAstNode } from '../ast-extension/ast-node-builder.js';
+import { builtLocalSymbols } from './built-local-symbols.js';
+import { FallbackScope } from './fallback-scope.js';
 import { isTieredDescription } from './scoped-ast-node-description.js';
 /**
  * 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.
@@ -21,16 +23,16 @@ import { isTieredDescription } from './scoped-ast-node-description.js';
  * ## 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
  *
@@ -50,7 +52,8 @@ import { isTieredDescription } from './scoped-ast-node-description.js';
  * - **{@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
@@ -80,6 +83,24 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
      * the workspace-global `DocumentBuilder.onUpdate`.
      */
     scopeCache;
+    /**
+     * 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.
+     */
+    localScopes = new WeakMap();
+    /**
+     * {@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.
+     */
+    nodeScopes = new WeakMap();
+    /**
+     * 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.
+     */
+    extensionScopes = new WeakMap();
     tracer;
     constructor(services, options = {}) {
         super(services);
@@ -91,19 +112,108 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
         this.scopeCache = new WorkspaceCache(services.shared);
         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() {
+        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.
+     */
+    getScope(context) {
+        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 = [];
+        for (let container = 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.
+     */
+    localSymbolsOf(node) {
+        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`.
+     */
+    localScope(localSymbols, container, referenceType) {
+        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.
+     */
+    createScope(elements, outerScope, options) {
+        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.
      */
     getGlobalScope(referenceType, context) {
         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);
     }
     /**
      * The SINGLE adopter-overridable level of the project/global scope.
@@ -136,21 +246,48 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
         return this.getProjectScope(sourceUri, langiumGlobal, referenceType);
     }
     /**
-     * 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.
      */
-    layerLocalExtension(referenceType, context, inner) {
-        return this.scopeExtensionService.getLocalExtensionScope(referenceType, context.container, inner);
+    layerLocalExtension(extensions, inner, _referenceType, _context) {
+        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.
+     */
+    layerUniversalExtension(extensions, inner, _referenceType, _context) {
+        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.
+     */
+    chainExtensionScopes(tiers, outer) {
+        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.
      */
-    layerUniversalExtension(referenceType, context, inner) {
-        return this.scopeExtensionService.getUniversalExtensionScope(referenceType, context.container, inner);
+    extensionScope(descriptions) {
+        let scope = this.extensionScopes.get(descriptions);
+        if (scope === undefined) {
+            scope = this.createScope(descriptions);
+            this.extensionScopes.set(descriptions, scope);
+        }
+        return scope;
     }
     /**
      * Project-tier scope filter. Given a source URI and a global scope,
@@ -189,7 +326,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.
      */
     getAllElementsGlobalScope(referenceType, context) {
@@ -244,11 +381,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.
      */
     createOwnProjectScope(context) {
-        return new StreamScope(stream(context.ownProjectEntries));
+        return new MultiMapScope(context.ownProjectEntries);
     }
     /**
      * Dependency-projects sub-scope — `'public'`-tier descriptions whose
@@ -256,7 +393,7 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
      * (own-project canonical filter applied by {@link bucketFor}).
      */
     createDependencyScope(context) {
-        return new StreamScope(stream(context.dependencyEntries));
+        return new MultiMapScope(context.dependencyEntries);
     }
     /**
      * Universal sub-scope — descriptions with no project association,
@@ -266,13 +403,13 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
         return new MapScope(context.universalEntries);
     }
     /**
-     * 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.
      */
     chainScopes(ownScope, dependencyScope, universalScope) {
-        return new StreamScope(ownScope.getAllElements(), new StreamScope(dependencyScope.getAllElements(), universalScope));
+        return new FallbackScope(ownScope, new FallbackScope(dependencyScope, universalScope));
     }
     /**
      * Classify a description into one of three sub-scope buckets, or
@@ -332,9 +469,50 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
         return this.services.shared.workspace.ProjectManager.getProject(description.documentUri)?.id;
     }
     /**
+     * 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.
+     */
+    createScopeForNodes(elements, outerScope, options) {
+        if (!Array.isArray(elements) || elements.length === 0 || outerScope !== undefined || options !== undefined) {
+            return this.createNodeScope(elements, outerScope, options);
+        }
+        const nodes = 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
@@ -344,7 +522,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.
      */
-    createScopeForNodes(elements, outerScope, options) {
+    createNodeScope(elements, outerScope, options) {
         const descriptions = stream(elements)
             .map(node => {
             const name = this.nameProvider.getOwnName(node);
@@ -353,7 +531,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);
     }
     /**
      * Convert a protocol-layer {@link ReferenceContext} into a Langium