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

package/src/langium/document-builder/document-builder.ts

@@ -7,7 +7,14 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock, type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
+import {
+   type Clock,
+   type LogThreshold,
+   type MaybeObservableValue,
+   ObservableValue,
+   type Tracer,
+   describeErrorWithStack
+} from '@hydranium/protocol';
 import {
    type AstNode,
    type BuildOptions,
@@ -356,7 +363,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
          try {
             listener(event);
          } catch (error: unknown) {
-            this.tracer.error(`A build-ended listener failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+            this.tracer.error(`A build-ended listener failed: ${describeErrorWithStack(error)}`);
          }
       }
    }
@@ -488,12 +495,15 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
          // land while a busy workspace keeps cancelling builds.
          let stalledRequeues = 0;
          let lastRequeueState: DocumentState | undefined;
-         const giveUp = (reason: string): void => {
+         let settled = false;
+         let cancelled = false;
+         const giveUp = (reason: string, cause?: unknown): void => {
             cleanup();
             reject(
                new Error(
                   `Gave up building ${this.formatUri(uri)} to '${DocumentState[state]}' ` +
-                     `(at '${DocumentState[document.state]}'): ${reason}`
+                     `(at '${DocumentState[document.state]}'): ${reason}`,
+                  { cause }
                )
             );
          };
@@ -517,9 +527,16 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
                stalledRequeues = 0;
                lastRequeueState = document.state;
             }
-            void this.requeueOrphaned(document, state, reason).then(built => {
-               if (!built && rejectWhenStuck) {
-                  giveUp('its recovery build failed');
+            this.requeueOrphaned(document, state, reason).catch((error: unknown) => {
+               const line = `A recovery build of ${this.formatUri(uri)} failed. ${describeErrorWithStack(error)}`;
+               if (rejectWhenStuck && !settled) {
+                  giveUp('its recovery build failed', error);
+               } else if (settled && !cancelled) {
+                  // The wait ended with an outcome its caller reports, and the retry warned.
+                  this.tracer.withUri(uri.toString()).debug(line);
+               } else {
+                  // The waiter has gone, or waits on its cancellation token alone, so nothing else reports this.
+                  this.tracer.withUri(uri.toString()).error(line);
                }
             });
          };
@@ -559,10 +576,12 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
          };
          const buildDisposable = this.onBuildEnded(buildEnded);
          const cancelDisposable = cancelToken.onCancellationRequested(() => {
+            cancelled = true;
             cleanup();
             reject(OperationCancelled);
          });
          const cleanup = (): void => {
+            settled = true;
             phaseDisposable.dispose();
             skipDisposable.dispose();
             buildDisposable.dispose();
@@ -628,11 +647,11 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
     * the build neither runs beside a locked one nor cancels the build a
     * re-queue is fired from, and skipped if a write that ran meanwhile carried
     * the document to `state`. The waiter resolves off the resulting phase
-    * notification; the answer only tells it whether the build was given up.
+    * notification; the promise only tells it whether the build was given up.
     */
-   protected requeueOrphaned(document: LangiumDocument, state: DocumentState, reason: string): Promise<boolean> {
+   protected requeueOrphaned(document: LangiumDocument, state: DocumentState, reason: string): Promise<void> {
       const tracer = this.tracer.withUri(document.uri.toString());
-      tracer.info(`Re-queuing orphaned document (at '${DocumentState[document.state]}', needs '${DocumentState[state]}'): ${reason}`);
+      tracer.debug(`Re-queuing orphaned document (at '${DocumentState[document.state]}', needs '${DocumentState[state]}'): ${reason}`);
       return this.versionSyncService().requestRecoveryBuild(document.uri, {
          // Skipped on purpose: a waiting caller is answered sooner, at the cost
          // of a possible duplicate build once the debounce fires.
@@ -1391,7 +1410,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       if (cancelledListeners > 0) {
          this.tracer
             .withUri(document.uri.toString())
-            .info(this.cancelledDocumentPhaseLine(document, state, cancelledListeners, listeners.length));
+            .debug(this.cancelledDocumentPhaseLine(document, state, cancelledListeners, listeners.length));
       }
       if (totalMs >= this.slowPhaseMs.value) {
          this.log(this.slowDocumentPhaseLine(document, state, listeners, perListenerMs, totalMs));

package/src/langium/integrity/integrity-service.ts

@@ -213,8 +213,11 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
          await interruptAndCheck(cancelToken);
       }
       const totalMs = Math.round(performance.now() - phaseStart);
-      if (totalMs >= 25 || mutatedCount > 0) {
+      // A repair is the operator's to know of; the timing alone is diagnosis.
+      if (mutatedCount > 0) {
          this.tracer.info(`enforce ${DocumentState[phase]}: docs=${documents.length}, mutated=${mutatedCount} [${totalMs}ms]`);
+      } else if (totalMs >= 25) {
+         this.tracer.debug(`enforce ${DocumentState[phase]}: docs=${documents.length}, mutated=${mutatedCount} [${totalMs}ms]`);
       }
       // One line per rule (count + self-% + self-ms), sorted by cost — only when profiling.
       session?.report('debug');

package/src/langium/model-service/client-session.ts

@@ -17,9 +17,10 @@ import {
    ObservableValue,
    type TextVersion,
    type Tracer,
-   type TransferElement
+   type TransferElement,
+   describeErrorWithStack
 } from '@hydranium/protocol';
-import { type AstNode, UriUtils } from '@hydranium/langium';
+import { type AstNode, isOperationCancelled, UriUtils } from '@hydranium/langium';
 import { type CancellationToken, type Disposable, Emitter, type Event } from 'vscode-languageserver';
 import { type AstDocument, type SavedAstDocument } from '../../documents/ast-document-manager.js';
 import { DocumentNotOpenError, SessionClosedError } from '../../documents/client-session-errors.js';
@@ -410,7 +411,23 @@ export class DefaultClientSession<
       const applied = uris.map((uri, i) => this.services.workspace.AstDocumentManager.update(uri, texts[i], this.clientId));
       await Promise.all(applied);
       const state = this.services.workspace.DocumentBuilder.finalBuildState();
-      return Promise.all(uris.map(uri => service.rebuild(uri, state, cancelToken)));
+      const rebuilt = await Promise.allSettled(uris.map(uri => service.rebuild(uri, state, cancelToken)));
+      const failures = rebuilt.flatMap((result, i) => (result.status === 'rejected' ? [{ uri: uris[i], reason: result.reason }] : []));
+      if (failures.length === 0) {
+         return rebuilt.flatMap(result => (result.status === 'fulfilled' ? [result.value] : []));
+      }
+      // The first is thrown as it is, so a typed failure keeps its type; one build
+      // usually carries the set and fails each with the same error. Any other
+      // failure reaches no one else, so it is logged here.
+      const [{ uri: firstUri, reason: firstReason }] = failures;
+      for (const { uri, reason } of failures.slice(1)) {
+         if (isOperationCancelled(reason)) {
+            this.tracer.with(uri).debug(`Rebuild of ${uri} cancelled beside that of ${firstUri}`);
+         } else if (reason !== firstReason) {
+            this.tracer.with(uri).error(`Rebuild of ${uri} failed beside that of ${firstUri}. ${describeErrorWithStack(reason)}`);
+         }
+      }
+      throw firstReason;
    }
 
    /**

package/src/langium/model-service/model-service.ts

@@ -18,9 +18,18 @@ import {
    type TransferElement,
    type TextVersion,
    type Tracer,
-   UNRECORDED_VERSION
+   UNRECORDED_VERSION,
+   describeErrorWithStack
 } from '@hydranium/protocol';
-import { type AstNode, DocumentState, type LangiumDocument, OperationCancelled, UriUtils, type URI } from '@hydranium/langium';
+import {
+   type AstNode,
+   DocumentState,
+   type LangiumDocument,
+   OperationCancelled,
+   isOperationCancelled,
+   UriUtils,
+   type URI
+} from '@hydranium/langium';
 import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
 import { ReentrantWriteLockError, isInsideWriteLock, isWriteLockScopeInstalled } from '../workspace/write-lock-scope.js';
@@ -571,23 +580,37 @@ export class DefaultModelService<
     * given up. A `Parsed` phase listener cannot serve: a cancel right after the
     * parse skips it, and the resumed build does not parse again.
     */
-   protected nextParseOrDeletion(
-      uri: URI,
-      cancelToken: CancellationToken = CancellationToken.None,
-      build?: Promise<boolean>
-   ): Promise<void> {
+   protected nextParseOrDeletion(uri: URI, cancelToken: CancellationToken = CancellationToken.None, build?: Promise<void>): Promise<void> {
       const builder = this.services.workspace.DocumentBuilder;
       return new Promise<void>((resolve, reject) => {
+         let ended = false;
+         let cancelled = false;
+         // Handled before any return, so a build given up after the wait ended is not an unhandled rejection.
+         build?.catch((error: unknown) => {
+            const line = `The build that would sync the root to its text failed. ${describeErrorWithStack(error)}`;
+            if (cancelled) {
+               // The waiter has gone, so nothing else reports this.
+               this.tracer.withUri(uri.toString()).error(line);
+            } else if (ended) {
+               // A parse or deletion came first: the waiter goes on and reports its own outcome, and the retry warned.
+               this.tracer.withUri(uri.toString()).debug(line);
+            } else {
+               done(() => reject(new Error(`The build that would sync ${uri.toString()} to its text failed`, { cause: error })));
+            }
+         });
          // A cancelled token's listener runs a macrotask later, after a build
          // that started meanwhile may have parsed.
          if (cancelToken.isCancellationRequested) {
+            ended = true;
+            cancelled = true;
             reject(OperationCancelled);
             return;
          }
          const done = (settle: () => void): void => {
+            ended = true;
             parsed.dispose();
             deleted.dispose();
-            cancelled.dispose();
+            cancelling.dispose();
             settle();
          };
          const parsed = this.services.workspace.VersionSyncService.onDidRecordModel(document => {
@@ -600,11 +623,9 @@ export class DefaultModelService<
                done(resolve);
             }
          });
-         const cancelled = cancelToken.onCancellationRequested(() => done(() => reject(OperationCancelled)));
-         void build?.then(built => {
-            if (!built) {
-               done(() => reject(new Error(`The build that would sync ${uri.toString()} to its text failed`)));
-            }
+         const cancelling = cancelToken.onCancellationRequested(() => {
+            cancelled = true;
+            done(() => reject(OperationCancelled));
          });
       });
    }
@@ -808,8 +829,9 @@ export class DefaultModelService<
     * so every language client reflects the latest content before a save returns.
     * No-op tail for headless adopters — `syncChains` is empty without an LSP
     * client. Bounded by {@link SAVE_SETTLE_TIMEOUT_MS} so a hung build, or an
-    * applyEdit reverse-RPC deadlock, can't freeze the caller; on timeout or a
-    * failed wait it logs a warning and returns rather than throwing.
+    * applyEdit reverse-RPC deadlock, can't freeze the caller; it returns rather
+    * than throwing, warning on timeout. A failed wait is logged at `error`, at
+    * `debug` when cancelled and at `warn` when the document is gone.
     *
     * Adopters with a save flow that must converge editor + disk before returning
     * (e.g. a dual form/code editor that would otherwise show a content-conflict
@@ -824,15 +846,26 @@ export class DefaultModelService<
          await this.waitForDocumentStateCanonical(canonical, IntegrityService.SettledState, cancelToken, { sync: true });
          await this.syncChains.get(key);
       })();
+      // The settle ends a failed wait, so it logs it, at one level whether the wait failed inside the bound or after it.
+      const reportFailedWait = (error: unknown, when: string): void => {
+         const tracer = this.tracer.withUri(key);
+         if (isOperationCancelled(error)) {
+            tracer.debug(`Save settle cancelled ${when}`);
+         } else if (!this.services.workspace.LangiumDocuments.hasDocument(UriUtils.toUri(canonical))) {
+            tracer.warn(`Save settle failed ${when}; the document is gone. ${describeErrorWithStack(error)}`);
+         } else {
+            tracer.error(`Save settle failed ${when}. ${describeErrorWithStack(error)}`);
+         }
+      };
       try {
          if ((await this.services.Clock.raceTimer(settled, SAVE_SETTLE_TIMEOUT_MS)) === TIMED_OUT) {
             this.tracer.withUri(key).warn(`Save settle exceeded ${SAVE_SETTLE_TIMEOUT_MS}ms — returning anyway`);
+            // The race has settled, so a later failure of the wait, such as a given-up sync build, reaches no one else.
+            void settled.catch((error: unknown) => reportFailedWait(error, 'after the timeout'));
          }
       } catch (err: unknown) {
-         // A failed wait, such as a cancelled token or a document the builder
-         // does not hold, gets its own line so it is not blamed on the bound.
-         const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
-         this.tracer.withUri(key).warn(`Save settle failed before the timeout — returning anyway. ${detail}`);
+         // Its own line, so the failure is not blamed on the bound.
+         reportFailedWait(err, 'before the timeout — returning anyway');
       }
    }
 
@@ -1123,7 +1156,7 @@ export class DefaultModelService<
             if (isClientGoneError(err)) {
                uriLogger.debug(`applyEdit to ${LANGUAGE_CLIENT_ID} skipped: client disconnected`);
             } else {
-               uriLogger.error(`applyEdit to ${LANGUAGE_CLIENT_ID} failed: ${err}`);
+               uriLogger.error(`applyEdit to ${LANGUAGE_CLIENT_ID} failed: ${describeErrorWithStack(err)}`);
             }
          }
       }
@@ -1162,7 +1195,7 @@ export class DefaultModelService<
          try {
             listener(Object.freeze({ uris: built.map(document => this.uriPolicy.canonicalUri(document.uri.toString())), phase }));
          } catch (err: unknown) {
-            this.tracer.error(`onModelsBuilt listener threw: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+            this.tracer.error(`onModelsBuilt listener threw: ${describeErrorWithStack(err)}`);
          }
       });
    }
@@ -1267,9 +1300,7 @@ export class DefaultModelService<
          try {
             listener(event);
          } catch (err: unknown) {
-            this.tracer
-               .with(uri)
-               .error(`onModelUpdated listener threw: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+            this.tracer.with(uri).error(`onModelUpdated listener threw: ${describeErrorWithStack(err)}`);
          }
       }
    }

package/src/langium/project/abstract-project-manager.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred, type Project, type Tracer, UNQUALIFIED_PROJECT_REFERENCE } from '@hydranium/protocol';
+import { Deferred, type Project, type Tracer, UNQUALIFIED_PROJECT_REFERENCE, describeErrorWithStack } from '@hydranium/protocol';
 import {
    type AstNode,
    AstUtils,
@@ -226,7 +226,7 @@ export abstract class AbstractProjectManager<TProject extends Project = Project>
       try {
          entries = await this.fileSystemProvider.readDirectory(folder);
       } catch (error) {
-         this.tracer.warn(`Failed to read directory ${folder.toString()}: ${error}`);
+         this.tracer.warn(`Failed to read directory ${folder.toString()}: ${describeErrorWithStack(error)}`);
          return;
       }
       for (const entry of entries) {
@@ -395,7 +395,7 @@ export abstract class AbstractProjectManager<TProject extends Project = Project>
          }
          return project;
       } catch (error) {
-         this.tracer.error(`Failed to parse ${this.conceptName()} descriptor at ${uri.toString()}: ${error}`);
+         this.tracer.error(`Failed to parse ${this.conceptName()} descriptor at ${uri.toString()}: ${describeErrorWithStack(error)}`);
          return undefined;
       }
    }
@@ -620,7 +620,7 @@ export abstract class AbstractProjectManager<TProject extends Project = Project>
          try {
             listener(event);
          } catch (error) {
-            this.tracer.error(`Project change listener failed: ${error}`);
+            this.tracer.error(`Project change listener failed: ${describeErrorWithStack(error)}`);
          }
       }
    }

package/src/langium/scope/hydranium-scope-computation.ts

@@ -59,6 +59,10 @@ import { type HydraniumAstNodeDescriptionProvider } from './ast-node-description
  * duplicated walks.
  */
 export class HydraniumScopeComputation extends DefaultScopeComputation {
+   /** The framework's name provider, which its language module binds to the slot. */
+   declare protected readonly nameProvider: NameProvider;
+   /** The framework's description provider, which its language module binds to the slot. */
+   declare protected readonly descriptions: HydraniumAstNodeDescriptionProvider;
    protected readonly tracer: Tracer;
 
    constructor(
@@ -155,17 +159,15 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * workspace-visible rather than being filtered out everywhere.
     */
    protected exportProject(node: AstNode, exports: AstNodeDescription[], document: LangiumDocument): void {
-      const nameProvider = this.nameProvider as NameProvider;
-      const documentName = nameProvider.getDocumentQualifiedName(node);
+      const documentName = this.nameProvider.getDocumentQualifiedName(node);
       if (!documentName) {
          return;
       }
       const projectId = this.getProjectIdForDocument(document);
-      const descriptions = this.descriptions as HydraniumAstNodeDescriptionProvider;
       exports.push(
          projectId !== undefined
-            ? descriptions.createProject({ node, name: documentName, document, projectId })
-            : descriptions.createUniversal({ node, name: documentName, document })
+            ? this.descriptions.createProject({ node, name: documentName, document, projectId })
+            : this.descriptions.createUniversal({ node, name: documentName, document })
       );
    }
 
@@ -182,16 +184,14 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
     * document-qualified name.
     */
    protected exportPublic(node: AstNode, exports: AstNodeDescription[], document: LangiumDocument): void {
-      const nameProvider = this.nameProvider as NameProvider;
       const projectId = this.getProjectIdForDocument(document);
       if (projectId === undefined) {
          return;
       }
-      const documentName = nameProvider.getDocumentQualifiedName(node);
-      const projectName = nameProvider.getProjectQualifiedName(node);
+      const documentName = this.nameProvider.getDocumentQualifiedName(node);
+      const projectName = this.nameProvider.getProjectQualifiedName(node);
       if (projectName && projectName !== documentName) {
-         const descriptions = this.descriptions as HydraniumAstNodeDescriptionProvider;
-         exports.push(descriptions.createPublic({ node, name: projectName, document, projectId }));
+         exports.push(this.descriptions.createPublic({ node, name: projectName, document, projectId }));
       }
    }
 
@@ -239,9 +239,9 @@ export class HydraniumScopeComputation extends DefaultScopeComputation {
       if (!container) {
          return;
       }
-      const name = (this.nameProvider as NameProvider).getOwnName(node);
+      const name = this.nameProvider.getOwnName(node);
       if (name) {
-         symbols.add(container, (this.descriptions as HydraniumAstNodeDescriptionProvider).createLocal({ node, name, document }));
+         symbols.add(container, this.descriptions.createLocal({ node, name, document }));
       }
    }
 }

package/src/langium/validation/document-validator.ts

@@ -698,9 +698,11 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
     */
    protected buildElementPath<N extends AstNode>(node: N, info: DiagnosticInfo<N, string>): string {
       const directPath = this.astNodeLocator.getAstNodePath(node);
-      const containerPath = directPath ? undefined : this.astNodeLocator.getAstNodePath(node.$container ?? ({ $type: 'Dummy' } as AstNode));
-      const nodePath = directPath || containerPath;
-      if (!nodePath) {
+      // The locator answers '' for the root, which is the root's path rather than a miss.
+      const isRoot = node.$container === undefined;
+      const containerPath = directPath || isRoot ? undefined : this.astNodeLocator.getAstNodePath(node.$container);
+      const nodePath = directPath || containerPath || '';
+      if (!nodePath && !isRoot) {
          this.tracer.warn('Cannot create diagnostic element path: Unable to determine AST node path.');
          return '';
       }

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

@@ -18,7 +18,7 @@ import { runInWriteLockScope } from './write-lock-scope.js';
 export interface HydraniumWorkspaceLockOptions extends LogNameOptions {
    /**
     * How long a write may keep running after a later write cancelled it before
-    * the lock logs an error. Every write and read waits behind it meanwhile, so
+    * the lock logs a warning. Every write and read waits behind it meanwhile, so
     * one that never ends stops the server. Defaults to 10 s; `0` turns the
     * check off.
     */
@@ -109,7 +109,7 @@ export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
    }
 
    protected reportStalledWrite(): void {
-      this.tracer.error(
+      this.tracer.warn(
          `A write is still running ${this.stalledWriteWarnMs} ms after it was cancelled, and every write and read waits behind it. ` +
             'Likely causes: a model-service write or rebuild from inside a build in a host with no write-lock scope tracker, ' +
             'which waits for the build it runs in, or a write action that ignores its cancellation token. ' +

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

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
+import { Deferred, type Logger, type Tracer, describeError, describeErrorWithStack } from '@hydranium/protocol';
 import {
    DefaultWorkspaceManager,
    DocumentState,
@@ -69,7 +69,7 @@ export function handleProcessUnhandledRejection(reason: unknown, logger: Logger)
    if (typeof reason === 'symbol' && String(reason) === 'Symbol(OperationCancelled)') {
       return;
    }
-   logger.error('Unhandled promise rejection: ' + (reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)));
+   logger.error('Unhandled promise rejection: ' + describeErrorWithStack(reason));
 }
 
 /**
@@ -507,11 +507,10 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
          await super.initializeWorkspace(folders, cancelToken);
          this.workspaceInitializedDeferred.resolve(undefined);
       } catch (error: unknown) {
-         const message = error instanceof Error ? error.message : String(error);
          if (isOperationCancelled(error) || isConnectionGoneError(error)) {
-            this.tracer.debug(`Initial workspace build did not complete: ${message}`);
+            this.tracer.debug(`Initial workspace build did not complete: ${describeError(error)}`);
          } else {
-            this.tracer.error(`Initial workspace build failed: ${message}`);
+            this.tracer.error(`Initial workspace build failed: ${describeErrorWithStack(error)}`);
          }
          this.workspaceInitializedDeferred.reject(error);
          throw error;

package/src/langium/workspace/persistent-file-system-provider.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { URI } from '@hydranium/langium';
+import { describeErrorWithStack } from '@hydranium/protocol';
 import { type WritableFileSystemProvider } from './file-system-provider.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type FileSystemSeed, InMemoryFileSystemProvider, type InMemoryFileSystemOptions } from './in-memory-file-system-provider.js';
@@ -250,7 +251,7 @@ export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
    }
 
    protected reportStoreFailure(operation: string, uri: URI, error: unknown): void {
-      this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${error instanceof Error ? error.message : String(error)}`);
+      this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${describeErrorWithStack(error)}`);
    }
 }
 

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) };
 }