@hydranium/core 1.0.0-next.11 → 1.0.0-next.112

package/src/messages/index.ts

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Every user-facing message `@hydranium/core` raises, plus the carrier helpers
+ * that attach an identity to one.
+ *
+ * Declarations stay beside their call sites and are re-exported here, so this is
+ * enumeration rather than centralization: a code's package segment has to name
+ * the package that raises it. The English is a fallback, not a contract; the
+ * code is the contract, and renaming one is a breaking change.
+ */
+
+export * from './carriers.js';
+export * from './renderer.js';
+
+export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
+export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
+export {
+   INVALID_DEDENT,
+   UNEXPECTED_CHARACTER,
+   MISSING_ITERATION,
+   NO_VIABLE_ALTERNATIVE,
+   TRAILING_INPUT,
+   UNEXPECTED_TOKEN,
+   UNPOPPABLE_LEXER_MODE,
+   UNRESOLVED_REFERENCE
+} from '../langium/validation/document-validator.js';
+export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
+export { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from '../langium/workspace/in-memory-file-system-provider.js';

package/src/messages/renderer.ts

@@ -0,0 +1,206 @@
+/********************************************************************************
+ * 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 {
+   describeError,
+   renderFrameworkMessage,
+   resolve,
+   resolvedFromResponseError,
+   type Locale,
+   type MessageCatalogue,
+   type MessageDefinition,
+   type ParamsArg,
+   type ResolvedMessage,
+   type Tracer
+} from '@hydranium/protocol';
+import { SimpleCache } from '@hydranium/langium';
+import type { ResponseError } from 'vscode-jsonrpc';
+import { Diagnostic } from 'vscode-languageserver-protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import type { ServerLocale } from '../locale/server-locale.js';
+import { resolvedFromDiagnostic } from './carriers.js';
+
+/** Construction options for {@link DefaultMessageRenderer}. */
+export type MessageRendererOptions = LogNameOptions;
+
+/**
+ * The render contract the `MessageRenderer` slot holds, implemented by
+ * {@link DefaultMessageRenderer}.
+ *
+ * An interface rather than the class, so the slot is compared STRUCTURALLY. A
+ * class-typed slot carries its `protected` members into every assignability
+ * check and TypeScript compares those nominally — which makes the slot
+ * unsatisfiable by a subclass declared against a second physical copy of this
+ * package, which any duplicated install produces. It also
+ * lets an adopter REPLACE this declaration rather than intersect with it, so
+ * slot resolution does not depend on the order a services type is written in.
+ *
+ * Every method carries a no-throw contract; see the implementation.
+ */
+export interface MessageRenderer {
+   renderDiagnostic(diagnostic: Diagnostic): string;
+   renderError(error: ResponseError<unknown>): string;
+   renderMessage<S extends string>(message: MessageDefinition<S>, ...params: ParamsArg<S>): string;
+}
+
+/**
+ * Renders every user-facing message the server sends, in the locale the server
+ * was handed at init. The framework ships no catalogue, so its own behaviour is
+ * a pass-through.
+ *
+ * Adopters override {@link translationsFor}: the public render methods carry
+ * the no-throw contract, and the catalogue lookup they wrap is what can fail.
+ *
+ * Two render methods rather than one, because what is useful to an adopter is
+ * the carrier's structured fields and the two carriers have different ones. A
+ * single `render(text)` would force an adopter to match English prose, which
+ * breaks on the first Langium reword.
+ */
+export class DefaultMessageRenderer implements MessageRenderer {
+   protected readonly tracer: Tracer;
+   protected readonly serverLocale: ServerLocale;
+   /**
+    * {@link translationsFor}'s answer per locale, `undefined` answers included —
+    * a `SimpleCache` distinguishes "absent" from "cached as none", which matters
+    * because shipping no catalogue is the framework's own hot path.
+    *
+    * `SimpleCache` rather than Langium's `WorkspaceCache`: the eviction axis
+    * there is document change, and a catalogue does not depend on documents, so
+    * it would evict on every build AND put a `DocumentBuilder` dependency on a
+    * service the shared tier declares free of one. Nothing evicts this: the
+    * locale arrives once per process. A subclass whose catalogue can change
+    * clears it.
+    */
+   protected readonly catalogues = new SimpleCache<Locale | undefined, MessageCatalogue | undefined>();
+
+   constructor(services: ServerSharedServicesMinimal, options: MessageRendererOptions = {}) {
+      this.serverLocale = services.ServerLocale;
+      this.tracer = services.Tracer.for(options.logName ?? 'MessageRenderer').trace('instantiated');
+   }
+
+   /**
+    * The sentence to publish for `diagnostic`, replacing its current `message`.
+    * Sees lexer and parser errors too, which Langium pushes onto the document
+    * without routing them through `toDiagnostic`.
+    *
+    * **Must not throw**, which is why the guard is here and not at the call
+    * site: this runs inside the `Validated` phase, and Langium's
+    * `notifyDocumentPhase` rethrows anything that is not a cancellation — so an
+    * escaping error leaves the document AT `Validated` with the phase's
+    * listeners never run, and the client receives no diagnostics for that file.
+    * A subclass overriding this method takes that contract on itself.
+    */
+   renderDiagnostic(diagnostic: Diagnostic): string {
+      try {
+         const resolved = resolvedFromDiagnostic(diagnostic);
+         return resolved ? this.render(resolved) : Diagnostic.getMessageString(diagnostic);
+      } catch (err: unknown) {
+         this.reportFailure(err, 'a diagnostic');
+         return Diagnostic.getMessageString(diagnostic);
+      }
+   }
+
+   /**
+    * The sentence to send for `error`, replacing its current `message`. Same
+    * no-throw contract as {@link renderDiagnostic}: an escaping error replaces a
+    * typed rejection the caller can handle with one it cannot.
+    */
+   renderError(error: ResponseError<unknown>): string {
+      try {
+         const resolved = resolvedFromResponseError(error);
+         return resolved ? this.render(resolved) : error.message;
+      } catch (err: unknown) {
+         this.reportFailure(err, 'an RPC error');
+         return error.message;
+      }
+   }
+
+   /**
+    * The sentence for a declaration the caller holds directly, for a carrier
+    * with no slot to put an identity in.
+    *
+    * GLSP's action protocol is the case: every member of its message, status
+    * and reject actions is prose or an enum, so a code cannot travel and the
+    * raise site is the last place that still knows which message this is.
+    * Prefer {@link renderDiagnostic} / {@link renderError} wherever a carrier
+    * does hold the identity — they keep the render off the raise site, so an
+    * adopter's own messages ride the same one binding.
+    *
+    * Same no-throw contract as the carrier methods.
+    */
+   renderMessage<S extends string>(message: MessageDefinition<S>, ...params: ParamsArg<S>): string {
+      // `resolve` is inside the guard with the render, not before it: it calls
+      // the declaration's own `format`, which for an adopter declaration is
+      // arbitrary code, and a throw there would escape a method whose contract
+      // says it cannot.
+      let resolved: ResolvedMessage | undefined;
+      try {
+         resolved = resolve(message, ...params);
+         return this.render(resolved);
+      } catch (err: unknown) {
+         this.reportFailure(err, `the message '${message.code}'`);
+         // Unset only when `format` ITSELF threw, which leaves the
+         // uninterpolated template as the only text there is. A failed render
+         // still has the resolved English.
+         return resolved?.text ?? message.text;
+      }
+   }
+
+   /**
+    * The catalogue for the current locale, or `undefined` for none — the
+    * framework's answer, shipping none. Overriding this leaves every identity
+    * decision, every pass-through and the no-throw guard in place.
+    *
+    * **Called once per locale, not once per message**, so an override may load
+    * a file or build a map without that cost landing per diagnostic. The
+    * corollary is that a catalogue mutated in place afterwards is not seen;
+    * clear {@link catalogues} to invalidate.
+    *
+    * An adopter wanting Langium's own uncoded sentences instead matches
+    * `Diagnostic.data.code` from an overridden {@link renderDiagnostic}, never
+    * the sentence.
+    */
+   protected translationsFor(_locale: Locale | undefined): MessageCatalogue | undefined {
+      return undefined;
+   }
+
+   /**
+    * Resolve one identity against the current locale's catalogue.
+    *
+    * Reads the locale per call. Copying it into a field at construction pins
+    * whatever was there before init ran, which is always `undefined` — services
+    * compose first.
+    *
+    * The catalogue behind it is memoized, because a workspace-wide validation
+    * renders once per diagnostic and the naive override — parse a JSON file,
+    * build a map — then pays that per diagnostic rather than per locale.
+    */
+   protected render(message: ResolvedMessage): string {
+      const locale = this.serverLocale.value;
+      return renderFrameworkMessage(
+         message,
+         this.catalogues.get(locale, () => this.translationsFor(locale))
+      );
+   }
+
+   /**
+    * Emit a failed render. Logged rather than swallowed: the fallback output is
+    * byte-identical to a correctly-configured default, so a throwing catalogue
+    * is otherwise invisible.
+    */
+   protected reportFailure(err: unknown, carrier: string): void {
+      this.tracer.error(this.formatRenderFailure(err, carrier));
+   }
+
+   /** Format the failed-render line. Override to name the adopter's catalogue entry. */
+   protected formatRenderFailure(err: unknown, carrier: string): string {
+      return `rendering ${carrier} failed; falling back to the server's own text. ${describeError(err)}`;
+   }
+}

package/src/node/heap-ceiling.ts

@@ -0,0 +1,108 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/*
+ * Choosing `--max-old-space-size` for a child process, which is a decision no
+ * caller gets right by picking a number.
+ *
+ * A fixed ceiling is sized for the machine the author had. Pass 8192 to a
+ * process under a 2 GiB cgroup limit and V8 lets old space grow past the limit
+ * without ever collecting hard, so the kernel OOM-kills the whole container
+ * before V8 has any reason to act — the parent sees a signal, not a heap error,
+ * and everything sharing the cgroup dies with it. Pass nothing on a large
+ * desktop and V8 sizes from physical RAM, which for a memory-heavy tool is well
+ * under what it needs.
+ *
+ * Both are the same mistake: a ceiling stated without reference to the limit
+ * that is actually in force. The rule here is to name the desktop default
+ * explicitly and step aside inside a container, where Node derives its own
+ * ceiling from the cgroup limit and a runaway heap therefore fails INSIDE the
+ * child — attributable, and reported as a heap error against one process rather
+ * than as a kill against every process in the cgroup.
+ */
+
+import * as os from 'node:os';
+
+/** Options for {@link heapCeilingArgs}. */
+export interface HeapCeilingOptions {
+   /**
+    * Ceiling in MiB to pass when no cgroup limit is in force. Name the value a
+    * memory-heavy run on a workstation needs; it is ignored inside a container.
+    */
+   readonly desktopDefaultMb: number;
+   /**
+    * Caller-supplied override, typically an environment variable, and typically
+    * `undefined`. A finite value at or above {@link minMb} wins everywhere,
+    * container or not — an operator who states a number has decided. An explicit
+    * `0` means "let Node decide" and emits no flag. Anything unparseable is
+    * REPORTED through {@link warn} rather than ignored: `8G` is a natural thing
+    * to type into a variable measured in MiB, and silently dropping it leaves
+    * the operator believing a ceiling is in force.
+    */
+   readonly envValue?: string;
+   /**
+    * Smallest override to pass on. Below it, {@link warn} is called and NO flag
+    * is emitted: a value that small can only be a misconfiguration — GiB typed
+    * where MiB was meant — and V8 fatals at startup once it is small enough.
+    * Deliberately not clamped UP: running with a different number than the one
+    * configured hides the mistake instead of surfacing it. Omitted means no floor.
+    */
+   readonly minMb?: number;
+   /** Where a rejected override is reported. Defaults to `console.warn`. */
+   readonly warn?: (message: string) => void;
+   /** Cgroup limit in bytes; defaults to this process's. Injectable for tests. */
+   readonly constrained?: number;
+   /** Host physical memory in bytes; defaults to `os.totalmem()`. Injectable for tests. */
+   readonly total?: number;
+}
+
+/**
+ * Whether a cgroup memory limit is in force — i.e. whether the OOM killer is
+ * watching a ceiling lower than (or equal to) the machine's own.
+ *
+ * **`constrained > 0` is not the test, and that is the whole reason this is a
+ * named function.** With no limit set, cgroup v2 reports 2^64 and v1 reports
+ * ~2^63 rather than 0, so the naive test reads every desktop as a container.
+ * Neither sentinel can equal `os.totalmem()`, so comparing against the host
+ * total costs nothing and rules both out. The comparison is `<=` rather than
+ * `<` so a limit set to exactly the host's RAM still counts as a limit.
+ */
+export function isMemoryConstrained(constrained = process.constrainedMemory?.() ?? 0, total = os.totalmem()): boolean {
+   return constrained > 0 && constrained <= total;
+}
+
+/**
+ * The `execArgv` entries that set a child's heap ceiling: `[]` to let Node size
+ * the heap itself, or a single `--max-old-space-size=<mb>`.
+ *
+ * Returns an array rather than a string so a caller can spread it
+ * unconditionally into an argv it is building.
+ */
+export function heapCeilingArgs(options: HeapCeilingOptions): string[] {
+   const { desktopDefaultMb, envValue, minMb, warn = (message: string) => console.warn(message) } = options;
+   if (envValue !== undefined) {
+      const mb = Number(envValue);
+      // An explicit 0 is a decision — "let Node decide" — so it passes quietly.
+      // Anything else that is not a positive number is a typo, and the operator
+      // who typed it is the one person who cannot tell it was dropped.
+      if (!Number.isFinite(mb) || mb < 0) {
+         warn(`Ignoring the heap ceiling '${envValue}': expected a whole number of MiB. Node will size the heap instead.`);
+         return [];
+      }
+      if (mb === 0) {
+         return [];
+      }
+      if (minMb !== undefined && mb < minMb) {
+         warn(`Ignoring a heap ceiling of ${envValue} MiB: below the ${minMb} MiB minimum. Node will size the heap instead.`);
+         return [];
+      }
+      return [`--max-old-space-size=${Math.floor(mb)}`];
+   }
+   return isMemoryConstrained(options.constrained, options.total) ? [] : [`--max-old-space-size=${desktopDefaultMb}`];
+}

package/src/node/index.ts

@@ -35,6 +35,7 @@ export * from './server-diagnostics.js';
 // entry alongside the default policy.
 export * from './ast-ground-truth.js';
 export * from './event-loop-monitor.js';
+export * from './heap-ceiling.js';
 export * from './latency-from-env.js';
 export * from './measure-memory.js';
 export * from './memory-monitor.js';

package/src/node/latency-from-env.ts

@@ -29,7 +29,7 @@ export function isLatencyEnabled(): boolean {
 
 /**
  * A {@link LatencyCollector} when {@link DEFAULT_LATENCY_ENV} is set, otherwise
- * `undefined`. Heads pass the result straight to `instrumentLspConnection`, the
+ * `undefined`. Heads pass the result straight to `lspLatencyOptions`, the
  * `DataServer` `latency` option and the RPC binder; all three treat `undefined`
  * as "seam off", so this single factory is the one place a head decides whether
  * timing runs. `clock` is forwarded to the collector so tests stay deterministic.

package/src/node/measure-memory.ts

@@ -174,6 +174,7 @@ export async function measureModelMemory(options: MeasureModelMemoryOptions): Pr
       result.churnGrowthBytes = growth;
       const verdict = growth > 5 * 1024 * 1024 ? 'POSSIBLE RETENTION' : 'stable (no leak)';
       log(`Rebuild churn growth ${Format.bytes(growth)} over ${editCycles} cycles - ${verdict}`);
+      log(`Documents after churn: ${shared.workspace.LangiumDocuments.all.toArray().length}`);
    }
 
    if (options.writeSnapshot) {

package/src/node/node-file-system-provider.ts

@@ -8,16 +8,18 @@
  ********************************************************************************/
 
 import { type Tracer } from '@hydranium/protocol';
-import { URI, UriUtils } from '@hydranium/langium';
+import { type FileSystemNode, URI, UriUtils } from '@hydranium/langium';
 import { NodeFileSystemProvider } from '@hydranium/langium/node';
 import { randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import { type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
 import { type SelfSaveRegistry } from '../documents/self-save-registry.js';
+import { renameOverOpenReaders } from './rename-over-open-readers.js';
 import { type LogNameOptions } from '../langium/diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../langium/shared-services.js';
-import { serveVirtualDocument } from '../langium/workspace/virtual-document.js';
+import { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from '../langium/workspace/in-memory-file-system-provider.js';
+import { serveVirtualDocument, serveVirtualNode } from '../langium/workspace/virtual-document.js';
 
 /**
  * Node-based default {@link WritableFileSystemProvider}. Extends Langium's
@@ -27,6 +29,13 @@ import { serveVirtualDocument } from '../langium/workspace/virtual-document.js';
  * {@link SelfSaveRegistry} bound at `services.workspace.SelfSaveRegistry` — so
  * consumers can suppress the `didChangeWatchedFiles` echo for their own writes.
  *
+ * Its read surface answers for registered virtual documents and refuses to
+ * derive a disk path from a URI that names no disk location — see
+ * {@link servesFromDisk}, which is the one place that judgement is made. Every
+ * method that derives an OS path is held to it, writes most of all: a read that
+ * skipped it would only mis-report, while a write would CREATE a file at a path
+ * the URI never named.
+ *
  * Server-only (`@hydranium/core/node`): pulls `node:fs`. The portable `.`
  * entry binds `DefaultEmptyFileSystemProvider` by default, so a Node host
  * must rebind this slot — through `context.fileSystemProvider` or directly — to
@@ -45,15 +54,114 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
       this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
    }
 
-   // Serve virtual documents from the registered document before touching disk
-   // (a virtual URI has no `fsPath` backing); delegate everything else to Node.
+   /**
+    * Whether `uri` names something this provider can reach on disk.
+    *
+    * Only a `file:` URI does. `URI.fsPath` yields a path for ANY scheme — for a
+    * hierarchical one it is the path component, which for a schemed URI with no
+    * authority comes out RELATIVE — so delegating an unrecognised scheme to Node
+    * does not fail, it probes `<cwd>/<path>` and answers about whatever
+    * unrelated file happens to sit there. A server whose working directory is
+    * the workspace root makes that collision ordinary rather than exotic.
+    *
+    * Note the deliberate disagreement with {@link realpath}, which treats a
+    * non-`file:` URI as PRESENT. The two degrade in opposite directions because
+    * they answer different questions: identity has to hand back a usable URI, so
+    * its safe answer is the one it was given, while occupancy and content must
+    * not be invented from an unrelated path, so their safe answer is "nothing
+    * here". A subclass adding a second on-disk scheme widens this and nothing
+    * else.
+    */
+   protected servesFromDisk(uri: URI): boolean {
+      return uri.scheme === 'file';
+   }
+
+   // Each read resolves in the same order: a registered virtual document first
+   // (it has no `fsPath` backing), then disk for a path this provider can
+   // reach, then the filesystem's own "nothing here" answer — never a probe
+   // against a path derived from a URI that names no disk location.
    override readFile(uri: URI): Promise<string> {
       const served = serveVirtualDocument(this.services, uri);
-      return served !== undefined ? Promise.resolve(served) : super.readFile(uri);
+      if (served !== undefined) {
+         return Promise.resolve(served);
+      }
+      return this.servesFromDisk(uri) ? super.readFile(uri) : Promise.reject(noSuchFile(uri));
    }
 
    override readFileSync(uri: URI): string {
-      return serveVirtualDocument(this.services, uri) ?? super.readFileSync(uri);
+      const served = serveVirtualDocument(this.services, uri);
+      if (served !== undefined) {
+         return served;
+      }
+      if (!this.servesFromDisk(uri)) {
+         throw noSuchFile(uri);
+      }
+      return super.readFileSync(uri);
+   }
+
+   override readBinary(uri: URI): Promise<Uint8Array> {
+      const served = serveVirtualDocument(this.services, uri);
+      if (served !== undefined) {
+         return Promise.resolve(encode(served));
+      }
+      return this.servesFromDisk(uri) ? super.readBinary(uri) : Promise.reject(noSuchFile(uri));
+   }
+
+   override readBinarySync(uri: URI): Uint8Array {
+      const served = serveVirtualDocument(this.services, uri);
+      if (served !== undefined) {
+         return encode(served);
+      }
+      if (!this.servesFromDisk(uri)) {
+         throw noSuchFile(uri);
+      }
+      return super.readBinarySync(uri);
+   }
+
+   override stat(uri: URI): Promise<FileSystemNode> {
+      const served = serveVirtualNode(this.services, uri);
+      if (served !== undefined) {
+         return Promise.resolve(served);
+      }
+      return this.servesFromDisk(uri) ? super.stat(uri) : Promise.reject(noSuchPath(uri));
+   }
+
+   override statSync(uri: URI): FileSystemNode {
+      const served = serveVirtualNode(this.services, uri);
+      if (served !== undefined) {
+         return served;
+      }
+      if (!this.servesFromDisk(uri)) {
+         throw noSuchPath(uri);
+      }
+      return super.statSync(uri);
+   }
+
+   // Delegating to `existsSync` would be shorter and would put a blocking stat
+   // on the async path.
+   override async exists(uri: URI): Promise<boolean> {
+      if (serveVirtualDocument(this.services, uri) !== undefined) {
+         return true;
+      }
+      return this.servesFromDisk(uri) ? super.exists(uri) : false;
+   }
+
+   override existsSync(uri: URI): boolean {
+      if (serveVirtualDocument(this.services, uri) !== undefined) {
+         return true;
+      }
+      return this.servesFromDisk(uri) ? super.existsSync(uri) : false;
+   }
+
+   // A URI this provider cannot reach on disk has no children rather than an
+   // error: a workspace walk enumerates folders it was handed, and failing one
+   // aborts the walk where an empty listing simply contributes nothing.
+   override readDirectory(uri: URI): Promise<FileSystemNode[]> {
+      return this.servesFromDisk(uri) ? super.readDirectory(uri) : Promise.resolve([]);
+   }
+
+   override readDirectorySync(uri: URI): FileSystemNode[] {
+      return this.servesFromDisk(uri) ? super.readDirectorySync(uri) : [];
    }
 
    /**
@@ -103,6 +211,17 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
     * only possible, which is what settles the trade.
     */
    async writeFile(uri: URI, content: string): Promise<void> {
+      // BEFORE the `mkdir`, and before any other OS path is derived. The read
+      // surface degrades to "nothing here" for a URI naming no disk location;
+      // a write has no such harmless degradation — `fsPath` would hand it a
+      // real path regardless of scheme, so an unguarded write does not fail,
+      // it CREATES a file (and the directories above it) somewhere unrelated.
+      // Rejecting is the only safe answer: a caller holding a `memory:` or
+      // `untitled:` document has nowhere for it to go, and inventing a
+      // destination from the path component is never what it meant.
+      if (!this.servesFromDisk(uri)) {
+         throw unsupportedWrite(uri);
+      }
       await fsp.mkdir(UriUtils.dirname(uri).fsPath, { recursive: true });
       const destination = this.realpath(uri)?.fsPath ?? uri.fsPath;
       const replaced = await replacedFile(destination);
@@ -135,6 +254,15 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
    }
 
    async mtimeMs(uri: URI): Promise<number | undefined> {
+      // Same rule as the read surface, and "unknown" is already the answer the
+      // caller handles — so a URI naming no disk location reports no mtime
+      // rather than the modification time of whatever occupies its `fsPath`.
+      // A stamp borrowed from an unrelated file is worse than none: the
+      // self-save registry keys on it to suppress a watcher echo, so a
+      // coincidental match would drop a real external change.
+      if (!this.servesFromDisk(uri)) {
+         return undefined;
+      }
       try {
          const stat = await fsp.stat(uri.fsPath);
          return stat.mtimeMs;
@@ -168,6 +296,26 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
    }
 }
 
+/** The "no content here" rejection, for a URI naming no readable file. */
+function noSuchFile(uri: URI): Error {
+   return new Error(NO_SUCH_FILE.format({ uri: uri.toString() }));
+}
+
+/** The "nothing occupies this" rejection, for a URI naming no filesystem node. */
+function noSuchPath(uri: URI): Error {
+   return new Error(NO_SUCH_PATH.format({ uri: uri.toString() }));
+}
+
+/** The "nowhere to put this" rejection, for a write to a URI with no disk backing. */
+function unsupportedWrite(uri: URI): Error {
+   return new Error(UNSUPPORTED_WRITE.format({ uri: uri.toString() }));
+}
+
+/** A virtual document's text as the bytes a binary read returns. */
+function encode(text: string): Uint8Array {
+   return new TextEncoder().encode(text);
+}
+
 /**
  * What a write has to know about the regular file at `path` before replacing
  * it: the permission bits to carry over, and how many names share its inode.
@@ -195,47 +343,6 @@ async function replacedFile(path: string): Promise<ReplacedFile | undefined> {
    }
 }
 
-/**
- * Errno values a rename reports on Windows when another handle holds the
- * destination open. POSIX renames are unaffected by open handles, so this
- * cannot fire there and the retry below costs nothing.
- */
-const RENAME_CONTENTION_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
-
-/**
- * `rename` the staged content over `destination`, retrying while Windows
- * reports the destination as held open.
- *
- * The staging file exists so a reader never sees a half-written file, and on
- * Windows the very presence of that reader is what makes the replacing rename
- * fail — so the indivisible write breaks under exactly the contention it was
- * built for, and it breaks intermittently, which is worse than never working.
- * A reader's handle is released in milliseconds, so waiting turns a spurious
- * failure into a slightly later success.
- *
- * BOUNDED, not open-ended: a genuine permission fault raises the same errno and
- * is distinguishable from contention only by never clearing, so an unbounded
- * wait would convert a hard error into a hang. Exhausting the budget rethrows
- * the last failure, leaving the caller's cleanup and error contract unchanged.
- */
-async function renameOverOpenReaders(staging: string, destination: string): Promise<void> {
-   const deadline = Date.now() + 2_000;
-   for (let attempt = 0; ; attempt++) {
-      try {
-         await fsp.rename(staging, destination);
-         return;
-      } catch (err: unknown) {
-         const code = err instanceof Error && 'code' in err ? String((err as NodeJS.ErrnoException).code) : undefined;
-         if (code === undefined || !RENAME_CONTENTION_CODES.has(code) || Date.now() >= deadline) {
-            throw err;
-         }
-         // Backs off to keep a long contention window from spinning, capped so
-         // a late attempt still lands promptly once the handle is released.
-         await new Promise(resolve => setTimeout(resolve, Math.min(2 ** attempt, 50)));
-      }
-   }
-}
-
 /**
  * Module fragment that binds the writable Node {@link DefaultFileSystemProvider},
  * spread into the services context on a Node host.

package/src/node/profile-capture.ts

@@ -147,8 +147,14 @@ export function formatProfileReport(report: ProfileReport, label = 'Profile repo
    return lines.join('\n');
 }
 
-/** Minimal structural view of a `node:inspector` `Session` — its typed per-method overloads can't be called generically. */
-interface InspectorSessionLike {
+/**
+ * Minimal structural view of a `node:inspector` `Session` — its typed per-method
+ * overloads can't be called generically.
+ *
+ * Held by the `protected` {@link ProfileCapture.session}, so a subclass reaching
+ * the inspector names this rather than `Session`.
+ */
+export interface InspectorSessionLike {
    connect(): void;
    disconnect(): void;
    post(method: string, params: Record<string, unknown>, callback: (error: Error | null, result?: unknown) => void): void;