@hydranium/core 1.0.0-next.39 → 1.0.0-next.391

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

@@ -7,10 +7,31 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { type Clock, type Tracer } from '@hydranium/protocol';
 import { DefaultWorkspaceLock, type MaybePromise } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { runInWriteLockScope } from './write-lock-scope.js';
 
+/** Constructor options for {@link HydraniumWorkspaceLock}. */
+export interface HydraniumWorkspaceLockOptions extends LogNameOptions {
+   /**
+    * How long a write may keep running after a later write cancelled it before
+    * the lock logs a warning. Every write and read waits behind it meanwhile, so
+    * one that never ends stops the server. Defaults to 10 s; `0` turns the
+    * check off.
+    */
+   readonly stalledWriteWarnMs?: number;
+}
+
+const DEFAULT_STALLED_WRITE_WARN_MS = 10_000;
+
+/** The write action a {@link HydraniumWorkspaceLock} is running, with the timer its cancellation started. */
+export interface RunningWrite {
+   stallTimer?: Disposable;
+}
+
 /**
  * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
  * write-lock scope, so anything it reaches can be asked whether the lock is
@@ -29,7 +50,85 @@ 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;
+   protected readonly clock: Clock;
+   protected readonly tracer: Tracer;
+   protected readonly stalledWriteWarnMs: number;
+   protected runningWrite?: RunningWrite;
+   /** Writes queued and not yet started. */
+   protected queuedWrites = 0;
+
+   constructor(services: Pick<ServerSharedServicesMinimal, 'Clock' | 'Tracer'>, options: HydraniumWorkspaceLockOptions = {}) {
+      super();
+      this.clock = services.Clock;
+      this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceLock');
+      this.stalledWriteWarnMs = options.stalledWriteWarnMs ?? DEFAULT_STALLED_WRITE_WARN_MS;
+   }
+
+   /**
+    * How many calls to `write` or `cancelWrite` came while a write was still
+    * queued or running. 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. A different number read after the caller's write ended
+    * does not prove that write was cancelled, since a later write that
+    * cancels another queued or running write counts too. A caller that
+    * retries on it builds once more than it needs to.
+    */
+   get writeCancellations(): number {
+      return this.cancelledWriteCount;
+   }
+
    override write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void> {
-      return super.write(token => runInWriteLockScope(() => action(token)));
+      const queued = super.write(token => {
+         this.queuedWrites--;
+         return runInWriteLockScope(() => this.runWrite(action, token));
+      });
+      // Counted after Langium's `write` has cancelled the write before it, so the new write does not count itself.
+      this.queuedWrites++;
+      return queued;
+   }
+
+   /** Run `action` as {@link runningWrite}, so a cancellation while it runs can time it. */
+   protected async runWrite(action: (token: CancellationToken) => MaybePromise<void>, token: CancellationToken): Promise<void> {
+      const running: RunningWrite = {};
+      this.runningWrite = running;
+      try {
+         await action(token);
+      } finally {
+         running.stallTimer?.dispose();
+         if (this.runningWrite === running) {
+            this.runningWrite = undefined;
+         }
+      }
+   }
+
+   /**
+    * Counted here rather than in {@link write}, because Langium's `write` cancels
+    * through this method too. A write that has ended is not counted, so the
+    * next write does not count as cancelling it. A write running when this is
+    * called has been cancelled, by this call or an earlier one, so its timer
+    * starts here.
+    */
+   override cancelWrite(): void {
+      if (this.queuedWrites > 0 || this.runningWrite !== undefined) {
+         this.cancelledWriteCount++;
+      }
+      const running = this.runningWrite;
+      if (running && !running.stallTimer && this.stalledWriteWarnMs > 0) {
+         running.stallTimer = this.clock.setTimer(() => this.reportStalledWrite(), this.stalledWriteWarnMs);
+      }
+      super.cancelWrite();
+   }
+
+   protected reportStalledWrite(): void {
+      this.tracer.warn(
+         `A write is still running ${this.stalledWriteWarnMs} ms after it was cancelled, and every write and read waits behind it. ` +
+            'Likely causes: a model-service write or rebuild from inside a build in a host with no write-lock scope tracker, ' +
+            'which waits for the build it runs in, or a write action that ignores its cancellation token. ' +
+            'See https://github.com/eclipse-emfcloud/hydranium/issues/245.'
+      );
    }
 }

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

@@ -7,19 +7,29 @@
  * 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, type InitializeParams } from 'vscode-languageserver';
+import { Deferred, type Logger, type Tracer, describeError, describeErrorWithStack } from '@hydranium/protocol';
+import {
+   DefaultWorkspaceManager,
+   DocumentState,
+   interruptAndCheck,
+   isOperationCancelled,
+   type LangiumDocument,
+   type Stream,
+   UriUtils,
+   type URI
+} from '@hydranium/langium';
+import { type CancellationToken, CancellationTokenSource, 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.
@@ -37,6 +47,13 @@ let operationCancelledSuppressionInstalled = false;
  */
 let operationCancelledSuppressionLogger: Logger | undefined;
 
+/**
+ * Never cancelled: `interruptAndCheck` yields only for a token other than
+ * `CancellationToken.None`, and the load must not stop part-way, since Langium
+ * checks for cancellation once every document exists.
+ */
+const LOAD_YIELD_TOKEN = new CancellationTokenSource().token;
+
 /**
  * Decide what to do with a process-level unhandled promise rejection.
  *
@@ -60,7 +77,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));
 }
 
 /**
@@ -93,6 +110,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.
@@ -125,8 +154,9 @@ 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. A project manager that defers
+ * the relink emits them from a follow-up build of its own instead.
  *
  * Descriptor URIs that triggered the cycle are intentionally excluded
  * from the affected set by `AbstractProjectManager.onBuildUpdate` —
@@ -163,8 +193,14 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
    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>();
+   /** How many documents {@link loadWorkspaceDocuments} reads and parses before it may yield; below 1 counts as 1. */
+   protected readonly loadChunkSize: number = 10;
 
-   constructor(services: ServerSharedServicesMinimal, options: LogNameOptions = {}) {
+   constructor(services: ServerSharedServicesMinimal, options: HydraniumWorkspaceManagerOptions = {}) {
       super(services);
       this.projectManager = services.workspace.ProjectManager;
       this.projectManager.onProjectsChanged(event => this.onProjectsChanged(event));
@@ -173,6 +209,7 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       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);
    }
@@ -201,16 +238,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 }
@@ -221,17 +258,18 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
     * Warn when a seeded additional document's URI matches no registered
     * language.
     *
-    * Such a document is added to the workspace and indexed, but every
-    * per-language service is resolved per URI — so scope computation, naming,
-    * validation and serialisation all fail to route to it, and it contributes
-    * nothing to the scopes it was written to populate. Nothing else reports
-    * this: the document exists, so no lookup errors, it is simply inert.
+    * Every per-language service is resolved per URI, so the workspace cannot
+    * load such a document: adding it throws, and the startup build fails
+    * with an error naming only the extension, not the document. This
+    * line names the document and the fix first.
     *
-    * The usual cause is a `virtualUri` with no file extension:
-    * `virtualUri(contributor)` yields `virtual:<contributor>`, and routing has
-    * nothing to match on — there is no extension, and a virtual document is
-    * never open in `TextDocuments`, so the declared-languageId rung cannot
-    * serve it either. The convention is to end the URI with a registered
+    * The usual cause is a `fromModel` or `fromStringInLanguage` document
+    * under a `virtualUri` with no file extension: `virtualUri(contributor)`
+    * yields `virtual:<contributor>`, and routing has nothing to match on —
+    * there is no extension, and a virtual document is never open in
+    * `TextDocuments`, so the declared-languageId rung cannot serve it either.
+    * A `fromString` document under such a URI never gets here: its parse
+    * throws first. The convention is to end the URI with a registered
     * extension by passing it as the last segment,
     * `virtualUri(contributor, 'name.<ext>')`.
     */
@@ -241,17 +279,16 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       }
       const extensions = this.languageRegistry.all.flatMap(language => language.LanguageMetaData.fileExtensions);
       this.tracer.warn(
-         `Additional document '${document.uri.toString()}' matches no registered language, so every per-language ` +
-            'service (scope computation, naming, validation, serialization) will fail to route to it and it will ' +
-            `contribute nothing to scopes. End its URI with a registered file extension (${extensions.join(', ')}); ` +
+         `Additional document '${document.uri.toString()}' matches no registered language, so the workspace ` +
+            `cannot load it and the startup build fails. End its URI with a registered file extension (${extensions.join(', ')}); ` +
             'for a virtual document that means passing it as the last segment, `virtualUri(contributor, "name.<ext>")`.'
       );
    }
 
    protected override async performStartup(folders: WorkspaceFolder[]): Promise<LangiumDocument[]> {
-      // Resolve the `{workspace}` file-tee placeholder (if configured) as early
-      // as possible — before any build logging — so per-workspace log capture
-      // names its file correctly and the buffered startup lines flush.
+      // Supply the `{workspace}` placeholder as early as possible — before any
+      // build logging — so per-workspace log capture names its file correctly
+      // and the buffered startup lines flush; the CPU profile reads it too.
       this.resolveWorkspaceLogTarget(folders);
       // Snapshot the document set around discovery so the descriptor documents
       // it creates can be identified afterwards. Plain iteration rather than
@@ -272,11 +309,136 @@ 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);
    }
 
+   /**
+    * Load the documents the file traversal found through
+    * {@link loadTraversedDocument}, {@link loadChunkSize} at a time, yielding
+    * between chunks once Langium's interruption period has passed. Langium's
+    * own load starts every read at once and parses each as it returns: over a
+    * synchronous provider nothing else runs until the last file has parsed, and
+    * over the Node provider incoming messages wait through long runs of parses.
+    * The cost: at most a chunk of reads is in flight, and each chunk waits for
+    * its slowest read, so slow storage takes a round per chunk, not one burst.
+    *
+    * Each loaded document is recorded, 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> {
+      const pending = uris.toArray();
+      const chunkSize = Math.max(1, this.loadChunkSize);
+      for (let i = 0; i < pending.length; i += chunkSize) {
+         if (i > 0) {
+            await interruptAndCheck(LOAD_YIELD_TOKEN);
+         }
+         await Promise.all(
+            pending.slice(i, i + chunkSize).map(async uri => {
+               const document = await this.loadTraversedDocument(uri);
+               if (document) {
+                  this.traversedUris.add(document.uri.toString());
+                  collector(document);
+               }
+            })
+         );
+      }
+   }
+
+   /**
+    * Load one document the file traversal found, or answer `undefined` to
+    * leave it out of the workspace.
+    *
+    * A file whose read fails and that the provider's `existsSettled`, or
+    * `exists` for a provider without it, reports gone is left out with a debug
+    * line, since it went between the scan and the read. A file still there is
+    * read once more, since a replacing rename can hide its name for a moment;
+    * that read's failure, and cancellation, fail the startup. A check that
+    * throws counts the file as there, since it cannot say the file went. The
+    * skip is the startup's only: other callers of `getOrCreateDocument` still
+    * get the read error.
+    */
+   protected async loadTraversedDocument(uri: URI): Promise<LangiumDocument | undefined> {
+      try {
+         return await this.langiumDocuments.getOrCreateDocument(uri);
+      } catch (error: unknown) {
+         if (isOperationCancelled(error)) {
+            throw error;
+         }
+         const fileSystem = this.writableFileSystemProvider;
+         if (!(await (fileSystem.existsSettled?.(uri) ?? fileSystem.exists(uri)).catch(() => true))) {
+            this.tracer.debug(`Skipped ${uri.toString()}: it was removed between the workspace scan and its load`);
+            return undefined;
+         }
+         return this.langiumDocuments.getOrCreateDocument(uri);
+      }
+   }
+
+   /**
+    * 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.
@@ -351,9 +513,10 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
    }
 
    /**
-    * Resolve the `{workspace}` file-tee placeholder from the first workspace
-    * folder. No-op when no folder is known or no `{workspace}`-templated log
-    * target is configured. See {@link toLogFileWorkspaceToken} for the token
+    * Supply the `{workspace}` placeholder from the first workspace folder, which
+    * the log file-tee and the CPU profile's file name both read, whether or not
+    * a log target is configured. No-op when no folder is known. See
+    * {@link toLogFileWorkspaceToken} for the token
     * derivation — a log-capturing test harness uses the same function so the
     * server's file name and the harness's correlation key agree.
     */
@@ -396,22 +559,38 @@ 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. A failed startup also
+    * rejects `ready`, so its waiters fail rather than wait forever; an override
+    * that skips `super` and catches a failed startup rejects `_ready` too.
     */
    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);
+         // Langium settles `ready` only after a startup that succeeded. Marked
+         // handled, as logged above; a no-op once startup has resolved it.
+         this._ready.reject(error);
+         this._ready.promise.catch(() => undefined);
          throw error;
       }
    }
 
    /**
     * 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. Under the project manager's
+    * `deferMemberRelink`, its follow-up build emits the members instead.
     *
     * 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,46 @@
 
 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'
+);
+
+/** A delete addressed a URI the provider cannot reach on disk, as {@link UNSUPPORTED_WRITE} a write. */
+export const UNSUPPORTED_DELETE = defineMessage(
+   'hydranium/core/unsupported-delete',
+   'Cannot delete {uri}: the scheme names no location on disk'
+);
+
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
  *
@@ -117,41 +142,47 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       this.files.set(normalize(uri), content);
    }
 
-   /** Remove the file at `uri`. A no-op when nothing is there. */
-   deleteFile(uri: URI): void {
-      this.files.delete(normalize(uri));
+   /** Remove the file at `uri`. A no-op when nothing is there; a directory is refused. */
+   async deleteFile(uri: URI): Promise<void> {
+      const key = normalize(uri);
+      if (this.hasChildren(key)) {
+         throw new Error(`Cannot delete ${uri.toString()}: it is a directory`);
+      }
+      this.files.delete(key);
    }
 
    async writeFile(uri: URI, content: string): Promise<void> {
       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 +193,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 +270,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

@@ -7,10 +7,13 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './ast-node-locator.js';
 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 './syntax-errors.js';
 export * from './index-manager.js';
 export * from './initialize-workspace.js';
 export * from './langium-documents.js';