@hydranium/core 1.0.0-next.266 → 1.0.0-next.268

package/src/launcher/integrated-server.ts

@@ -20,7 +20,9 @@
  *   primarily by tests waiting for tidy teardown.
  *
  * Either promise may reject if startup or shutdown encounters an error
- * the head can't recover from.
+ * the head can't recover from. A launcher given a logger logs its own startup
+ * failure, so a rejected `started` is control flow: the caller stops what
+ * depends on it without logging the failure again.
  */
 export interface IntegratedServer {
    readonly started: Promise<void>;

package/src/lsp/hydranium-document-update-handler.ts

@@ -7,7 +7,15 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Debouncer, Deferred, type Logger, ObservableValue, type MaybeObservableValue, TIMED_OUT } from '@hydranium/protocol';
+import {
+   Debouncer,
+   Deferred,
+   type Logger,
+   ObservableValue,
+   type MaybeObservableValue,
+   TIMED_OUT,
+   describeErrorWithStack
+} from '@hydranium/protocol';
 import { URI, UriUtils } from '@hydranium/langium';
 import { DefaultDocumentUpdateHandler } from '@hydranium/langium/lsp';
 import { HYDRANIUM_BUILD_REASONS, type HydraniumDocumentBuilder } from '../langium/document-builder/document-builder.js';
@@ -221,7 +229,9 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             for (const change of filtered.changes) {
                this.textDocuments
                   .reloadDiskBaseline(change.uri)
-                  .catch((err: unknown) => this.logger.error(`Disk baseline not reloaded for ${change.uri}. ${String(err)}`));
+                  .catch((err: unknown) =>
+                     this.logger.error(`Disk baseline not reloaded for ${change.uri}. ${describeErrorWithStack(err)}`)
+                  );
             }
             // External file-system changes are authoritative — overwrite any
             // pending reason (typically empty here; could be `didChangeContent`
@@ -238,7 +248,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             // `unhandledRejection` listener, which reports neither the URIs nor
             // the fact that a watched-file rebuild was dropped — leaving the
             // workspace diverged from disk with no diagnostic and no retry.
-            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            const detail = describeErrorWithStack(err);
             const uris = params.changes.map(change => change.uri).join(', ');
             this.logger.error(`Watched-file update dropped for ${uris}. ${detail}`);
          });
@@ -293,9 +303,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             });
          } catch (err) {
             cap.dispose();
-            this.logger.error(
-               `willSaveWaitUntil for ${uri} answered without waiting. ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`
-            );
+            this.logger.error(`willSaveWaitUntil for ${uri} answered without waiting. ${describeErrorWithStack(err)}`);
             release();
             resolve([]);
          }
@@ -417,7 +425,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             if (isConnectionGoneError(err)) {
                return;
             }
-            const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            const detail = describeErrorWithStack(err);
             this.logger.error(`Workspace initialization failed. Could not perform document update. ${detail}`);
          });
    }

package/src/node/event-loop-monitor.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { monitorEventLoopDelay } from 'node:perf_hooks';
+import { describeErrorWithStack } from '@hydranium/protocol';
 import { formatMemory } from '../langium/diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
 import { formatServerState } from './server-state-snapshot.js';
@@ -74,7 +75,7 @@ export function startEventLoopMonitor(shared: ServerSharedServicesMinimal, optio
             try {
                onStallSnapshot(maxMs);
             } catch (error) {
-               logger.warn(`Stall snapshot failed: ${error instanceof Error ? error.message : String(error)}`);
+               logger.warn(`Stall snapshot failed: ${describeErrorWithStack(error)}`);
             }
          }
       }

package/src/node/log-preamble-node.ts

@@ -17,6 +17,7 @@ import {
 } from './event-loop-monitor.js';
 import { MEMORY_DELTA_BYTES } from '../langium/diagnostics/logger.js';
 import { DEFAULT_MEMORY_CRITICAL_THRESHOLD, DEFAULT_MEMORY_WARN_THRESHOLD } from './memory-monitor.js';
+import { type ServerDiagnosticsOptions } from './server-diagnostics.js';
 import { type LogPreambleOptions } from '../langium/diagnostics/log-preamble.js';
 
 /**
@@ -37,19 +38,25 @@ export function nodeSystemInfoLines(): string[] {
  * Node monitor + memory-suffix convention lines for
  * {@link LogPreambleOptions.conventionLines}. These describe the `[EventLoop]`
  * / `[Memory]` monitors and the heap/rss suffix — all Node-only behaviour, so
- * they're omitted from the portable preamble.
+ * they're omitted from the portable preamble. Pass the options the monitors
+ * were started with, or the lines state the defaults.
  */
-export function nodeConventionLines(phaseDetailThresholdMs = 50): string[] {
+export function nodeConventionLines(
+   phaseDetailThresholdMs = 50,
+   monitors: Pick<ServerDiagnosticsOptions, 'eventLoop' | 'memory'> = {}
+): string[] {
    const memoryDeltaMb = MEMORY_DELTA_BYTES / (1024 * 1024);
-   const intervalSeconds = DEFAULT_EVENT_LOOP_INTERVAL_MS / 1000;
-   const warnPercent = Math.round(DEFAULT_MEMORY_WARN_THRESHOLD * 100);
-   const criticalPercent = Math.round(DEFAULT_MEMORY_CRITICAL_THRESHOLD * 100);
+   const thresholdMs = monitors.eventLoop?.thresholdMs ?? DEFAULT_EVENT_LOOP_THRESHOLD_MS;
+   const intervalSeconds = (monitors.eventLoop?.intervalMs ?? DEFAULT_EVENT_LOOP_INTERVAL_MS) / 1000;
+   const snapshotAboveMs = monitors.eventLoop?.snapshotAboveMs ?? DEFAULT_EVENT_LOOP_SNAPSHOT_ABOVE_MS;
+   const warnPercent = Math.round((monitors.memory?.warnThreshold ?? DEFAULT_MEMORY_WARN_THRESHOLD) * 100);
+   const criticalPercent = Math.round((monitors.memory?.criticalThreshold ?? DEFAULT_MEMORY_CRITICAL_THRESHOLD) * 100);
    return [
       `• Memory suffix:  heap/rss included on [done] only when heap moved >${memoryDeltaMb}MB since last log,`,
       `                  always included on rebuilds >=${phaseDetailThresholdMs}ms and on [EventLoop] stall warnings`,
-      `• [EventLoop]:    warns when a stall >=${DEFAULT_EVENT_LOOP_THRESHOLD_MS}ms is observed within a ${intervalSeconds}s window;`,
-      `                  stalls >=${DEFAULT_EVENT_LOOP_SNAPSHOT_ABOVE_MS}ms also trigger a [Process] server-state snapshot`,
-      `• [Memory]:       warns >=${warnPercent}% of V8 heap_size_limit, errors >=${criticalPercent}%, info on recovery`
+      `• [EventLoop]:    warns when a stall >=${thresholdMs}ms is observed within a ${intervalSeconds}s window;`,
+      `                  stalls >=${snapshotAboveMs}ms also trigger a [Process] server-state snapshot`,
+      `• [Memory]:       warns >=${warnPercent}% of V8 heap_size_limit, again as imminent OOM >=${criticalPercent}%, info on recovery`
    ];
 }
 
@@ -58,6 +65,9 @@ export function nodeConventionLines(phaseDetailThresholdMs = 50): string[] {
  * the portable `logPreamble`'s options on a Node host:
  * `logPreamble(logger, { productName, version, ...nodeLogPreambleSections() })`.
  */
-export function nodeLogPreambleSections(phaseDetailThresholdMs = 50): Pick<LogPreambleOptions, 'systemInfoLines' | 'conventionLines'> {
-   return { systemInfoLines: nodeSystemInfoLines(), conventionLines: nodeConventionLines(phaseDetailThresholdMs) };
+export function nodeLogPreambleSections(
+   phaseDetailThresholdMs = 50,
+   monitors: Pick<ServerDiagnosticsOptions, 'eventLoop' | 'memory'> = {}
+): Pick<LogPreambleOptions, 'systemInfoLines' | 'conventionLines'> {
+   return { systemInfoLines: nodeSystemInfoLines(), conventionLines: nodeConventionLines(phaseDetailThresholdMs, monitors) };
 }

package/src/node/memory-monitor.ts

@@ -13,7 +13,7 @@ import { type ServerSharedServicesMinimal } from '../langium/shared-services.js'
 
 /** Heap usage ratio (heapUsed / heap_size_limit) above which we emit a warning. */
 export const DEFAULT_MEMORY_WARN_THRESHOLD = 0.85;
-/** Heap usage ratio above which we emit an error-level warning (imminent OOM likely). */
+/** Heap usage ratio above which the warning says out-of-memory is imminent. */
 export const DEFAULT_MEMORY_CRITICAL_THRESHOLD = 0.95;
 /** Cooldown between repeated warnings at the same level, in ms. */
 export const DEFAULT_COOLDOWN_MS = 30_000;
@@ -25,7 +25,7 @@ type Severity = 'ok' | 'warn' | 'critical';
 export interface MemoryMonitorOptions {
    /** Heap-usage ratio (0..1) above which a warning is emitted. Default {@link DEFAULT_MEMORY_WARN_THRESHOLD}. */
    warnThreshold?: number;
-   /** Heap-usage ratio above which an error is emitted (imminent OOM likely). Default {@link DEFAULT_MEMORY_CRITICAL_THRESHOLD}. */
+   /** Heap-usage ratio above which the warning says out-of-memory is imminent. Default {@link DEFAULT_MEMORY_CRITICAL_THRESHOLD}. */
    criticalThreshold?: number;
    /** Sample interval, in ms. Default {@link DEFAULT_MEMORY_INTERVAL_MS}. */
    intervalMs?: number;
@@ -86,9 +86,8 @@ export function startMemoryMonitor(shared: ServerSharedServicesMinimal, options:
             : severity === 'warn'
               ? ' - garbage collection pressure may slow operations'
               : ' - recovered below warning threshold');
-      if (severity === 'critical') {
-         logger.error(message);
-      } else if (severity === 'warn') {
+      // Critical is still a warning: nothing has failed yet.
+      if (severity !== 'ok') {
          logger.warn(message);
       } else {
          logger.info(message);

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

@@ -23,7 +23,7 @@ import { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_WRITE } from '../langium/worksp
 /**
  * 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.
@@ -143,7 +143,10 @@ 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
+    * 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. 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`

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/socket-launcher.ts

@@ -8,7 +8,7 @@
  ********************************************************************************/
 
 import * as net from 'node:net';
-import { Deferred, type Disposable, type Logger } from '@hydranium/protocol';
+import { Deferred, describeErrorWithStack, type Disposable, type Logger } from '@hydranium/protocol';
 import { createMessageConnection, SocketMessageReader, SocketMessageWriter } from 'vscode-jsonrpc/node';
 import type { MessageConnection } from 'vscode-jsonrpc';
 import type { IntegratedServer } from '../launcher/integrated-server.js';
@@ -131,7 +131,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
          try {
             adopterDisposable.dispose();
          } catch (err) {
-            logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${(err as Error)?.message ?? err}`);
+            logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${describeErrorWithStack(err)}`);
          }
          connection.dispose();
          const idx = activeConnections.indexOf(entry);
@@ -164,7 +164,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
       started.resolve();
    });
    netServer.on('error', err => {
-      logger?.error(`[${tag}] Error: ${err.message}`);
+      logger?.error(`[${tag}] Error: ${describeErrorWithStack(err)}`);
       started.reject(err);
    });
    netServer.on('close', () => {
@@ -174,7 +174,7 @@ export function startSocketServer(options: SocketServerOptions, onClientConnecti
          try {
             entry.adopterDisposable.dispose();
          } catch (err) {
-            logger?.warn(`[${tag}] Adopter disposable threw on shutdown: ${(err as Error)?.message ?? err}`);
+            logger?.warn(`[${tag}] Adopter disposable threw on shutdown: ${describeErrorWithStack(err)}`);
          }
          entry.connection.dispose();
       }

package/src/node/stdio-launcher.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred, type Disposable, type Logger } from '@hydranium/protocol';
+import { Deferred, type Disposable, type Logger, describeError, describeErrorWithStack } from '@hydranium/protocol';
 import type { MessageConnection } from 'vscode-jsonrpc';
 import { createMessageConnection, StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node';
 import type { IntegratedServer } from '../launcher/integrated-server.js';
@@ -115,17 +115,21 @@ export function startStdioServer(
       try {
          adopterDisposable.dispose();
       } catch (err: unknown) {
-         logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${err instanceof Error ? err.message : String(err)}`);
+         logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${describeErrorWithStack(err)}`);
       }
       connection.dispose();
       stopped.resolve();
    };
    connection.onClose(() => close());
 
+   // The workspace manager logs a failed initialization itself.
+   let initializing = false;
    const begin = async (): Promise<void> => {
       if (options.workspace !== undefined) {
          logger?.info(`[${tag}] Initializing workspace`);
+         initializing = true;
          await initializeWorkspaceProgrammatically(options.shared, options.workspace);
+         initializing = false;
       }
       // Only now attach the reader — see the ordering note in the doc above.
       connection.listen();
@@ -138,7 +142,11 @@ export function startStdioServer(
          // A failed startup must not leave a half-live head: report it on
          // `started` and tear the connection down rather than listening over an
          // uninitialized workspace.
-         logger?.error(`[${tag}] Startup failed: ${err instanceof Error ? err.message : String(err)}`);
+         if (initializing) {
+            logger?.debug(`[${tag}] Startup failed: the workspace did not initialize. ${describeError(err)}`);
+         } else {
+            logger?.error(`[${tag}] Startup failed: ${describeErrorWithStack(err)}`);
+         }
          started.reject(err);
          close();
       }

package/src/testing/playwright/server-log-capture.ts

@@ -415,6 +415,20 @@ export function forwardBrowserConsole(
    });
 }
 
+/** The label a `Warn` or `Error` entry starts with; continuation lines of a stack never do. */
+const WARN_OR_ERROR_LINE = /^\[(Warn|Error)\s*-/;
+
+/**
+ * The `Warn` and `Error` lines of `text` that no pattern of `allowlist`
+ * matches; its keys are the reasons the lines are expected. A clean run logs
+ * neither: `warn` is an anomaly that was handled and `error` is work that
+ * failed, so either one in a passing spec is a defect or a missing allowance.
+ */
+export function findUnexpectedServerLogLines(text: string, allowlist: Readonly<Record<string, RegExp>> = {}): string[] {
+   const patterns = Object.values(allowlist);
+   return text.split('\n').filter(line => WARN_OR_ERROR_LINE.test(line) && !patterns.some(pattern => pattern.test(line)));
+}
+
 /**
  * Per-test server-log capture, called from a spec's `afterEach` with the test's
  * workspace path:

package/src/testing/playwright/server-log-fixture.ts

@@ -11,7 +11,14 @@
 // The plain functions in `server-log-capture.ts` stay playwright-free; only
 // adopters that use this fixture need `@playwright/test` installed.
 import { test as base, type Fixtures, type PlaywrightTestArgs, type PlaywrightTestOptions } from '@playwright/test';
-import { attachServerLog, markServerLog } from './server-log-capture.js';
+import {
+   attachServerLog,
+   DEFAULT_SERVER_LOG_ATTACH_ENV,
+   findUnexpectedServerLogLines,
+   markServerLog,
+   resolveServerLogPath
+} from './server-log-capture.js';
+import { readServerLogRegion } from './server-log-region.js';
 
 export interface ServerLogFixtures {
    /**
@@ -22,6 +29,21 @@ export interface ServerLogFixtures {
     * `attachServerLog` in `beforeEach` / `afterEach` instead.
     */
    serverLogWorkspace: string;
+   /**
+    * Fail a test whose part of the server log holds a `Warn` or `Error` line
+    * that {@link serverLogAllowlist} does not match. Off by default; reads
+    * nothing when capture is off.
+    */
+   serverLogClean: boolean;
+   /**
+    * The `Warn` and `Error` lines {@link serverLogClean} lets through: each key
+    * is why the line is expected, and its pattern is matched against the whole
+    * line, label and timestamp included. A pattern takes neither the `g` nor
+    * the `y` flag, which make `test` resume from its last match. An object
+    * rather than a list, because Playwright reads an array whose second entry
+    * is an object as a fixture's `[value, options]`.
+    */
+   serverLogAllowlist: Readonly<Record<string, RegExp>>;
 }
 
 /** Full fixture set including the internal side-effect-only auto fixture. */
@@ -36,17 +58,35 @@ interface ServerLogTestFixtures extends ServerLogFixtures {
  * (teardown) — i.e. the `beforeEach` + `afterEach` pair fused into one auto
  * fixture. Compose onto any test base, or use the pre-extended {@link test}.
  * Override `serverLogWorkspace` to wire the workspace; otherwise it's inert.
+ * Set `serverLogClean` to also fail a test on an unexpected `Warn` or `Error`.
  */
 export const serverLogFixtures: Fixtures<ServerLogTestFixtures, object, PlaywrightTestArgs & PlaywrightTestOptions> = {
    serverLogWorkspace: ['', { option: true }],
+   serverLogClean: [false, { option: true }],
+   serverLogAllowlist: [{}, { option: true }],
    serverLogCapture: [
-      async ({ serverLogWorkspace }, use): Promise<void> => {
-         if (serverLogWorkspace) {
-            markServerLog(base.info(), serverLogWorkspace);
+      async ({ serverLogWorkspace, serverLogClean, serverLogAllowlist }, use): Promise<void> => {
+         if (!serverLogWorkspace) {
+            await use(undefined);
+            return;
          }
+         markServerLog(base.info(), serverLogWorkspace);
          await use(undefined);
-         if (serverLogWorkspace) {
-            await attachServerLog(base.info(), serverLogWorkspace);
+         const file = resolveServerLogPath(serverLogWorkspace);
+         const region = file ? readServerLogRegion(file) : '';
+         let problem: string | undefined;
+         if (serverLogClean) {
+            const unexpected = findUnexpectedServerLogLines(region, serverLogAllowlist);
+            if (unexpected.length > 0) {
+               problem = `The server logged ${unexpected.length} unexpected Warn or Error line(s):\n${unexpected.join('\n')}`;
+            }
+         }
+         // The failure-only policy reads the test's status, which failing here
+         // does not change; a run set to attach nothing still attaches nothing.
+         const attachOn = process.env[DEFAULT_SERVER_LOG_ATTACH_ENV] === 'never' ? 'never' : 'always';
+         await attachServerLog(base.info(), serverLogWorkspace, problem ? { attachOn } : {});
+         if (problem) {
+            throw new Error(problem);
          }
       },
       { auto: true }

package/src/testing/playwright/server-log-region.ts

@@ -0,0 +1,32 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { existsSync, readFileSync } from 'node:fs';
+
+/**
+ * How far each log has been read. A suite starts its app before its first
+ * test's marker, so reading from the marker would leave startup unread.
+ */
+const readUpTo = new Map<string, number>();
+
+/**
+ * The part of `file` written since the last read of it, up to its last complete
+ * line, since the server may be mid-write. Every test reads, checked or not, so
+ * a test that is not checked leaves no lines to the next one.
+ */
+export function readServerLogRegion(file: string): string {
+   if (!existsSync(file)) {
+      return '';
+   }
+   const log = readFileSync(file);
+   const end = log.lastIndexOf('\n') + 1;
+   const text = log.subarray(readUpTo.get(file) ?? 0, end).toString('utf-8');
+   readUpTo.set(file, end);
+   return text;
+}

package/src/util/connection-liveness.ts

@@ -7,6 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { describeError } from '@hydranium/protocol';
+
 /**
  * Phrases that mean a call lost its connection. Matched on the message because
  * the condition surfaces in shapes that share no discriminator:
@@ -64,7 +66,7 @@ export function isConnectionGoneError(err: unknown): boolean {
    if (isDestroyedStreamError(err)) {
       return true;
    }
-   const message = err instanceof Error ? err.message : String(err);
+   const message = describeError(err);
    const normalized = message.toLowerCase();
    return CONNECTION_GONE_PATTERNS.some(pattern => pattern.test(normalized));
 }
@@ -92,6 +94,6 @@ export function isClientGoneError(err: unknown): boolean {
    if (err instanceof Error && 'code' in err && typeof err.code === 'string' && SOCKET_GONE_CODES.has(err.code)) {
       return true;
    }
-   const message = err instanceof Error ? err.message : String(err);
+   const message = describeError(err);
    return SOCKET_GONE_PATTERN.test(message.toLowerCase());
 }