@hydranium/core 1.0.0-next.28 → 1.0.0-next.281

package/src/langium/residency/cst-residency-service.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { asMutable, type Clock, Debouncer, Format, type Tracer } from '@hydranium/protocol';
+import { asMutable, type Clock, Debouncer, Format, type Tracer, UNRECORDED_VERSION } from '@hydranium/protocol';
 import {
    type AstNode,
    AstUtils,
@@ -24,9 +24,13 @@ import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
  * Default priority of the CST-residency pass. Deliberately very high so it runs
  * *last* among `Validated` build-phase passes (the registry iterates priority
- * ascending): every other reaction to the build — an adopter's own derived-state
- * pass included — settles while the CST is still guaranteed resident, before the
- * residency policy arms the shed.
+ * ascending).
+ *
+ * The ordering is defensive, not load-bearing: the pass only arms or cancels an
+ * idle timer, so every pass at `Validated` reads a resident CST whichever order
+ * they run in, and lowering it changes nothing observable while that holds. It
+ * becomes load-bearing the moment the shed stops being deferred — a pass that
+ * frees the CST synchronously has to run after every reader of it.
  */
 export const CST_RESIDENCY_PASS_PRIORITY = 1_000_000;
 
@@ -41,8 +45,11 @@ export const CST_RESIDENCY_PASS_PRIORITY = 1_000_000;
  *   "off" toggle.
  * - `{ kind: 'shed-closed-when-idle', idleMs }`: shed a closed document's CST
  *   once it has been idle (not in any build) for `idleMs`, keeping the AST
- *   resident. Open documents are always kept. `idleMs: 0` sheds as soon as a
- *   document is closed (a pure close-triggered threshold of this strategy).
+ *   resident. Open documents are always kept. The timer starts when a build
+ *   includes the document, so `idleMs: 0` sheds a closed document on the tick
+ *   after each such build. A shed document that re-enters a build is re-parsed
+ *   in full, so a window shorter than the gap between a document's builds
+ *   re-parses a closed document on every build it rides in.
  */
 export type CstResidencyStrategy = { readonly kind: 'always-keep' } | { readonly kind: 'shed-closed-when-idle'; readonly idleMs: number };
 
@@ -181,8 +188,10 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
 }
 
 /**
- * Residency policy that reclaims memory by shedding the concrete syntax tree
- * (CST) of closed documents while keeping their AST resident. Each build refreshes
+ * Keeps a document's CST available to the readers that need one, shedding it
+ * for documents that have gone idle and re-grafting on demand.
+ *
+ * Each build refreshes
  * the idle window of the documents in its batch; when a closed, sheddable
  * document's window elapses, every AST node's `$cstNode` and every reference's
  * `$refNode` are nulled, and the CST root, `Range`s and `Position`s become
@@ -227,7 +236,23 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
  * `HydraniumLangiumDocuments.getOrCreateDocument`.
  */
-export class CstResidencyService {
+export interface CstResidencyService {
+   /**
+    * Ensure `document` has a CST, re-parsing its retained text if it was shed.
+    * A resident document is left exactly as it is, so this is safe to call on
+    * a hot path and safe to call twice.
+    */
+   rehydrate(document: LangiumDocument): void;
+
+   /**
+    * Node-level convenience over {@link rehydrate}, cheap enough for an
+    * unconditional call: a node whose `$cstNode` is already set returns
+    * without resolving its document.
+    */
+   rehydrateNode(node: AstNode): void;
+}
+
+export class DefaultCstResidencyService implements CstResidencyService {
    protected readonly strategy: CstResidencyStrategy;
    /** Bytes-per-node for the optional reclaim estimate in traces; `0` disables it. */
    protected readonly estimatedBytesPerShedNode: number;
@@ -277,8 +302,8 @@ export class CstResidencyService {
     * until navigation latency on shed files is actually observed to hurt. This
     * method is where that hook goes.
     */
-   rehydrate(document: LangiumDocument): boolean {
-      return rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
+   rehydrate(document: LangiumDocument): void {
+      rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
    }
 
    /**
@@ -287,11 +312,11 @@ export class CstResidencyService {
     * `true` without even resolving the document, so hot read paths
     * (`getNameNode`, comment lookup) call this unconditionally.
     */
-   rehydrateNode(node: AstNode): boolean {
+   rehydrateNode(node: AstNode): void {
       if (node.$cstNode !== undefined) {
-         return true;
+         return;
       }
-      return this.rehydrate(AstUtils.getDocument(node));
+      this.rehydrate(AstUtils.getDocument(node));
    }
 
    /**
@@ -353,8 +378,8 @@ export class CstResidencyService {
       this.shedTotal += this.shed(document);
    }
 
-   /** Cancel and drop every idle timer — for clean shutdown and deterministic tests. */
-   dispose(): void {
+   /** Cancel every armed shed, so a document that has gone idle keeps its CST. */
+   cancelPendingShed(): void {
       for (const timer of this.idleTimers.values()) {
          timer.dispose();
       }
@@ -383,6 +408,15 @@ export class CstResidencyService {
       if (root === undefined || root.$cstNode === undefined) {
          return 0;
       }
+      // Readers of the parsed text, the `'text-diagnostics'` fingerprint among
+      // them, otherwise see none once the CST is gone. Recorded in the ledger
+      // directly: no root is produced, and reconciling it with the store would
+      // step a closed document's sequence for a root behind its text.
+      const ledger = this.services.workspace.ModelLedger;
+      const version = ledger.versionOf(root);
+      if (version !== UNRECORDED_VERSION) {
+         ledger.record(root, version, ledger.textOf(root));
+      }
       let cleared = 0;
       for (const node of AstUtils.streamAst(root)) {
          if (node.$cstNode) {

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,7 +24,6 @@ import {
    type AstNodeLocator,
    AstUtils,
    DefaultScopeProvider,
-   type LangiumDocuments,
    MapScope,
    type ReferenceInfo,
    type Scope,
@@ -35,11 +34,14 @@ import {
    WorkspaceCache,
    stream
 } from '@hydranium/langium';
+import { buildAstNode } from '../ast-extension/ast-node-builder.js';
 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 { FallbackScope } from './fallback-scope.js';
 import { type ScopeExtensionService } from './scope-extension-service.js';
-import { isTieredDescription } from './scoped-ast-node-description.js';
+import { type TieredAstNodeDescription, isTieredDescription } from './scoped-ast-node-description.js';
 
 /**
  * Construction-time options for {@link HydraniumScopeProvider}. Extends
@@ -143,7 +145,7 @@ export interface ScopeContext {
  * `reference-candidate-provider.ts` module.
  */
 export class HydraniumScopeProvider extends DefaultScopeProvider {
-   protected readonly langiumDocuments: LangiumDocuments;
+   protected readonly langiumDocuments: HydraniumDocumentRegistry;
    protected readonly astNodeLocator: AstNodeLocator;
    protected readonly scopeExtensionService: ScopeExtensionService;
    protected readonly options: HydraniumScopeProviderOptions;
@@ -182,6 +184,26 @@ 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();
+   }
+
    /**
     * Framework-owned assembly seam. **Adopters do NOT override this** —
     * override {@link createGlobalScope} instead. This method layers the
@@ -193,8 +215,9 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     */
    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.universal, projectChain, referenceType, context);
+      return this.layerLocalExtension(extensions.local, withUniversal, referenceType, context);
    }
 
    /**
@@ -229,22 +252,32 @@ 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 the scope extensions' `local`-tier `descriptions` on top of
+    * `inner`, through {@link createScope}. 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(
+      descriptions: readonly TieredAstNodeDescription[],
+      inner: Scope,
+      _referenceType: string,
+      _context: ReferenceInfo
+   ): Scope {
+      return descriptions.length === 0 ? inner : this.createScope(descriptions, inner);
    }
 
    /**
-    * 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.
+    * Layer the scope extensions' `universal`-tier `descriptions` below
+    * `inner`, which shadows them, through {@link createScope} and a
+    * {@link FallbackScope}, so `inner` keeps its own lookup. Returns `inner`
+    * unchanged when there are none.
     */
-   protected layerUniversalExtension(referenceType: string, context: ReferenceInfo, inner: Scope): Scope {
-      return this.scopeExtensionService.getUniversalExtensionScope(referenceType, context.container, inner);
+   protected layerUniversalExtension(
+      descriptions: readonly TieredAstNodeDescription[],
+      inner: Scope,
+      _referenceType: string,
+      _context: ReferenceInfo
+   ): Scope {
+      return descriptions.length === 0 ? inner : new FallbackScope(inner, this.createScope(descriptions));
    }
 
    /**
@@ -442,8 +475,9 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
 
    /**
     * 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
@@ -469,12 +503,13 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * Convert a protocol-layer {@link ReferenceContext} into a Langium
     * {@link ReferenceInfo} the rest of the scope/linking machinery accepts.
     *
-    * Walks `syntheticPath` by FABRICATING a type-only stub per step, so a
-    * scope can be queried for an element that does not exist yet — which is
-    * what synthetic paths are for. The stubs carry no children, so a caller
-    * that needs to read a collection off the leaf wants
-    * {@link resolveReferenceSource} instead, which walks the same path into
-    * the real tree.
+    * Walks `syntheticPath` by FABRICATING a stub per step, so a scope can be
+    * queried for an element that does not exist yet — which is what synthetic
+    * paths are for. A stub carries the grammar's declared defaults and nothing
+    * else, so its containment lists are present but EMPTY: a caller that needs
+    * to read a populated collection off the leaf wants
+    * {@link resolveReferenceSource} instead, which walks the same path into the
+    * real tree.
     *
     * Throws if the context references an unresolvable source; callers
     * that prefer a soft failure should catch and fall back to
@@ -486,16 +521,15 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
          throw new Error('Invalid reference source');
       }
       for (const step of ctx.syntheticPath ?? []) {
-         container = {
+         container = buildAstNode(this.services.shared.AstReflection, step.type, {
             $container: container,
             $containerProperty: step.containerProperty,
             // Part of Langium's own container contract, so a stub that omits it
             // is an under-specified node: anything reading position off the
             // chain (a key provider, an adopter scope extension) sees
             // `undefined` where the caller named a slot.
-            $containerIndex: step.index,
-            $type: step.type
-         };
+            $containerIndex: step.index
+         });
       }
       return {
          reference: { $refText: '', ref: undefined },
@@ -586,18 +620,35 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
-    * Build a transient AST-node stub for a {@link SyntheticSource} request.
-    * Default: looks up the document via `LangiumDocuments` and uses its parse
-    * root as the container; returns `undefined` if the document isn't loaded.
-    * Consumers that need to materialise an empty document on demand (e.g.
-    * to query the scope before a file exists) override this.
+    * Build a transient AST-node stub for a {@link SyntheticSource} request: a
+    * node of the requested type, contained by the document at `source.uri`.
+    *
+    * **The container is materialised when no document is loaded there**, which
+    * is the case the source type exists for — a `SyntheticSource` names a node
+    * that does not exist yet, and the create-element flow asks at the FOLDER
+    * the file is about to be written into. Abstaining there would answer an
+    * empty candidate list, which a client cannot tell from "nothing matches".
+    *
+    * The stand-in parses under THIS provider's grammar, because a folder URI
+    * carries no extension for the routing ladder to end on and this provider is
+    * bound per grammar. Reaching for `createEmptyDocument(uri)` without the id
+    * instead fails inside the parse, on an empty extension rather than on the
+    * URI.
+    *
+    * The materialised document is unregistered and transient; see
+    * `createEmptyDocument`. Overriding is still open to a consumer whose
+    * "container" is an inner element rather than the parse root, or one that
+    * deliberately declines to answer for an absent document.
+    *
+    * The stub carries the grammar's declared defaults, so an extension reading a
+    * containment list off it sees an empty array rather than `undefined`.
     */
    protected resolveSyntheticSource(source: SyntheticSource): AstNode | undefined {
-      const document = this.langiumDocuments.getDocument(UriUtils.toUri(source.uri));
-      if (!document) {
-         return undefined;
-      }
-      return { $type: source.type, $container: document.parseResult.value };
+      const uri = UriUtils.toUri(source.uri);
+      const document =
+         this.langiumDocuments.getDocument(uri) ??
+         this.langiumDocuments.createEmptyDocument(uri, this.services.LanguageMetaData.languageId);
+      return buildAstNode(this.services.shared.AstReflection, source.type, { $container: document.parseResult.value });
    }
 
    /**

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';

package/src/langium/scope/reference-candidate-provider.ts

@@ -102,9 +102,9 @@ export interface ResolvedCandidate {
 export interface ReferenceCandidateProvider {
    /**
     * UI-facing entry point: returns the candidate scope's elements as
-    * {@link ReferenceCandidate}s.
+    * {@link ReferenceCandidate}s. Accepts what {@link getCandidateScope} does.
     */
-   find(ctx: ReferenceContext): ReferenceCandidate[];
+   find(ctx: ReferenceContext | ReferenceInfo): ReferenceCandidate[];
 
    /**
     * Build a ranked + deduped scope for candidate selection at the
@@ -195,14 +195,15 @@ export class DefaultReferenceCandidateProvider implements ReferenceCandidateProv
     * and never matches: a self-reference filter silently stops excluding, and
     * the element offers itself as its own target.
     *
-    * The mirror of `ReferenceBuilder.nameProviderFor`, and the same fallback
-    * reasoning: an unroutable target has no better answer than the source's.
+    * The mirror of `DefaultReferenceBuilder.nameProviderFor`, and the same
+    * fallback reasoning: an unroutable target has no better answer than the
+    * source's.
     */
    protected nameProviderFor(target: AstNode): NameProvider {
       return this.services.shared.ServiceRegistry?.getServicesFor(target)?.references.NameProvider ?? this.nameProvider;
    }
 
-   find(ctx: ReferenceContext): ReferenceCandidate[] {
+   find(ctx: ReferenceContext | ReferenceInfo): ReferenceCandidate[] {
       const scope = this.getCandidateScope(ctx);
       return scope.elementScope
          .getAllElements()