@hydranium/core 1.0.0-next.16 → 1.0.0-next.168

package/src/langium/workspace/file-not-found.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 URI } from '@hydranium/langium';
+
+// Not re-exported from the workspace barrel: the framework's providers share
+// it, and it is no API of theirs.
+
+/**
+ * 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. The last close relies on it to
+ * tell a document gone meanwhile from any other failed rebuild.
+ */
+export function notFound(message: string, uri: URI): Error {
+   return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
+}

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

@@ -9,18 +9,18 @@
 
 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';
 
 /**
- * Empty-filesystem default {@link WritableFileSystemProvider}. For
- * in-memory / browser / test / CLI hosts that don't have a real filesystem.
- * All writes are no-ops. This is the portable `.`-entry default; the
- * Node-backed `DefaultFileSystemProvider`
- * lives in `@hydranium/core/node` (it pulls `node:fs`).
+ * Empty-filesystem {@link WritableFileSystemProvider}. For browser / test / CLI
+ * hosts that don't have a real filesystem. All writes are no-ops. On the
+ * portable `.` entry it is the {@link FileSystemProviderRegistry.host} when
+ * `context.fileSystemProvider` gives no writable provider; the Node-backed
+ * `DefaultFileSystemProvider` lives in `@hydranium/core/node` (it pulls
+ * `node:fs`).
  */
 export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider implements WritableFileSystemProvider {
    protected readonly tracer: Tracer;
@@ -37,16 +37,153 @@ export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider impl
       // no-op
    }
 
-   // 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();
+   // `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. The
+   // base declares `readFile` and `readBinary` param-less, so the param is
+   // optional there.
+   override async readFile(_uri?: URI): Promise<string> {
+      return super.readFile();
    }
 
-   override readFileSync(uri?: URI): string {
-      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
-      return served !== undefined ? served : super.readFileSync();
+   override async readBinary(_uri?: URI): Promise<Uint8Array> {
+      return super.readBinary();
+   }
+
+   override async stat(uri: URI): Promise<FileSystemNode> {
+      return super.stat(uri);
+   }
+}
+
+/**
+ * The provider bound on `workspace.FileSystemProvider`: it dispatches each call
+ * by the URI's scheme to the provider registered for it in the shared
+ * `fileSystemProviders` group, and to the {@link host} for any scheme without
+ * one.
+ *
+ * So one provider answers for each scheme, and a host's provider needs to know
+ * only its own: the framework registers `virtual:` there, and an adopter adds a
+ * scheme by contributing to the group. The host takes every unclaimed scheme
+ * rather than `file:` alone, which keeps an in-memory workspace under `memory:`
+ * or any other scheme on the host's provider.
+ *
+ * `THost` types the host, so an adopter whose own provider has more members
+ * than the base declares the slot as `FileSystemProviderRegistry<MyProvider>`,
+ * binds a {@link DefaultFileSystemProviderRegistry} with that host, and reads
+ * those members through `services.workspace.FileSystemProvider.host`.
+ */
+export interface FileSystemProviderRegistry<
+   THost extends WritableFileSystemProvider = WritableFileSystemProvider
+> extends WritableFileSystemProvider {
+   /** The provider for every scheme no entry of `fileSystemProviders` claims. */
+   readonly host: THost;
+   /** The provider that answers for `uri`. */
+   providerFor(uri: URI): WritableFileSystemProvider;
+}
+
+/** Options for {@link DefaultFileSystemProviderRegistry}. */
+export interface FileSystemProviderRegistryOptions<
+   THost extends WritableFileSystemProvider = WritableFileSystemProvider
+> extends LogNameOptions {
+   /**
+    * The provider for every scheme no entry of `fileSystemProviders` claims.
+    * The framework passes the provider `context.fileSystemProvider` returns,
+    * or a {@link DefaultEmptyFileSystemProvider} when that is not writable.
+    */
+   host: THost;
+}
+
+/**
+ * The framework's {@link FileSystemProviderRegistry}.
+ *
+ * A directory is listed by the provider of its own scheme, so a workspace
+ * root's tree comes from that provider alone.
+ *
+ * `realpath` and `mtimeMs` are always present and forward to the scheme's
+ * provider. Where that provider lacks one, `realpath` returns the URI unchanged
+ * and `mtimeMs` returns `undefined`: the answers `RealpathDocumentUriPolicy`
+ * and the self-save filter already give a provider without them.
+ */
+export class DefaultFileSystemProviderRegistry<
+   THost extends WritableFileSystemProvider = WritableFileSystemProvider
+> implements FileSystemProviderRegistry<THost> {
+   readonly host: THost;
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal & { fileSystemProviders: Record<string, WritableFileSystemProvider> },
+      options: FileSystemProviderRegistryOptions<THost>
+   ) {
+      this.host = options.host;
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   /**
+    * The group is read per call, not in the constructor, so a registered
+    * provider is built on first use and may read slots that reach back to this
+    * one. Only an OWN key of the group counts: the DI container resolves any
+    * key found on the prototype chain, so a scheme such as `constructor` would
+    * otherwise dispatch to a function.
+    */
+   providerFor(uri: URI): WritableFileSystemProvider {
+      const providers = this.services.fileSystemProviders;
+      return Object.hasOwn(providers, uri.scheme) ? providers[uri.scheme] : this.host;
+   }
+
+   // The async methods are `async` so a provider that throws synchronously from
+   // one still rejects, for the reason `DefaultEmptyFileSystemProvider` gives.
+   async writeFile(uri: URI, content: string): Promise<void> {
+      return this.providerFor(uri).writeFile(uri, content);
+   }
+
+   async mtimeMs(uri: URI): Promise<number | undefined> {
+      return this.providerFor(uri).mtimeMs?.(uri);
+   }
+
+   realpath(uri: URI): URI | undefined {
+      const provider = this.providerFor(uri);
+      return provider.realpath ? provider.realpath(uri) : uri;
+   }
+
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.providerFor(uri).stat(uri);
+   }
+
+   statSync(uri: URI): FileSystemNode {
+      return this.providerFor(uri).statSync(uri);
+   }
+
+   async exists(uri: URI): Promise<boolean> {
+      return this.providerFor(uri).exists(uri);
+   }
+
+   existsSync(uri: URI): boolean {
+      return this.providerFor(uri).existsSync(uri);
+   }
+
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.providerFor(uri).readBinary(uri);
+   }
+
+   readBinarySync(uri: URI): Uint8Array {
+      return this.providerFor(uri).readBinarySync(uri);
+   }
+
+   async readFile(uri: URI): Promise<string> {
+      return this.providerFor(uri).readFile(uri);
+   }
+
+   readFileSync(uri: URI): string {
+      return this.providerFor(uri).readFileSync(uri);
+   }
+
+   async readDirectory(uri: URI): Promise<FileSystemNode[]> {
+      return this.providerFor(uri).readDirectory(uri);
+   }
+
+   readDirectorySync(uri: URI): FileSystemNode[] {
+      return this.providerFor(uri).readDirectorySync(uri);
    }
 }

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

@@ -8,10 +8,11 @@
  ********************************************************************************/
 
 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 { DefaultWorkspaceManager, DocumentState, 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';
@@ -92,6 +93,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 +137,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 +169,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 +218,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 +289,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 +456,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
@@ -380,9 +501,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

@@ -8,11 +8,40 @@
  ********************************************************************************/
 
 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 { notFound } from './file-not-found.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'
+);
 
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
@@ -116,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: ${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 {
@@ -152,7 +183,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> {
@@ -229,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;