@hydranium/core 1.0.0-next.14 → 1.0.0-next.148

package/src/langium/workspace/file-system-provider.ts

@@ -9,11 +9,11 @@
 
 import { type Tracer } from '@hydranium/protocol';
 import { EmptyFileSystemProvider } from '@hydranium/langium';
-import type { URI } from '@hydranium/langium';
+import type { FileSystemNode, URI } from '@hydranium/langium';
 import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
-import { serveVirtualDocument } from './virtual-document.js';
+import { serveVirtualDocument, serveVirtualNode } from './virtual-document.js';
 
 /**
  * Empty-filesystem default {@link WritableFileSystemProvider}. For
@@ -38,15 +38,55 @@ export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider impl
    }
 
    // Serve virtual documents from the registered document (there is no disk to
-   // read); delegate everything else to the empty base (which throws). The
-   // base declares these param-less, so the param is optional here.
-   override readFile(uri?: URI): Promise<string> {
-      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
-      return served !== undefined ? Promise.resolve(served) : super.readFile();
+   // read); delegate everything else to the empty base (which throws, or
+   // answers "absent"). The base declares these param-less, so the param is
+   // optional here.
+   //
+   // The async reads are `async` so the base's refusal becomes a rejection: it
+   // throws SYNCHRONOUSLY from a method declared to return a promise, and a
+   // synchronous throw escapes the promise chain — `.catch()` never attaches
+   // and `Promise.all` dies while its argument array is still being built, so
+   // a caller reading several URIs cannot handle the miss it asked about.
+   override async readFile(uri?: URI): Promise<string> {
+      const served = this.served(uri);
+      return served !== undefined ? served : super.readFile();
    }
 
    override readFileSync(uri?: URI): string {
-      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
+      const served = this.served(uri);
       return served !== undefined ? served : super.readFileSync();
    }
+
+   override async readBinary(uri?: URI): Promise<Uint8Array> {
+      const served = this.served(uri);
+      return served !== undefined ? new TextEncoder().encode(served) : super.readBinary();
+   }
+
+   override readBinarySync(uri?: URI): Uint8Array {
+      const served = this.served(uri);
+      return served !== undefined ? new TextEncoder().encode(served) : super.readBinarySync();
+   }
+
+   // The base declares these two WITH a URI parameter, so they stay required.
+   override async stat(uri: URI): Promise<FileSystemNode> {
+      const served = serveVirtualNode(this.services, uri);
+      return served !== undefined ? served : super.stat(uri);
+   }
+
+   override statSync(uri: URI): FileSystemNode {
+      return serveVirtualNode(this.services, uri) ?? super.statSync(uri);
+   }
+
+   override async exists(uri?: URI): Promise<boolean> {
+      return this.existsSync(uri);
+   }
+
+   override existsSync(uri?: URI): boolean {
+      return this.served(uri) !== undefined;
+   }
+
+   /** Text of the virtual document registered at `uri`, if there is one. */
+   protected served(uri: URI | undefined): string | undefined {
+      return uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
+   }
 }

package/src/langium/workspace/hydranium-langium-document-factory.ts

@@ -15,6 +15,7 @@ import {
    type ParseResult,
    type URI
 } from '@hydranium/langium';
+import { type ExtendedServiceRegistry } from '../service-registry.js';
 import { type Serializer } from '../serialization/serializer.js';
 
 /** Structural view of the per-language serializer slot on the resolved services. */
@@ -49,6 +50,39 @@ interface WithSerializer {
  * node identity is preserved.
  */
 export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+   /**
+    * Narrows the inherited Langium `ServiceRegistry` field to the framework's
+    * {@link ExtendedServiceRegistry}, so the by-id lookup below needs no
+    * per-callsite cast. The framework's shared module binds that class.
+    */
+   declare protected readonly serviceRegistry: ExtendedServiceRegistry;
+
+   /**
+    * Parse `text` for `uri` under the grammar `languageId` names, instead of
+    * the one `uri` routes to.
+    *
+    * For a URI that routes to no grammar at all: a directory, or any other URI
+    * that names no file and so carries no extension. Langium's ladder ends at
+    * the extension, so it reports `no services for the extension ''` from
+    * inside the parse — naming neither the URI nor the caller that could have
+    * said which grammar it meant.
+    *
+    * The caller supplies the language because nothing else can. A URI with no
+    * extension carries no routing signal, and choosing on its behalf would be a
+    * guess the moment a second grammar is registered — which is why this takes
+    * the id rather than falling back to a sole registered language.
+    *
+    * @throws when `languageId` names no registered grammar.
+    */
+   fromStringInLanguage<T extends AstNode = AstNode>(text: string, uri: URI, languageId: string): LangiumDocument<T> {
+      const services = this.serviceRegistry.getServicesById(languageId);
+      if (!services) {
+         throw new Error(`No grammar is registered for the language id '${languageId}' (parsing ${uri.toString()}).`);
+      }
+      const parseResult: ParseResult<T> = services.parser.LangiumParser.parse<T>(text);
+      return this.createLangiumDocument<T>(parseResult, uri, undefined, text);
+   }
+
    override fromModel<T extends AstNode = AstNode>(model: T, uri: URI): LangiumDocument<T> {
       // Make the code-built AST as structurally complete as a parsed one — the
       // parser links containers, `fromModel` does not. In place (identity kept).

package/src/langium/workspace/hydranium-workspace-lock.ts

@@ -29,7 +29,28 @@ import { runInWriteLockScope } from './write-lock-scope.js';
  * would turn ordinary read-then-write sequences into false positives.
  */
 export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+   /** Backs {@link writeCancellations}. */
+   protected cancelledWriteCount = 0;
+
+   /**
+    * How many calls have cancelled the lock's latest write: every `write`,
+    * which cancels the write before it, and every `cancelWrite`. A caller that
+    * reads this right after queuing a write, and reads the same number later,
+    * holds a write nothing has cancelled, whether it is still queued or
+    * already running. Its token answers that only once the write runs, since
+    * a queued write has not been handed it yet.
+    */
+   get writeCancellations(): number {
+      return this.cancelledWriteCount;
+   }
+
    override write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void> {
       return super.write(token => runInWriteLockScope(() => action(token)));
    }
+
+   /** Counted here rather than in {@link write}, because Langium's `write` cancels through this method too. */
+   override cancelWrite(): void {
+      this.cancelledWriteCount++;
+      super.cancelWrite();
+   }
 }

package/src/langium/workspace/hydranium-workspace-manager.ts

@@ -9,9 +9,10 @@
 
 import { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
 import { DefaultWorkspaceManager, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver';
+import { type CancellationToken, type InitializeParams } from 'vscode-languageserver';
 import type { WorkspaceFolder } from 'vscode-languageserver-types';
 import { type LogNameOptions, resolveLogFilePlaceholder, toLogFileWorkspaceToken } from '../diagnostics/logger.js';
+import type { ServerLocale } from '../../locale/server-locale.js';
 import type { ProjectChangeEvent } from '../project/project-change-event.js';
 import type { ProjectManager } from '../project/project-manager.js';
 import type { ServerSharedServicesMinimal } from '../shared-services.js';
@@ -156,6 +157,8 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
    readonly workspaceInitialized: Promise<unknown> = this.workspaceInitializedDeferred.promise;
 
    protected readonly uriPolicy: DocumentUriPolicy;
+   /** Handed the client's locale at init; read by whoever renders in it. */
+   protected readonly serverLocale: ServerLocale;
    protected readonly writableFileSystemProvider: WritableFileSystemProvider;
    protected readonly additionalDocuments: Record<string, AdditionalDocumentContribution>;
    /** Registry consulted by {@link warnIfUnroutable} to check a seeded document routes. */
@@ -166,6 +169,7 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       this.projectManager = services.workspace.ProjectManager;
       this.projectManager.onProjectsChanged(event => this.onProjectsChanged(event));
       this.uriPolicy = services.workspace.DocumentUriPolicy;
+      this.serverLocale = services.ServerLocale;
       this.writableFileSystemProvider = services.workspace.FileSystemProvider;
       this.additionalDocuments = services.additionalDocuments;
       this.languageRegistry = services.ServiceRegistry;
@@ -360,6 +364,31 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       }
    }
 
+   /**
+    * Forward the locale the client declared, then Langium's own read of the
+    * params. `DefaultWorkspaceManager.initialize` reads `workspaceFolders`
+    * alone, so `params.locale` would otherwise be discarded — and this is the
+    * only place it arrives, which the headless init seams route through too.
+    *
+    * **The ABSENT case is reported from here rather than from `ServerLocale`,
+    * because this is the only end that can see it.** `accept` is not called
+    * when no locale was declared — nor should it be, since `''` is a claim
+    * about a language rather than the absence of one — so a log written there
+    * covers one of the two outcomes and leaves the other looking like a server
+    * that never reached init. Both lines are at `info` for the reason `accept`
+    * gives: the framework ships no catalogue, so an undeclared locale and an
+    * untranslated code produce the same English and the log is what separates
+    * them.
+    */
+   override initialize(params: InitializeParams): void {
+      if (params.locale) {
+         this.serverLocale.accept(params.locale);
+      } else {
+         this.tracer.info("no locale declared at init — rendering messages in the framework's English");
+      }
+      super.initialize(params);
+   }
+
    /**
     * Override of Langium's workspace setup to resolve / reject
     * {@link workspaceInitializedDeferred} once setup completes. Adopters with

package/src/langium/workspace/in-memory-file-system-provider.ts

@@ -8,11 +8,49 @@
  ********************************************************************************/
 
 import { type FileSystemNode, URI } from '@hydranium/langium';
-import { type Tracer } from '@hydranium/protocol';
+import { defineMessage, type Tracer } from '@hydranium/protocol';
 import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
-import { serveVirtualDocument } from './virtual-document.js';
+import { serveVirtualDocument, serveVirtualNode } from './virtual-document.js';
+
+/**
+ * A provider's spelling of "the document is not there", raised wherever a read
+ * finds no content — this filesystem, or a URI naming no location a disk-backed
+ * provider can reach. Distinct from `NO_LOADABLE_CONTENT`, which the URI policy
+ * raises when it can settle the question AHEAD of the read; a provider with no
+ * `realpath` cannot, so the miss surfaces here instead.
+ */
+export const NO_SUCH_FILE = defineMessage('hydranium/core/no-such-file', 'No such file: {uri}');
+
+/** The same for a node of any kind, so it also covers a directory. */
+export const NO_SUCH_PATH = defineMessage('hydranium/core/no-such-path', 'No such file or directory: {uri}');
+
+/**
+ * A write addressed a URI the provider cannot reach on disk.
+ *
+ * Deliberately not a not-found code: {@link NO_SUCH_FILE} reports something
+ * missing, which a caller may reasonably answer by creating it — exactly the
+ * wrong reading here. The destination is not missing; the URI names no disk
+ * location at all, and no retry makes it one.
+ *
+ * Declared here rather than beside the Node provider that raises it, so the
+ * message catalog stays reachable from the portable `.` entry — the Node
+ * module pulls `node:fs` and is server-only.
+ */
+export const UNSUPPORTED_WRITE = defineMessage(
+   'hydranium/core/unsupported-write',
+   'Cannot write {uri}: the scheme names no location on disk'
+);
+
+/**
+ * A missing-file error shaped as a Node file system raises it, with code
+ * `ENOENT` and the path: callers tell a missing file from any other failure by
+ * those two fields, whichever provider is bound.
+ */
+function notFound(message: string, uri: URI): Error {
+   return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
+}
 
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
@@ -116,8 +154,14 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       this.setFile(uri, content);
    }
 
-   readFile(uri: URI): Promise<string> {
-      return Promise.resolve(this.readFileSync(uri));
+   // `async` on each read whose sync twin can throw, rather than
+   // `Promise.resolve(this.<x>Sync(uri))`. That form evaluates the sync call
+   // FIRST, so a miss throws before `Promise.resolve` is ever reached — and a
+   // synchronous throw escapes the promise chain: `.catch()` never attaches and
+   // `Promise.all` dies while its argument array is still being built, so a
+   // caller reading several URIs cannot handle the miss it asked about.
+   async readFile(uri: URI): Promise<string> {
+      return this.readFileSync(uri);
    }
 
    readFileSync(uri: URI): string {
@@ -127,24 +171,29 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       }
       const content = this.files.get(normalize(uri));
       if (content === undefined) {
-         throw new Error(`No such file: ${uri.toString()}`);
+         throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
       }
       return content;
    }
 
-   readBinary(uri: URI): Promise<Uint8Array> {
-      return Promise.resolve(this.readBinarySync(uri));
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.readBinarySync(uri);
    }
 
    readBinarySync(uri: URI): Uint8Array {
       return new TextEncoder().encode(this.readFileSync(uri));
    }
 
-   stat(uri: URI): Promise<FileSystemNode> {
-      return Promise.resolve(this.statSync(uri));
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.statSync(uri);
    }
 
    statSync(uri: URI): FileSystemNode {
+      // Virtual first, on the same terms as `readFileSync`.
+      const served = serveVirtualNode(this.services, uri);
+      if (served !== undefined) {
+         return served;
+      }
       const path = normalize(uri);
       if (this.files.has(path)) {
          return { isFile: true, isDirectory: false, uri };
@@ -152,7 +201,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       if (this.hasChildren(path)) {
          return { isFile: false, isDirectory: true, uri };
       }
-      throw new Error(`No such file or directory: ${uri.toString()}`);
+      throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
    }
 
    exists(uri: URI): Promise<boolean> {
@@ -160,6 +209,9 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
    }
 
    existsSync(uri: URI): boolean {
+      if (serveVirtualDocument(this.services, uri) !== undefined) {
+         return true;
+      }
       const path = normalize(uri);
       return this.files.has(path) || this.hasChildren(path);
    }

package/src/langium/workspace/initialize-workspace.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { UriUtils, URI } from '@hydranium/langium';
+import type { Locale } from '@hydranium/protocol';
 // Bare `'path'` (not `node:path`) so a browser bundle can alias it to a POSIX
 // shim — this is the only filesystem-path use left on the portable `.` entry,
 // and it's the headless/CLI string-input convenience of `toWorkspaceFolders`.
@@ -18,6 +19,33 @@ import type { ServerSharedServicesMinimal } from '../shared-services.js';
 /** A workspace folder root accepted by the headless init seams: a filesystem path or a {@link URI}. */
 export type WorkspaceFolderInput = string | URI;
 
+/**
+ * Options for the headless init seams.
+ *
+ * **Optional, and the parameter is optional too**, so that no existing caller
+ * has to change to gain a field it does not set.
+ */
+export interface ProgrammaticInitOptions {
+   /**
+    * The locale to render user-facing server messages in — the headless
+    * equivalent of LSP `initialize`'s `locale`, for a head with no LSP
+    * connection (`startStdioServer`, the CLI subcommands, a test harness).
+    *
+    * Omitted means no locale, which the default renderer resolves as the
+    * framework's English. That is the correct answer for a headless tool: it
+    * has no reading user to have a language.
+    *
+    * **An IETF language tag, hyphenated — `de`, `de-CH`, `zh-Hant-TW` — and
+    * not the POSIX or Java spelling.** An LSP client is held to that syntax by
+    * the protocol, while a headless caller supplies the string itself and the
+    * obvious source is an environment variable holding `de_DE` or
+    * `en_US.UTF-8`. Neither is a tag, and the string is passed through
+    * unchecked, so a renderer that parses it finds nothing to match and every
+    * message renders in English.
+    */
+   readonly locale?: Locale;
+}
+
 /**
  * Normalize the seam's flexible folder argument to LSP {@link WorkspaceFolder}s.
  * A `string` is resolved to an absolute filesystem path and wrapped as a
@@ -58,17 +86,25 @@ function toWorkspaceFolders(folders: WorkspaceFolderInput | ReadonlyArray<Worksp
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function initializeWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
    const workspaceFolders = toWorkspaceFolders(folders);
    const manager = services.workspace.WorkspaceManager;
-   // `initialize` records the folders (DefaultWorkspaceManager reads only this
+   // `locale` goes through the synthesized params rather than a direct
+   // `acceptLocale` call, so this seam and a real LSP `initialize` reach the
+   // slot by the SAME path — an adopter overriding the capture in
+   // `HydraniumWorkspaceManager.initialize` is honoured headlessly too, which a
+   // second write site here would silently bypass.
+   //
+   // `initialize` records the folders (DefaultWorkspaceManager reads only that
    // field); `initialized` runs `mutex.write(initializeWorkspace)` and resolves
    // once discovery + the init build settle, so awaiting it is the ready gate.
-   manager.initialize({ workspaceFolders } as InitializeParams);
+   manager.initialize({ workspaceFolders, locale: options.locale } as InitializeParams);
    await manager.initialized({} as InitializedParams);
 }
 
@@ -91,12 +127,14 @@ export async function initializeWorkspaceProgrammatically(
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function buildWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
-   await initializeWorkspaceProgrammatically(services, folders);
+   await initializeWorkspaceProgrammatically(services, folders, options);
    const documents = services.workspace.LangiumDocuments.all.toArray();
    await services.workspace.DocumentBuilder.build(documents, { validation: true });
 }

package/src/langium/workspace/langium-documents.ts

@@ -7,14 +7,49 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Tracer } from '@hydranium/protocol';
-import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI } from '@hydranium/langium';
+import { defineMessage } from '@hydranium/protocol';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from './document-uri-policy.js';
+import { type HydraniumLangiumDocumentFactory } from './hydranium-langium-document-factory.js';
 
 /**
- * Default `LangiumDocuments` for `@hydranium/core` consumers. Layers two
- * extensions on top of Langium's {@link DefaultLangiumDocuments}:
+ * The document a caller asked to load is not there.
+ *
+ * User-facing, and the Node host's spelling of it: `loadUri` returns `undefined`
+ * exactly when the URI policy's `realpath` reports the path absent. A host whose
+ * provider has no `realpath` never reaches this — the miss surfaces from the
+ * provider instead, so the same condition has one declaration per host.
+ */
+export const NO_LOADABLE_CONTENT = defineMessage('hydranium/core/no-loadable-content', 'No loadable content for {uri}');
+
+/**
+ * A stand-in was asked for at a URI that routes to no grammar, and no language
+ * id was given to route it instead.
+ *
+ * User-facing, and raised BEFORE the parse: left to Langium's ladder the same
+ * condition surfaces as `no services for the extension ''`, which names neither
+ * the URI nor the argument that would have answered.
+ */
+export const NO_LANGUAGE_FOR_STAND_IN = defineMessage(
+   'hydranium/core/no-language-for-stand-in',
+   'No grammar routes {uri}; pass a languageId to say which one the stand-in should parse with'
+);
+
+/**
+ * The registry surface the framework adds on top of Langium's
+ * {@link LangiumDocuments}. Declared separately from the implementing class so
+ * the shared-services slot can narrow to it: the class takes the services tree
+ * as its constructor parameter, so naming the CLASS there would make that type
+ * depend on itself.
+ */
+export interface HydraniumDocumentRegistry extends LangiumDocuments {
+   createEmptyDocument(uri: URI, languageId?: string): LangiumDocument<AstNode>;
+}
+
+/**
+ * Default `LangiumDocuments` for `@hydranium/core` consumers, extending
+ * Langium's {@link DefaultLangiumDocuments} with:
  *
  * 1. **Identity via the {@link DocumentUriPolicy} seam.**
  *    `getOrCreateDocument` resolves the requested URI through the seam — the
@@ -24,31 +59,78 @@ import { type DocumentUriPolicy } from './document-uri-policy.js';
  *    `LangiumDocuments` override. The default resolves to the URI unchanged
  *    (`DefaultDocumentUriPolicy`), matching Langium's own keying.
  *
- * 2. **`createEmptyDocument(uri)` — synchronous** factory for a transient
- *    document with no loadable on-disk content. `getOrCreateDocument` falls
- *    back to it when the seam reports no loadable URI, or when `super` cannot
- *    load it, so callers always receive a document. Abstract because the
- *    parse-result root is grammar-specific (each grammar returns its own
- *    root node type). The fallback document is deliberately
- *    **not** registered: a transient placeholder must not mask the real
- *    document once it appears.
+ * 2. **A load that finds nothing rejects**, rather than answering with a
+ *    transient empty document. An empty AST validates clean, so a placeholder
+ *    hands the caller something that silently is not the file, and a caller
+ *    that wants a document for a URI with no content on disk cannot use one
+ *    anyway: it is unregistered, so no build, index or save can see it, and
+ *    `LangiumDocumentFactory.update` reads from disk. Content that legitimately
+ *    lives outside the filesystem belongs in a virtual document, which carries
+ *    real source text.
  */
-export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
+export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implements HydraniumDocumentRegistry {
    /** Document-identity seam, shared with the text store, event filters, and builder. */
    protected readonly uriPolicy: DocumentUriPolicy;
-   protected readonly tracer: Tracer;
+
+   /**
+    * Narrows the inherited Langium factory field to the framework's, so the
+    * language-explicit `fromStringInLanguage` below needs no cast. The
+    * framework's shared module binds that class.
+    */
+   declare protected readonly langiumDocumentFactory: HydraniumLangiumDocumentFactory;
 
    constructor(protected override readonly services: ServerSharedServicesMinimal) {
       super(services);
       this.uriPolicy = services.workspace.DocumentUriPolicy;
-      this.tracer = services.Tracer.for('LangiumDocuments');
    }
 
    /**
-    * Build a transient empty document for `uri`. Implemented by consumers
-    * because the parse-result root is grammar-specific.
+    * Build a transient document for `uri` by parsing empty text with the
+    * grammar `languageId` names, or the one `uri` routes to when it is
+    * omitted, so the root is that language's entry type with every containment
+    * list initialised.
+    *
+    * For callers that need a document at a URI with no content on disk — the
+    * scope provider querying before a file exists is the case it was added for.
+    * `getOrCreateDocument` deliberately does NOT fall back to this: fabricating
+    * a document behind a caller that asked to LOAD one hands back something
+    * that silently is not the file, whereas calling this is a caller saying it
+    * wants a stand-in.
+    *
+    * **Pass `languageId` whenever the URI names no file.** The create-element
+    * flow this exists for asks at the DIRECTORY a file is about to be written
+    * into, and a directory URI has no extension for the routing ladder to end
+    * on — so omitting the id there fails inside the parse, on an empty
+    * extension rather than on the URI. A caller in that position always knows
+    * its language: {@link HydraniumScopeProvider} is bound per grammar, and a
+    * request that names no document at all still carries the AST type
+    * `ExtendedServiceRegistry.soleServicesByType` routes on.
+    *
+    * The result is not registered, so nothing downstream can see it, and
+    * `LangiumDocumentFactory.update` would read from disk. It is a probe, not a
+    * document under construction; content that must survive belongs in a
+    * virtual document, which carries real source text.
+    *
+    * Building the root by hand instead needs the entry type name and a cast
+    * past the generated types, and leaves those lists `undefined`. A grammar
+    * whose entry rule opens with mandatory syntax yields a parse error here,
+    * and it is kept: `AstReflection.isComplete` is `false` for such a root
+    * however it is built, so the error states the same thing.
     */
-   abstract createEmptyDocument(uri: URI): LangiumDocument<AstNode>;
+   createEmptyDocument(uri: URI, languageId?: string): LangiumDocument<AstNode> {
+      if (languageId !== undefined) {
+         return this.langiumDocumentFactory.fromStringInLanguage('', uri, languageId);
+      }
+      if (!this.services.ServiceRegistry.getServicesFor(uri)) {
+         // Reported here rather than left to the parse, which ends on the empty
+         // extension and so names neither the URI nor the id that would have
+         // answered.
+         throw new Error(NO_LANGUAGE_FOR_STAND_IN.format({ uri: uri.toString() }));
+      }
+      // The two-argument overload is synchronous; passing a cancellation token
+      // selects the promise-returning one, which this contract cannot await.
+      return this.langiumDocumentFactory.fromString('', uri);
+   }
 
    override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
       const resolved = this.uriPolicy.loadUri(uri);
@@ -68,27 +150,18 @@ export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDo
             return await super.getOrCreateDocument(resolved);
          } catch (error: unknown) {
             // Load lost a race with a concurrent create — return that document.
+            // Checked before propagating, so a race is not reported as a
+            // missing file; cancellation carries no document and falls through.
             const reentrant = this.getDocument(resolved);
             if (reentrant) {
                this.services.workspace.CstResidencyService.rehydrate(reentrant);
                return reentrant;
             }
-            // No concurrent document, so the load genuinely failed. The fallback
-            // below still runs, because the file-not-found case is the ordinary
-            // one here and no provider-independent way to recognise it exists:
-            // Node's provider throws `ENOENT`, the in-memory one a bare `Error`,
-            // and the provider is a seam an adopter rebinds. Discriminating on
-            // message text across that seam would be a worse defect than the
-            // one it fixes. So the failure is TRACED rather than propagated —
-            // an unreadable-but-present file still degrades to an empty
-            // document, but it stops doing so silently.
-            this.tracer
-               .with(resolved.toString())
-               .debug(`Load failed, falling back to an empty document: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
          }
       }
-      // No loadable content (missing / synthetic / not yet written): a transient
-      // empty placeholder keyed canonically — not registered (see the class doc).
-      return this.createEmptyDocument(resolved ?? uri);
+      // The seam reports no loadable content, so there is nothing to read and
+      // no error from a read to carry.
+      throw new Error(NO_LOADABLE_CONTENT.format({ uri: uri.toString() }));
    }
 }

package/src/langium/workspace/virtual-document.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { URI } from '@hydranium/langium';
+import { type FileSystemNode, URI } from '@hydranium/langium';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 
 /**
@@ -76,14 +76,19 @@ export function isVirtualUri(uri: URI | string): boolean {
  * is not virtual or no document is registered for it (so a FileSystemProvider
  * delegates to its real backing).
  *
- * The framework's FileSystemProvider defaults call this at the top of
- * `readFile` / `readFileSync` so a virtual document survives a re-read:
+ * The framework's FileSystemProvider defaults consult this across their whole
+ * read surface, so a virtual document survives a re-read:
  * `DocumentBuilder.update` / `LangiumDocumentFactory.update` re-read a changed
  * URI from the FileSystemProvider, and nothing on disk backs a virtual URI. The
  * text comes from the registered document — the original source for a
  * `fromString` document, or the serialized form retained by the framework's
  * `fromModel` (which fills in the text Langium leaves empty). No serializer is
  * consulted here; the text is already on the document.
+ *
+ * **Every read method has to agree.** Serving only the text methods leaves one
+ * provider answering "here is the content" and "nothing is there" about one
+ * URI, which is a worse contract than answering neither: a caller cannot probe
+ * before reading.
  */
 export function serveVirtualDocument(services: ServerSharedServicesMinimal, uri: URI): string | undefined {
    if (!isVirtualUri(uri)) {
@@ -92,3 +97,16 @@ export function serveVirtualDocument(services: ServerSharedServicesMinimal, uri:
    const document = services.workspace.LangiumDocuments.getDocument(uri);
    return document ? document.textDocument.getText() : undefined;
 }
+
+/**
+ * The filesystem node a registered virtual document presents as, or `undefined`
+ * on the same terms as {@link serveVirtualDocument}.
+ *
+ * Always a FILE: a virtual document is a leaf carrying text, and nothing is
+ * addressable beneath it. Reporting it as a directory instead would put it in
+ * front of a workspace walk that would then try to enumerate children it has
+ * none of.
+ */
+export function serveVirtualNode(services: ServerSharedServicesMinimal, uri: URI): FileSystemNode | undefined {
+   return serveVirtualDocument(services, uri) === undefined ? undefined : { isFile: true, isDirectory: false, uri };
+}