@hydranium/core 1.0.0-next.27 → 1.0.0-next.271

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

@@ -7,18 +7,28 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-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 { Deferred, type Logger, type Tracer, describeError, describeErrorWithStack } from '@hydranium/protocol';
+import {
+   DefaultWorkspaceManager,
+   DocumentState,
+   isOperationCancelled,
+   type LangiumDocument,
+   type Stream,
+   UriUtils,
+   type URI
+} from '@hydranium/langium';
+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';
-import type { WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import type { WritableFileSystemProvider } from './file-system-provider.js';
 import { type DocumentUriPolicy, findRealpathDivergence } from './document-uri-policy.js';
 import { type AdditionalDocumentContribution, collectAdditionalDocuments } from './additional-document-contribution.js';
 import { onProcessEvent } from '../../util/environment.js';
+import { isConnectionGoneError } from '../../util/connection-liveness.js';
 
 /**
  * Module-level guard so repeated workspace-manager construction (e.g.
@@ -59,7 +69,7 @@ export function handleProcessUnhandledRejection(reason: unknown, logger: Logger)
    if (typeof reason === 'symbol' && String(reason) === 'Symbol(OperationCancelled)') {
       return;
    }
-   logger.error('Unhandled promise rejection: ' + (reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)));
+   logger.error('Unhandled promise rejection: ' + describeErrorWithStack(reason));
 }
 
 /**
@@ -92,6 +102,18 @@ export function installOperationCancelledSuppression(logger: Logger): void {
    });
 }
 
+/** Options for {@link HydraniumWorkspaceManager}. */
+export interface HydraniumWorkspaceManagerOptions extends LogNameOptions {
+   /**
+    * Whether startup warns about seeded documents the bound
+    * `FileSystemProvider` cannot serve (see
+    * {@link HydraniumWorkspaceManager.warnIfDocumentsUnserved}). Defaults to
+    * `true`; turn it off for a host that drops such documents at their last
+    * close on purpose.
+    */
+   warnUnservedDocuments?: boolean;
+}
+
 /**
  * Framework {@link DefaultWorkspaceManager} subclass that integrates the
  * project tier with Langium's workspace startup.
@@ -124,8 +146,8 @@ export function installOperationCancelledSuppression(logger: Logger): void {
  * URIs (its own members plus any transitive dependents per the
  * `getAffectedProjects` hook). This manager re-runs
  * `DocumentBuilder.resetToState(doc, DocumentState.Changed)` on each
- * affected document so the next build cycle re-links them with the new
- * visibility scope.
+ * affected document so the build of the update that changed the descriptor
+ * re-links them with the new visibility scope.
  *
  * Descriptor URIs that triggered the cycle are intentionally excluded
  * from the affected set by `AbstractProjectManager.onBuildUpdate` —
@@ -156,19 +178,27 @@ 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. */
    protected readonly languageRegistry: ServerSharedServicesMinimal['ServiceRegistry'];
+   /** Whether startup runs {@link warnIfDocumentsUnserved}. */
+   protected readonly warnUnservedDocuments: boolean;
+   /** URIs of the documents the running startup's file traversal loaded; see {@link loadWorkspaceDocuments}. */
+   protected readonly traversedUris = new Set<string>();
 
-   constructor(services: ServerSharedServicesMinimal, options: LogNameOptions = {}) {
+   constructor(services: ServerSharedServicesMinimal, options: HydraniumWorkspaceManagerOptions = {}) {
       super(services);
       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;
+      this.warnUnservedDocuments = options.warnUnservedDocuments ?? true;
       this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceManager').trace('instantiated');
       installOperationCancelledSuppression(this.tracer);
    }
@@ -197,16 +227,16 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       // seeded. `tags` is read at the done-emit, so the document count pushed
       // inside the callback appears in the log line.
       const tags: string[] = [`${contributions.length} contributions`];
-      let documentCount = 0;
+      const seeded: LangiumDocument[] = [];
       await this.tracer.time(
          'Load additional documents',
          async () => {
             await collectAdditionalDocuments(this.additionalDocuments, folders, document => {
-               documentCount++;
+               seeded.push(document);
                this.warnIfUnroutable(document);
                collector(document);
             });
-            tags.push(`${documentCount} documents`);
+            tags.push(`${seeded.length} documents`);
          },
          'info',
          { logAfterMs: 0, tags }
@@ -268,11 +298,86 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
             discovered.push(document);
          }
       }
-      const documents = await super.performStartup(folders);
+      this.traversedUris.clear();
+      let documents: LangiumDocument[];
+      try {
+         documents = await super.performStartup(folders);
+         if (this.warnUnservedDocuments) {
+            await this.warnIfDocumentsUnserved(documents.filter(document => !this.traversedUris.has(document.uri.toString())));
+         }
+      } finally {
+         this.traversedUris.clear();
+      }
       this.probePathDivergence(folders);
       return this.withDiscoveredDescriptors(documents, discovered);
    }
 
+   /**
+    * Record each document the file traversal loads, so startup can tell them
+    * from the documents `loadAdditionalDocuments` seeded, through the
+    * `additionalDocuments` group or an override of its own.
+    *
+    * The traversal found each of its documents through the provider, so asking
+    * it again whether they exist costs one call per workspace file and cannot
+    * come out false. Telling them apart by scheme does not work either: the
+    * registry's host answers every scheme no other provider claims, a seeded
+    * scheme nobody serves included. An override that loads documents without
+    * delegating here leaves them unrecorded, so startup asks the provider
+    * about each of them.
+    */
+   protected override async loadWorkspaceDocuments(uris: Stream<URI>, collector: (document: LangiumDocument) => void): Promise<void> {
+      await super.loadWorkspaceDocuments(uris, document => {
+         this.traversedUris.add(document.uri.toString());
+         collector(document);
+      });
+   }
+
+   /**
+    * Warn once when the bound `FileSystemProvider` cannot serve a seeded
+    * document, naming each such document's scheme.
+    *
+    * The last close keeps a document only if the provider says it `exists`, so
+    * each such document leaves the workspace the first time an editor closes
+    * it, and whatever resolved against it breaks. The framework's registry
+    * serves `virtual:` through the `fileSystemProviders` group and every other
+    * scheme through its host, which knows nothing of a scheme an adopter
+    * invented for its seeded documents, and nothing else reports the loss. A
+    * provider that throws counts as not serving the document, since a startup
+    * that failed on a diagnostic would be worse than the loss.
+    *
+    * Runs over every document startup collected outside the file traversal,
+    * which is what `loadAdditionalDocuments` seeded, through the
+    * `additionalDocuments` group or an override of that method, once startup
+    * has added them to the workspace, unless `warnUnservedDocuments` is
+    * `false`.
+    */
+   protected async warnIfDocumentsUnserved(documents: readonly LangiumDocument[]): Promise<void> {
+      const unserved: URI[] = [];
+      for (const document of documents) {
+         let served = false;
+         try {
+            served = await this.writableFileSystemProvider.exists(document.uri);
+         } catch {
+            // Counted as unserved, below.
+         }
+         if (!served) {
+            unserved.push(document.uri);
+         }
+      }
+      if (unserved.length === 0) {
+         return;
+      }
+      const schemes = [...new Set(unserved.map(uri => uri.scheme))];
+      const named = unserved.slice(0, 3).map(uri => uri.toString());
+      this.tracer.warn(
+         `${unserved.length} seeded document(s) under ${schemes.map(scheme => `${scheme}:`).join(', ')} cannot be served by the bound workspace.FileSystemProvider ` +
+            `(${named.join(', ')}${unserved.length > 3 ? ', …' : ''}), so each leaves the workspace at its ` +
+            `last close. Register a provider under the key ${schemes.map(scheme => `'${scheme}'`).join(', ')} in the shared ` +
+            'fileSystemProviders group, or serve the scheme from the host provider; set warnUnservedDocuments: false ' +
+            'to accept the loss.'
+      );
+   }
+
    /**
     * Add back the documents project discovery created that Langium's file
     * traversal then filtered out.
@@ -360,6 +465,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
@@ -367,12 +497,21 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
     * and either delegate to `super.initializeWorkspace(...)` (preserving the
     * default resolve) or call `this.workspaceInitializedDeferred.resolve(...)`
     * themselves after the additional work finishes.
+    *
+    * A failed setup is logged here, since every framework waiter on
+    * {@link workspaceInitialized} discards the rejection; an override that
+    * rejects the deferred itself logs its own failure.
     */
    override async initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise<void> {
       try {
          await super.initializeWorkspace(folders, cancelToken);
          this.workspaceInitializedDeferred.resolve(undefined);
-      } catch (error) {
+      } catch (error: unknown) {
+         if (isOperationCancelled(error) || isConnectionGoneError(error)) {
+            this.tracer.debug(`Initial workspace build did not complete: ${describeError(error)}`);
+         } else {
+            this.tracer.error(`Initial workspace build failed: ${describeErrorWithStack(error)}`);
+         }
          this.workspaceInitializedDeferred.reject(error);
          throw error;
       }
@@ -380,9 +519,9 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
 
    /**
     * Default cascade-rebuild handler. Iterates {@link ProjectChangeEvent.affectedDocuments}
-    * and resets each to {@link DocumentState.Changed} so the next build cycle
-    * re-runs the pipeline (parse → link → validate) under the new project
-    * visibility scope.
+    * and resets each to {@link DocumentState.Changed} so the build of the update
+    * that changed the descriptor re-runs the pipeline (parse → link → validate)
+    * under the new project visibility scope.
     *
     * Subclasses can override for additional behaviour (e.g. logging,
     * telemetry, custom rebuild policies); call `super` to preserve the

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

@@ -9,21 +9,40 @@
 
 import { type FileSystemNode, URI } from '@hydranium/langium';
 import { defineMessage, type Tracer } from '@hydranium/protocol';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type WritableFileSystemProvider } from './file-system-provider.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
-import { serveVirtualDocument } from './virtual-document.js';
+import { notFound } from './file-not-found.js';
 
 /**
- * The browser host's spelling of "the document is not there". Its Node
- * counterpart is `NO_LOADABLE_CONTENT`: this provider has no `realpath`, so the
- * URI policy cannot answer the existence question ahead of the read and the miss
- * surfaces here instead.
+ * 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'
+);
+
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
  *
@@ -126,32 +145,34 @@ 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 {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return served;
-      }
       const content = this.files.get(normalize(uri));
       if (content === undefined) {
-         throw new Error(NO_SUCH_FILE.format({ uri: 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 {
@@ -162,7 +183,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       if (this.hasChildren(path)) {
          return { isFile: false, isDirectory: true, uri };
       }
-      throw new Error(NO_SUCH_PATH.format({ uri: uri.toString() }));
+      throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
    }
 
    exists(uri: URI): Promise<boolean> {
@@ -239,8 +260,8 @@ function normalize(uri: URI | string): string {
  * services context exactly where a Node host spreads `NodeFileSystem`.
  *
  * A host that needs to reach the provider afterwards — to seed or mutate it
- * mid-test — reads it back off `shared.workspace.FileSystemProvider`, since the
- * slot owns construction.
+ * mid-test — narrows `shared.workspace.FileSystemProvider.host` to this
+ * class, since the slot owns construction.
  */
 export function inMemoryFileSystem(options: InMemoryFileSystemOptions = {}): {
    fileSystemProvider: (services: unknown) => WritableFileSystemProvider;

package/src/langium/workspace/index.ts

@@ -11,6 +11,7 @@ export * from './document-uri-policy.js';
 export * from './file-system-provider.js';
 export * from './in-memory-file-system-provider.js';
 export * from './persistent-file-system-provider.js';
+export * from './self-save-registry.js';
 export * from './index-manager.js';
 export * from './initialize-workspace.js';
 export * from './langium-documents.js';

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,10 +7,11 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI } from '@hydranium/langium';
+import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI, UriUtils } 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';
 
 /**
  * The document a caller asked to load is not there.
@@ -22,6 +23,19 @@ import { type DocumentUriPolicy } from './document-uri-policy.js';
  */
 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
@@ -30,7 +44,7 @@ export const NO_LOADABLE_CONTENT = defineMessage('hydranium/core/no-loadable-con
  * depend on itself.
  */
 export interface HydraniumDocumentRegistry extends LangiumDocuments {
-   createEmptyDocument(uri: URI): LangiumDocument<AstNode>;
+   createEmptyDocument(uri: URI, languageId?: string): LangiumDocument<AstNode>;
 }
 
 /**
@@ -58,6 +72,13 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
    /** Document-identity seam, shared with the text store, event filters, and builder. */
    protected readonly uriPolicy: DocumentUriPolicy;
 
+   /**
+    * 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;
@@ -65,8 +86,9 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
 
    /**
     * Build a transient document for `uri` by parsing empty text with the
-    * grammar `uri` routes to, so the root is that language's entry type with
-    * every containment list initialised.
+    * 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.
@@ -75,6 +97,15 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
     * 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
@@ -86,12 +117,32 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
     * and it is kept: `AstReflection.isComplete` is `false` for such a root
     * however it is built, so the error states the same thing.
     */
-   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);
    }
 
+   /**
+    * Registers `document`, then reports it to `VersionSyncService.modelProduced`:
+    * a first load parses outside the build, so no build's re-parse reports it.
+    * That marks one below `Parsed`, such as the builder's placeholder for a new
+    * file, as a placeholder. A rejected duplicate is not reported.
+    */
+   override addDocument(document: LangiumDocument): void {
+      super.addDocument(document);
+      this.services.workspace.VersionSyncService.modelProduced(document);
+   }
+
    override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
       const resolved = this.uriPolicy.loadUri(uri);
       if (resolved) {
@@ -120,6 +171,13 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
             throw error;
          }
       }
+      // No file, but possibly a document: one created and not yet saved is
+      // built from its text and registered under its canonical URI.
+      const created = this.getDocument(UriUtils.toUri(this.uriPolicy.canonicalUri(uri)));
+      if (created) {
+         this.services.workspace.CstResidencyService.rehydrate(created);
+         return created;
+      }
       // 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/persistent-file-system-provider.ts

@@ -8,7 +8,8 @@
  ********************************************************************************/
 
 import { URI } from '@hydranium/langium';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { describeErrorWithStack } from '@hydranium/protocol';
+import { type WritableFileSystemProvider } from './file-system-provider.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type FileSystemSeed, InMemoryFileSystemProvider, type InMemoryFileSystemOptions } from './in-memory-file-system-provider.js';
 
@@ -125,13 +126,6 @@ export interface PersistentFileSystemOptions extends InMemoryFileSystemOptions {
  * restored as deleted, which is why the marker is NUL-wrapped and text a grammar
  * can parse is not.
  *
- * # A registered virtual document still wins
- *
- * `readFileSync` consults the virtual-document seam before the map, so a stdlib
- * contributed in code keeps answering for its URI whether or not the store holds
- * one. The store cannot shadow it, which is what keeps a rebuild that re-reads
- * that URI from losing the stdlib.
- *
  * # What it deliberately does not answer
  *
  * The store is scoped to the ORIGIN, not to the page: two pages on the same
@@ -257,7 +251,7 @@ export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
    }
 
    protected reportStoreFailure(operation: string, uri: URI, error: unknown): void {
-      this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${error instanceof Error ? error.message : String(error)}`);
+      this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${describeErrorWithStack(error)}`);
    }
 }