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

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

@@ -8,29 +8,38 @@
  ********************************************************************************/
 
 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 { type WritableFileSystemProvider } from '../langium/workspace/file-system-provider.js';
+import { type SelfSaveRegistry } from '../langium/workspace/self-save-registry.js';
+import { RENAME_GAP_BUDGET_MS, 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';
 
 /**
  * Node-based default {@link WritableFileSystemProvider}. Extends Langium's
  * {@link NodeFileSystemProvider} with an async {@link writeFile} that
- * creates parent directories on demand, replaces the target indivisibly unless
+ * creates parent directories on demand, replaces the target whole unless
  * that would break a hard link, and registers the resulting mtime with the
  * {@link SelfSaveRegistry} bound at `services.workspace.SelfSaveRegistry` — so
  * consumers can suppress the `didChangeWatchedFiles` echo for their own writes.
  *
+ * Its read surface 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. Behind the framework's
+ * `FileSystemProviderRegistry`, a `virtual:` URI goes to the framework's own
+ * provider for that scheme, not here.
+ *
  * 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
- * get real disk I/O.
+ * entry falls back to `DefaultEmptyFileSystemProvider`, so a Node host passes
+ * this one through `context.fileSystemProvider` (see {@link NodeFileSystem})
+ * to get real disk I/O.
  */
 export class DefaultFileSystemProvider extends NodeFileSystemProvider implements WritableFileSystemProvider {
    readonly selfSaveRegistry: SelfSaveRegistry;
@@ -45,15 +54,109 @@ 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 answers from disk for a path this provider can reach, and
+   // otherwise with the filesystem's own "nothing here" — 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);
+      return this.servesFromDisk(uri) ? super.readFile(uri) : Promise.reject(noSuchFile(uri));
    }
 
    override readFileSync(uri: URI): string {
-      return serveVirtualDocument(this.services, uri) ?? super.readFileSync(uri);
+      if (!this.servesFromDisk(uri)) {
+         throw noSuchFile(uri);
+      }
+      return super.readFileSync(uri);
+   }
+
+   override readBinary(uri: URI): Promise<Uint8Array> {
+      return this.servesFromDisk(uri) ? super.readBinary(uri) : Promise.reject(noSuchFile(uri));
+   }
+
+   override readBinarySync(uri: URI): Uint8Array {
+      if (!this.servesFromDisk(uri)) {
+         throw noSuchFile(uri);
+      }
+      return super.readBinarySync(uri);
+   }
+
+   override stat(uri: URI): Promise<FileSystemNode> {
+      return this.servesFromDisk(uri) ? super.stat(uri) : Promise.reject(noSuchPath(uri));
+   }
+
+   override statSync(uri: URI): FileSystemNode {
+      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> {
+      return this.servesFromDisk(uri) ? super.exists(uri) : false;
+   }
+
+   override existsSync(uri: URI): boolean {
+      return this.servesFromDisk(uri) ? super.existsSync(uri) : false;
+   }
+
+   /**
+    * On Windows a miss is polled for up to {@link RENAME_GAP_BUDGET_MS}, since a
+    * replacing rename there can hide the name from a reader for a while; it
+    * answers `true` as soon as the file is back. Elsewhere a miss is final.
+    */
+   async existsSettled(uri: URI): Promise<boolean> {
+      if (await this.exists(uri)) {
+         return true;
+      }
+      if (!this.servesFromDisk(uri) || process.platform !== 'win32') {
+         return false;
+      }
+      // A stopwatch, not two `now()` readings: a wall-clock jump would end the
+      // wait early, removing a file that is only being replaced.
+      const waited = this.services.Clock.stopwatch();
+      while (waited.elapsedMs < RENAME_GAP_BUDGET_MS) {
+         // Not `clock.setTimer`: it unrefs its timer, so a process with only
+         // this check pending could exit mid-wait.
+         await new Promise(resolve => setTimeout(resolve, 10));
+         if (await this.exists(uri)) {
+            return true;
+         }
+      }
+      return 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) : [];
    }
 
    /**
@@ -66,8 +169,12 @@ export class DefaultFileSystemProvider extends NodeFileSystemProvider implements
     * overwrite cannot offer that, because the target is truncated before the
     * first byte lands, so a reader in that window gets a short or empty file —
     * and a model file that fails to parse is worse than one holding a previous
-    * good revision. It does NOT serialise writers: two writers still race, and
-    * the loser's content is replaced wholesale rather than interleaved.
+    * good revision. On Windows the replacing rename also leaves the name
+    * unresolvable for a moment, so a reader there can find the file missing
+    * (`ENOENT`) or refused (`EPERM`), never torn, and must not take either for
+    * a deletion; {@link existsSettled} waits that moment out. It does NOT
+    * serialise writers: two writers still race, and the loser's content is
+    * replaced wholesale rather than interleaved.
     *
     * The destination is the RESOLVED path, via {@link realpath}: a `rename`
     * onto a symlink replaces the link itself with a regular file and leaves the
@@ -103,6 +210,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 +253,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 +295,21 @@ 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() }));
+}
+
 /**
  * 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 +337,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

@@ -17,18 +17,11 @@
  * `ProfileSession` (aggregate self-time spans).
  */
 
-import { Format, type ProfileCaptureOptions } from '@hydranium/protocol';
+import { type Clock, Format, type ProfileCaptureOptions, type Stopwatch, SystemClock } from '@hydranium/protocol';
 import * as fs from 'node:fs';
 import { Session } from 'node:inspector';
-import {
-   constants,
-   monitorEventLoopDelay,
-   PerformanceObserver,
-   performance,
-   type IntervalHistogram,
-   type PerformanceEntry
-} from 'node:perf_hooks';
-import { snapshotFilePath, writeHeapSnapshotToDir } from './process-memory.js';
+import { constants, monitorEventLoopDelay, PerformanceObserver, type IntervalHistogram, type PerformanceEntry } from 'node:perf_hooks';
+import { snapshotFilePath, writeHeapSnapshotToDir } from '@hydranium/protocol/node';
 
 export const DEFAULT_CPU_INTERVAL_MICROS = 1000;
 export const DEFAULT_ALLOCATION_INTERVAL_BYTES = 32768;
@@ -147,8 +140,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;
@@ -175,7 +174,9 @@ let active: ProfileCapture | undefined;
  * session at a time); prefer {@link profileWorkload} for the common wrap-a-block case.
  */
 export class ProfileCapture {
-   protected startedAt = 0;
+   /** Times the window: real time, since what it frames is real CPU and memory. */
+   protected readonly clock: Clock = new SystemClock();
+   protected sinceStart: Stopwatch = this.clock.stopwatch();
    protected startCpu: NodeJS.CpuUsage = { user: 0, system: 0 };
    protected startMem: NodeJS.MemoryUsage = process.memoryUsage();
    protected session?: InspectorSessionLike;
@@ -208,7 +209,7 @@ export class ProfileCapture {
    }
 
    protected async begin(): Promise<void> {
-      this.startedAt = performance.now();
+      this.sinceStart = this.clock.stopwatch();
       this.startCpu = process.cpuUsage();
       this.startMem = process.memoryUsage();
       if (this.options.cpu || this.options.allocation) {
@@ -248,7 +249,7 @@ export class ProfileCapture {
       if (active !== this) {
          throw new Error('ProfileCapture.stop called on an inactive capture.');
       }
-      const durationMs = performance.now() - this.startedAt;
+      const durationMs = this.sinceStart.elapsedMs;
       // Sample cpu + memory at the workload boundary (alongside durationMs), NOT
       // after teardown: the synchronous profile write inflates RSS and the heap
       // snapshot forces a full GC, so a post-teardown read would fold the

package/src/node/profiling-run.ts

@@ -19,7 +19,11 @@
 
 import {
    DEFAULT_LOG_FILE_ENV,
+   DEFAULT_LOG_FILE_LEVEL_ENV,
+   DEFAULT_LOG_LEVEL_ENV,
+   parseLogLevel,
    PROFILING_SCHEMA_VERSION,
+   type LogThreshold,
    type LatencyCollector,
    type ProfilingArtifact,
    type ProfilingArtifactKind,
@@ -55,10 +59,26 @@ export interface ProfilingRunOptions {
    /**
     * Optional latency collector. When present, {@link ProfilingRun.finish} writes
     * its report to `server-latency.json` and records a `server-latency` manifest artefact. A
-    * head feeds it via the RPC binding / `instrumentLspConnection`; a pure
-    * headless build with no request traffic leaves it empty.
+    * head feeds it via the RPC binding / `lspLatencyOptions`; a pure headless
+    * build with no request traffic leaves it empty.
     */
    latency?: LatencyCollector;
+   /**
+    * Threshold `server.log` is written at. Defaults to `HYDRANIUM_LOG_FILE_LEVEL`,
+    * then `HYDRANIUM_LOG_LEVEL`, then `'info'`, read at {@link ProfilingRun.start}
+    * and held for the run, so a log-level setting arriving mid-run leaves the log
+    * alone. Above `'info'` the framework's own debug profile sessions run inside
+    * the captured windows and show up in the profiles.
+    */
+   logFileLevel?: LogThreshold;
+}
+
+function restoreEnv(name: string, value: string | undefined): void {
+   if (value === undefined) {
+      delete process.env[name];
+   } else {
+      process.env[name] = value;
+   }
 }
 
 /** A cgroup memory controller signals we are inside a container/pod. */
@@ -80,6 +100,8 @@ export class ProfilingRun {
    protected finished = false;
    /** The `HYDRANIUM_LOG_FILE` value seen before this run pointed it at the session (restored on {@link finish}). */
    protected readonly previousLogFileEnv?: string;
+   /** The `HYDRANIUM_LOG_FILE_LEVEL` value seen before this run set it (restored on {@link finish}). */
+   protected readonly previousLogFileLevelEnv?: string;
    /** Absolute path of the session's teed server log. */
    readonly serverLogPath: string;
 
@@ -97,10 +119,13 @@ export class ProfilingRun {
       // `HYDRANIUM_LOG_FILE` env, which every `@hydranium/core` copy reads when
       // its logger is CONSTRUCTED — so `ProfilingRun.start` must run before the
       // head's services are created (as `measureModelMemory` does). This is the
-      // only mechanism that crosses a yalc'd adopter's separate core copy; a
+      // only mechanism that crosses an adopter's separate core copy; a
       // process-local `setLogFilePath` would only reach this module's own copy.
       this.previousLogFileEnv = process.env[DEFAULT_LOG_FILE_ENV];
       process.env[DEFAULT_LOG_FILE_ENV] = this.serverLogPath;
+      this.previousLogFileLevelEnv = process.env[DEFAULT_LOG_FILE_LEVEL_ENV];
+      process.env[DEFAULT_LOG_FILE_LEVEL_ENV] =
+         options.logFileLevel ?? parseLogLevel(this.previousLogFileLevelEnv) ?? parseLogLevel(process.env[DEFAULT_LOG_LEVEL_ENV]) ?? 'info';
    }
 
    static async start(options: ProfilingRunOptions = {}): Promise<ProfilingRun> {
@@ -179,11 +204,8 @@ export class ProfilingRun {
       this.finished = true;
       // Restore the prior log-file env, then record the log as an artefact only
       // if the run actually produced one.
-      if (this.previousLogFileEnv === undefined) {
-         delete process.env[DEFAULT_LOG_FILE_ENV];
-      } else {
-         process.env[DEFAULT_LOG_FILE_ENV] = this.previousLogFileEnv;
-      }
+      restoreEnv(DEFAULT_LOG_FILE_ENV, this.previousLogFileEnv);
+      restoreEnv(DEFAULT_LOG_FILE_LEVEL_ENV, this.previousLogFileLevelEnv);
       if (fs.existsSync(this.serverLogPath)) {
          this.artifacts.push({ kind: 'server-log', path: 'server.log' });
       }

package/src/node/rename-over-open-readers.ts

@@ -0,0 +1,94 @@
+/********************************************************************************
+ * 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 Clock, SystemClock } from '@hydranium/protocol';
+import * as fsp from 'node:fs/promises';
+
+/**
+ * Errnos Windows raises when a replacing `rename` meets a handle already on the
+ * destination open. POSIX renames are unaffected by open handles, so these
+ * cannot fire there and the retry below costs nothing.
+ */
+export const RENAME_CONTENTION_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+/**
+ * How long a replacing rename may keep retrying before it gives up.
+ *
+ * BOUNDED, not open-ended: a genuine permission fault raises the same errno as
+ * contention and is distinguishable from it only by never clearing, so an
+ * unbounded wait would convert a hard error into a hang.
+ *
+ * The figure is a judgement, not a measurement, and the honest bound on it is
+ * that the previous 2s was observed EXHAUSTED on a loaded Windows CI runner
+ * while no upper bound has been established. What would settle it is recording
+ * how long a real contended rename takes to clear. graceful-fs tolerates 60s
+ * for Windows rename contention, but that is weaker support than it looks: it
+ * retries only where the destination has GONE, which is the opposite of
+ * replacing one a reader holds open.
+ */
+export const RENAME_BUDGET_MS = 10_000;
+
+/**
+ * How long a miss is waited out on Windows before it counts as an absence,
+ * since a replacing rename there can hide the name from a reader for a while.
+ * Bounded: a real deletion differs only by never ending, so it pays the whole
+ * budget. The figure is a judgement, not an established bound.
+ */
+export const RENAME_GAP_BUDGET_MS = 2_000;
+
+/** Seams for the test, which cannot make a real rename fail on demand. */
+export interface RenameOverOpenReadersOptions {
+   readonly rename?: (from: string, to: string) => Promise<void>;
+   readonly budgetMs?: number;
+   readonly clock?: Clock;
+}
+
+/**
+ * `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.
+ *
+ * Exhausting the budget rethrows the last failure, leaving the caller's cleanup
+ * and error contract unchanged. An errno OUTSIDE the contention set is rethrown
+ * without waiting at all: retrying a fault that will not clear only delays it.
+ */
+export async function renameOverOpenReaders(
+   staging: string,
+   destination: string,
+   options: RenameOverOpenReadersOptions = {}
+): Promise<void> {
+   const rename = options.rename ?? fsp.rename;
+   const clock = options.clock ?? new SystemClock();
+   const budgetMs = options.budgetMs ?? RENAME_BUDGET_MS;
+   // A stopwatch, not two `now()` readings: a wall-clock jump would end the
+   // budget early or stretch it.
+   const waited = clock.stopwatch();
+   for (let attempt = 0; ; attempt++) {
+      try {
+         await 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) || waited.elapsedMs >= budgetMs) {
+            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.
+         // Not `clock.setTimer`: it unrefs its timer, so a process with only
+         // this write pending could exit mid-backoff.
+         await new Promise(resolve => setTimeout(resolve, Math.min(2 ** attempt, 50)));
+      }
+   }
+}

package/src/node/server-diagnostics.ts

@@ -49,7 +49,7 @@ export function startServerDiagnostics(shared: ServerSharedServicesMinimal, opti
       productName,
       version,
       phaseDetailThresholdMs,
-      ...nodeLogPreambleSections(phaseDetailThresholdMs)
+      ...nodeLogPreambleSections(phaseDetailThresholdMs, options)
    });
    if (options.logInitialMemory ?? true) {
       shared.Tracer.for('Process').memory('Initial Memory');

package/src/node/server-state-snapshot.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Format } from '@hydranium/protocol';
+import { Format, type Stopwatch, SystemClock } from '@hydranium/protocol';
 import { DocumentState, type LangiumDocuments } from '@hydranium/langium';
 import { isCstShed } from '../langium/residency/cst-residency-service.js';
 import { performance } from 'node:perf_hooks';
@@ -15,7 +15,7 @@ import * as v8 from 'node:v8';
 
 /** Cumulative samples kept across calls so each snapshot can report deltas. */
 interface DeltaState {
-   atMs: number;
+   sinceSample: Stopwatch;
    cpu: NodeJS.CpuUsage;
    elu: { idle: number; active: number };
 }
@@ -62,7 +62,7 @@ export interface ServerStateSnapshotOptions {
  * requested via `options` ({@link ServerStateSnapshotOptions}).
  */
 export function formatServerState(documents?: LangiumDocuments, label?: string, options?: ServerStateSnapshotOptions): string {
-   const now = performance.now();
+   const sinceSample = new SystemClock().stopwatch();
    const mem = process.memoryUsage();
    const heap = v8.getHeapStatistics();
    const cpu = process.cpuUsage();
@@ -87,7 +87,7 @@ export function formatServerState(documents?: LangiumDocuments, label?: string,
          `native contexts ${heap.number_of_native_contexts}, detached contexts ${heap.number_of_detached_contexts}`
    );
    if (lastSample) {
-      const wallMs = now - lastSample.atMs;
+      const wallMs = lastSample.sinceSample.elapsedMs;
       const userMs = (cpu.user - lastSample.cpu.user) / 1000;
       const systemMs = (cpu.system - lastSample.cpu.system) / 1000;
       const cpuPct = wallMs > 0 ? Math.round(((userMs + systemMs) / wallMs) * 100) : 0;
@@ -138,7 +138,7 @@ export function formatServerState(documents?: LangiumDocuments, label?: string,
       }
    }
 
-   lastSample = { atMs: now, cpu, elu };
+   lastSample = { sinceSample, cpu, elu };
    return lines.join('\n');
 }