@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,412 @@
+/********************************************************************************
+ * 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 { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
+import { DefaultWorkspaceManager, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver';
+import type { WorkspaceFolder } from 'vscode-languageserver-types';
+import { type LogNameOptions, resolveLogFilePlaceholder, toLogFileWorkspaceToken } from '../diagnostics/logger.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 DocumentUriPolicy, findRealpathDivergence } from './document-uri-policy.js';
+import { type AdditionalDocumentContribution, collectAdditionalDocuments } from './additional-document-contribution.js';
+import { onProcessEvent } from '../../util/environment.js';
+
+/**
+ * Module-level guard so repeated workspace-manager construction (e.g.
+ * test environments creating multiple instances across files) doesn't
+ * pile up listeners on the `process` singleton.
+ */
+let operationCancelledSuppressionInstalled = false;
+
+/**
+ * The logger the installed listener routes through, re-pointed by every
+ * install rather than captured by the first. A process hosts more than one
+ * services tree — a test worker builds many, and a CLI subcommand spawns one
+ * beside a running head — and a handler holding the first tree's logger sends
+ * every later tree's genuine rejections to a logger nobody is reading.
+ */
+let operationCancelledSuppressionLogger: Logger | undefined;
+
+/**
+ * Decide what to do with a process-level unhandled promise rejection.
+ *
+ * Langium's internal `Symbol(OperationCancelled)` marker — emitted when a
+ * `documentBuilder.build` is preempted by a concurrent write lock or
+ * cancellation token — is benign and is swallowed silently (without it the
+ * server logs spurious "Unhandled rejection" entries for cancellations that
+ * are not errors).
+ *
+ * Every OTHER reason is re-surfaced through {@link Logger.error}. This matters
+ * because Node disables its default crash/warn for ALL unhandled rejections as
+ * soon as any `unhandledRejection` listener is registered — so a handler that
+ * swallowed everything would make genuine unhandled rejections (real bugs)
+ * vanish silently. Logging keeps them visible while preserving the server's
+ * resilience (it does not re-crash the process).
+ *
+ * Pure and listener-free so it is unit-testable without touching the `process`
+ * singleton; {@link installOperationCancelledSuppression} wires it up.
+ */
+export function handleProcessUnhandledRejection(reason: unknown, logger: Logger): void {
+   if (typeof reason === 'symbol' && String(reason) === 'Symbol(OperationCancelled)') {
+      return;
+   }
+   logger.error('Unhandled promise rejection: ' + (reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)));
+}
+
+/**
+ * Install a process-level `unhandledRejection` listener that routes every
+ * rejection through {@link handleProcessUnhandledRejection} — swallowing
+ * Langium's `OperationCancelled` marker and logging everything else via the
+ * supplied {@link Logger}.
+ *
+ * Idempotent — safe to call from every {@link HydraniumWorkspaceManager}
+ * constructor. The `process` listener is installed at most once, because one
+ * per tree would pile up on a singleton, but each call RE-POINTS the logger it
+ * routes through: the listener reads it at rejection time rather than closing
+ * over the first caller's, so the most recently built tree is the one that
+ * hears about a genuine rejection.
+ *
+ * Applies to every Langium-based server that experiences concurrent builds.
+ */
+export function installOperationCancelledSuppression(logger: Logger): void {
+   operationCancelledSuppressionLogger = logger;
+   if (operationCancelledSuppressionInstalled) {
+      return;
+   }
+   operationCancelledSuppressionInstalled = true;
+   // Node-only: a browser worker has no `process` / `unhandledRejection` — the
+   // accessor makes this a no-op there.
+   onProcessEvent('unhandledRejection', reason => {
+      if (operationCancelledSuppressionLogger) {
+         handleProcessUnhandledRejection(reason, operationCancelledSuppressionLogger);
+      }
+   });
+}
+
+/**
+ * Framework {@link DefaultWorkspaceManager} subclass that integrates the
+ * project tier with Langium's workspace startup.
+ *
+ * ## Phase 0 — project discovery
+ *
+ * Overrides {@link performStartup} to await
+ * {@link ProjectManager.discoverProjects} **before** Langium's standard
+ * startup phases (additional documents → file traversal → workspace
+ * documents). By the time `documentBuilder.build` runs, the project
+ * registry is fully populated and every parsed document can resolve its
+ * owning project via `projectManager.getProject(uri)`.
+ *
+ * Single-project consumers using `SingleProjectManager` pay no cost —
+ * the override is a no-op resolve.
+ *
+ * Discovery has a side effect the startup sequence has to compensate for:
+ * it reads each descriptor through `LangiumDocuments.getOrCreateDocument`,
+ * so those documents already exist when Langium's traversal runs — and
+ * Langium's traversal deliberately drops URIs that already have a document
+ * ("ensure that the documents don't already exist"), so it never returns
+ * them. {@link performStartup} adds them back; see the method comment for
+ * what breaks without it.
+ *
+ * ## Cascade rebuild
+ *
+ * Subscribes to {@link ProjectManager.onProjectsChanged} in the
+ * constructor. When a project's identity, version, or dependencies
+ * change post-startup, the project manager emits the affected document
+ * 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.
+ *
+ * Descriptor URIs that triggered the cycle are intentionally excluded
+ * from the affected set by `AbstractProjectManager.onBuildUpdate` —
+ * re-adding them would loop.
+ */
+export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
+   protected readonly projectManager: ProjectManager;
+   protected readonly tracer: Tracer;
+
+   /**
+    * Deferred backing {@link workspaceInitialized}. The framework default
+    * resolves it from {@link initializeWorkspace} once Langium's standard
+    * workspace setup completes. Adopters that need to gate first-`didOpen`
+    * on additional async work (project-scope discovery, schema fetch, etc.)
+    * override {@link initializeWorkspace} and resolve / reject this Deferred
+    * after their work completes.
+    */
+   protected readonly workspaceInitializedDeferred = new Deferred<unknown>();
+
+   /**
+    * Resolves when the workspace is ready to handle the first `didOpen`
+    * event. `HydraniumTextDocuments.listen` awaits this promise inside its
+    * `didOpen` handler so the gate is hit at first use, not at DI. The
+    * framework resolves it from {@link initializeWorkspace}; adopters with
+    * extra async init override `initializeWorkspace` to thread their work
+    * before the resolve.
+    */
+   readonly workspaceInitialized: Promise<unknown> = this.workspaceInitializedDeferred.promise;
+
+   protected readonly uriPolicy: DocumentUriPolicy;
+   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'];
+
+   constructor(services: ServerSharedServicesMinimal, options: LogNameOptions = {}) {
+      super(services);
+      this.projectManager = services.workspace.ProjectManager;
+      this.projectManager.onProjectsChanged(event => this.onProjectsChanged(event));
+      this.uriPolicy = services.workspace.DocumentUriPolicy;
+      this.writableFileSystemProvider = services.workspace.FileSystemProvider;
+      this.additionalDocuments = services.additionalDocuments;
+      this.languageRegistry = services.ServiceRegistry;
+      this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceManager').trace('instantiated');
+      installOperationCancelledSuppression(this.tracer);
+   }
+
+   /**
+    * Contribution form of Langium's `loadAdditionalDocuments`. Runs the base
+    * behaviour first (a no-op unless a further subclass adds documents), then
+    * lets every {@link AdditionalDocumentContribution} in the shared
+    * `additionalDocuments` group build in-memory documents via the bound
+    * `LangiumDocumentFactory` and seed them through Langium's `collector`
+    * — so each is added to the workspace and indexed like a file-backed
+    * document. Adopters contribute a stdlib / built-in set here instead of
+    * overriding this method.
+    */
+   protected override async loadAdditionalDocuments(
+      folders: WorkspaceFolder[],
+      collector: (document: LangiumDocument) => void
+   ): Promise<void> {
+      await super.loadAdditionalDocuments(folders, collector);
+      const contributions = Object.keys(this.additionalDocuments);
+      if (contributions.length === 0) {
+         return;
+      }
+      // Observable like the discovery / build-phase spans: one timed line
+      // reporting how many contributions ran and how many documents they
+      // 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;
+      await this.tracer.time(
+         'Load additional documents',
+         async () => {
+            await collectAdditionalDocuments(this.additionalDocuments, folders, document => {
+               documentCount++;
+               this.warnIfUnroutable(document);
+               collector(document);
+            });
+            tags.push(`${documentCount} documents`);
+         },
+         'info',
+         { logAfterMs: 0, tags }
+      );
+   }
+
+   /**
+    * 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.
+    *
+    * 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
+    * extension by passing it as the last segment,
+    * `virtualUri(contributor, 'name.<ext>')`.
+    */
+   protected warnIfUnroutable(document: LangiumDocument): void {
+      if (this.languageRegistry.hasServices(document.uri)) {
+         return;
+      }
+      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(', ')}); ` +
+            '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.
+      this.resolveWorkspaceLogTarget(folders);
+      // Snapshot the document set around discovery so the descriptor documents
+      // it creates can be identified afterwards. Plain iteration rather than
+      // stream operators, so the two passes work against any conforming
+      // `LangiumDocuments`; both run once per workspace initialization, next to
+      // a discovery walk of the whole tree.
+      const beforeDiscovery = new Set<string>();
+      for (const document of this.langiumDocuments.all) {
+         beforeDiscovery.add(document.uri.toString());
+      }
+      // Phase 0: project discovery. By the time Langium's standard startup
+      // runs below, `getProject(uri)` returns a definitive answer for every URI
+      // that belongs to a discovered project.
+      await this.projectManager.discoverProjects(folders);
+      const discovered: LangiumDocument[] = [];
+      for (const document of this.langiumDocuments.all) {
+         if (!beforeDiscovery.has(document.uri.toString())) {
+            discovered.push(document);
+         }
+      }
+      const documents = await super.performStartup(folders);
+      this.probePathDivergence(folders);
+      return this.withDiscoveredDescriptors(documents, discovered);
+   }
+
+   /**
+    * Add back the documents project discovery created that Langium's file
+    * traversal then filtered out.
+    *
+    * `AbstractProjectManager.discoverProjects` has to parse each descriptor to
+    * read it, which it does through `LangiumDocuments.getOrCreateDocument`.
+    * Langium's `performStartup` traversal skips any URI that already has a
+    * document, so every descriptor is missing from the list it returns — and
+    * `initializeWorkspace` builds exactly that list.
+    *
+    * The consequence is not a slow first build but a WRONG one. Descriptor
+    * documents stay at `Parsed` with nothing in the global index, while the
+    * documents that did make the list run all the way through `Linked` against
+    * that empty index. Every cross-document reference into a descriptor fails,
+    * and the failure sticks: a later build skips documents already at
+    * `Validated`, so nothing re-links them until the user edits the file.
+    *
+    * Invisible to an adopter whose descriptors ARE its model files (every file
+    * is a descriptor, the returned list is empty, `build([])` is a no-op).
+    * Fatal for one whose descriptors are a subset — a folder-scoped project
+    * model, or a second grammar whose files are never descriptors.
+    *
+    * Only documents created by discovery are re-added: pre-existing ones are
+    * either additional/library documents (already collected by
+    * `loadAdditionalDocuments`) or leftovers from an earlier initialization,
+    * and neither belongs in this build list.
+    */
+   protected withDiscoveredDescriptors(documents: LangiumDocument[], discovered: readonly LangiumDocument[]): LangiumDocument[] {
+      if (discovered.length === 0) {
+         return documents;
+      }
+      const collected = new Set(documents.map(document => document.uri.toString()));
+      const missing = discovered.filter(document => !collected.has(document.uri.toString()));
+      if (missing.length === 0) {
+         return documents;
+      }
+      this.tracer.debug(`Re-adding ${missing.length} project-descriptor document(s) to the initial build.`);
+      return [...missing, ...documents];
+   }
+
+   /**
+    * One-shot startup diagnostic. Warns when a workspace root resolves through a
+    * symlink / `..` / case variant, so the URI a client opens (`S`) diverges
+    * from the canonical document identity (`R`) the build keys by — the
+    * condition the {@link DocumentUriPolicy} seam exists to reconcile.
+    * Probing the roots is sufficient and cheap: a divergent ancestor means every
+    * file beneath it diverges, and the loaded documents' URIs are already
+    * canonical (their original spelling is gone). Emits NOTHING for a plain
+    * on-disk workspace, or a filesystem without `realpath` — so a non-empty line
+    * is the empirical signal that a deployment actually exercises the divergence
+    * machinery.
+    */
+   protected probePathDivergence(folders: WorkspaceFolder[]): void {
+      if (!this.uriPolicy) {
+         return;
+      }
+      for (const folder of folders) {
+         const real = findRealpathDivergence(folder.uri, this.writableFileSystemProvider);
+         if (!real) {
+            continue;
+         }
+         const policyName = this.uriPolicy.constructor.name;
+         const collapsed = this.uriPolicy.canonicalUri(folder.uri) === this.uriPolicy.canonicalUri(real);
+         this.tracer.warn(
+            `Workspace root '${folder.uri}' resolves through a symlink/'..'/case variant to '${real.toString()}', ` +
+               `so client URIs under it diverge from canonical document identity. ` +
+               (collapsed
+                  ? `The bound ${policyName} collapses both spellings to one identity, so subscriptions stay consistent.`
+                  : `The bound ${policyName} does NOT collapse them — the link and its target would become distinct documents.`)
+         );
+      }
+   }
+
+   /**
+    * 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
+    * derivation — a log-capturing test harness uses the same function so the
+    * server's file name and the harness's correlation key agree.
+    */
+   protected resolveWorkspaceLogTarget(folders: WorkspaceFolder[]): void {
+      const first = folders[0];
+      if (first) {
+         resolveLogFilePlaceholder('workspace', toLogFileWorkspaceToken(first.uri));
+      }
+   }
+
+   /**
+    * Override of Langium's workspace setup to resolve / reject
+    * {@link workspaceInitializedDeferred} once setup completes. Adopters with
+    * extra async work override this method, do their work in a sub-helper,
+    * and either delegate to `super.initializeWorkspace(...)` (preserving the
+    * default resolve) or call `this.workspaceInitializedDeferred.resolve(...)`
+    * themselves after the additional work finishes.
+    */
+   override async initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise<void> {
+      try {
+         await super.initializeWorkspace(folders, cancelToken);
+         this.workspaceInitializedDeferred.resolve(undefined);
+      } catch (error) {
+         this.workspaceInitializedDeferred.reject(error);
+         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.
+    *
+    * Subclasses can override for additional behaviour (e.g. logging,
+    * telemetry, custom rebuild policies); call `super` to preserve the
+    * default cascade.
+    */
+   protected onProjectsChanged(event: ProjectChangeEvent): void {
+      for (const uri of event.affectedDocuments) {
+         const document = this.langiumDocuments.getDocument(uri);
+         if (document) {
+            this.documentBuilder.resetToState(document, DocumentState.Changed);
+         }
+      }
+   }
+
+   /**
+    * Format a URI as a workspace-relative path suitable for log messages.
+    * Returns the path relative to `workspace` when provided (defaults to the
+    * first workspace folder's URI); falls back to the URI string when no
+    * workspace folder is known. Adopters with a multi-workspace model or a
+    * different display convention override on their workspace-manager
+    * subclass.
+    */
+   wsRelativePath(uri: URI | string, workspace?: string): string;
+   wsRelativePath(uri: URI | string, workspace = this.workspaceFolders?.[0]?.uri): string {
+      return workspace ? UriUtils.relative(workspace, uri) : typeof uri === 'string' ? uri : uri.path.toString();
+   }
+}

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

@@ -0,0 +1,241 @@
+/********************************************************************************
+ * 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 FileSystemNode, URI } from '@hydranium/langium';
+import { 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';
+
+/**
+ * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
+ *
+ * Keys are absolute URI strings unless {@link InMemoryFileSystemOptions.rootUri}
+ * is given, in which case they are relative to it. The relative form is what
+ * lets a build step emit the record without knowing where the host will mount
+ * the workspace.
+ */
+export type FileSystemSeed = Readonly<Record<string, string>>;
+
+/** Options for {@link InMemoryFileSystemProvider} and {@link inMemoryFileSystem}. */
+export interface InMemoryFileSystemOptions extends LogNameOptions {
+   /** Initial content. Absent leaves the filesystem empty but writable. */
+   seed?: FileSystemSeed;
+   /**
+    * Prefix for relative {@link seed} keys, without a trailing separator. When
+    * omitted the keys are taken as absolute URIs.
+    */
+   rootUri?: string;
+}
+
+/**
+ * A writable filesystem held in a `Map`, for a host with no disk — a browser
+ * worker, or a test that needs the workspace walk to find real content.
+ *
+ * # Why neither shipped provider stands in
+ *
+ * `DefaultEmptyFileSystemProvider` is genuinely empty (reads throw, writes
+ * are dropped) and the disk-backed one in `@hydranium/core/node` pulls
+ * `node:fs`, which a browser bundle refuses to resolve. A host that means to
+ * open a workspace without a disk needs a third thing: real contents, no
+ * syscalls.
+ *
+ * # It must be typed writable, not merely `FileSystemProvider`
+ *
+ * The `fileSystemProvider` context slot accepts what it is handed only if that
+ * carries `writeFile`; anything narrower is silently replaced by the empty
+ * default, which presents as "the workspace is empty" rather than as a wiring
+ * error. A read-only in-memory provider is therefore not a smaller version of
+ * this one — it is one that does not bind.
+ *
+ * # Directories are implied, never stored
+ *
+ * Only files are held. A directory exists exactly when some file key sits under
+ * it, which is what keeps a write a single `Map.set` with no parent-creation
+ * step to forget. The cost is that an empty directory cannot be represented; the
+ * workspace walk does not need one, and a stored directory set would be a second
+ * source of truth to keep in step with the first.
+ *
+ * # A trailing separator is stripped on every lookup
+ *
+ * Langium spells the workspace root both with and without one depending on which
+ * walk asks, so normalising only where a directory prefix is computed leaves
+ * `stat` and `exists` disagreeing with `readDirectory` about the same folder.
+ *
+ * # What it deliberately does not answer
+ *
+ * No watch notifications, no case-insensitivity, no eviction policy for a
+ * workspace larger than memory. `mtimeMs` and `realpath` are omitted rather than
+ * stubbed, which the framework degrades on by design: the self-save filter lets
+ * the change through and the URI policy keeps the URI it was given.
+ *
+ * Nor does the map outlive the host: every write is lost when the process or the
+ * page goes. `PersistentFileSystemProvider` is the subclass that mirrors
+ * the same writes into an asynchronous backing store, and it is a subclass
+ * rather than an option because the map has to stay the read path either way.
+ */
+export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
+   protected readonly files = new Map<string, string>();
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal,
+      options: InMemoryFileSystemOptions = {}
+   ) {
+      const { seed = {}, rootUri } = options;
+      for (const [path, content] of Object.entries(seed)) {
+         this.files.set(normalize(rootUri === undefined ? path : `${rootUri}/${path}`), content);
+      }
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated', {
+         files: this.files.size
+      });
+   }
+
+   /**
+    * Replace the content at `uri`, creating it if absent. The synchronous twin
+    * of `writeFile`, for a test that mutates the filesystem between builds
+    * rather than through the server.
+    */
+   setFile(uri: URI, content: string): void {
+      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));
+   }
+
+   async writeFile(uri: URI, content: string): Promise<void> {
+      this.setFile(uri, content);
+   }
+
+   readFile(uri: URI): Promise<string> {
+      return Promise.resolve(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()}`);
+      }
+      return content;
+   }
+
+   readBinary(uri: URI): Promise<Uint8Array> {
+      return Promise.resolve(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));
+   }
+
+   statSync(uri: URI): FileSystemNode {
+      const path = normalize(uri);
+      if (this.files.has(path)) {
+         return { isFile: true, isDirectory: false, uri };
+      }
+      if (this.hasChildren(path)) {
+         return { isFile: false, isDirectory: true, uri };
+      }
+      throw new Error(`No such file or directory: ${uri.toString()}`);
+   }
+
+   exists(uri: URI): Promise<boolean> {
+      return Promise.resolve(this.existsSync(uri));
+   }
+
+   existsSync(uri: URI): boolean {
+      const path = normalize(uri);
+      return this.files.has(path) || this.hasChildren(path);
+   }
+
+   readDirectory(uri: URI): Promise<FileSystemNode[]> {
+      return Promise.resolve(this.readDirectorySync(uri));
+   }
+
+   readDirectorySync(uri: URI): FileSystemNode[] {
+      const prefix = `${normalize(uri)}/`;
+      const children = new Map<string, boolean>();
+      for (const path of this.files.keys()) {
+         if (!path.startsWith(prefix)) {
+            continue;
+         }
+         const remainder = path.slice(prefix.length);
+         const separator = remainder.indexOf('/');
+         const name = separator < 0 ? remainder : remainder.slice(0, separator);
+         if (!children.has(name)) {
+            children.set(name, separator < 0);
+         }
+      }
+      return [...children].map(([name, isFile]) => ({
+         isFile,
+         isDirectory: !isFile,
+         uri: URI.parse(`${prefix}${name}`)
+      }));
+   }
+
+   /**
+    * The map key for `uri`.
+    *
+    * Exposed for a subclass that mirrors the map into a second store and has to
+    * key it the same way. Deriving a key from `uri.toString()` instead agrees
+    * with this one for every ordinary path and disagrees for exactly the ones
+    * normalisation exists for — a percent-encodable character, a trailing
+    * separator — so the stored entry becomes unfindable in the case nobody
+    * tests.
+    */
+   protected fileKey(uri: URI | string): string {
+      return normalize(uri);
+   }
+
+   protected hasChildren(path: string): boolean {
+      const prefix = `${path}/`;
+      for (const candidate of this.files.keys()) {
+         if (candidate.startsWith(prefix)) {
+            return true;
+         }
+      }
+      return false;
+   }
+}
+
+/**
+ * Key a URI into the file map: parsed so a seeded string and a URI the framework
+ * hands back agree on percent-encoding, then stripped of a trailing separator so
+ * a folder spelled both ways is one entry.
+ */
+function normalize(uri: URI | string): string {
+   const text = typeof uri === 'string' ? URI.parse(uri).toString() : uri.toString();
+   return text.endsWith('/') ? text.slice(0, -1) : text;
+}
+
+/**
+ * Module fragment binding an {@link InMemoryFileSystemProvider}, spread into the
+ * 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.
+ */
+export function inMemoryFileSystem(options: InMemoryFileSystemOptions = {}): {
+   fileSystemProvider: (services: unknown) => WritableFileSystemProvider;
+} {
+   return {
+      fileSystemProvider: serverSharedFactory(services => new InMemoryFileSystemProvider(services, options))
+   };
+}