@hydranium/core 1.0.0-next.33 → 1.0.0-next.331

package/src/lsp/lsp-latency.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * 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 { LatencyCollector } from '@hydranium/protocol';
+import type { ConnectionOptions, Message } from 'vscode-jsonrpc';
+
+/**
+ * Connection options that time every inbound LSP message into `latency` under
+ * its method name — the LSP analog of the data-server RPC chokepoint.
+ *
+ * Pass the result to `createConnection` where the head builds its connection:
+ * `createConnection(ProposedFeatures.all, lspLatencyOptions(latency))`. The
+ * transport is untouched, so a head keeps whatever `--stdio` / `--socket`
+ * selection its arguments make.
+ *
+ * **`messageStrategy` is the seam because it is the only one the handlers
+ * actually pass through.** `vscode-languageserver` builds its `Connection` as an
+ * object whose `onHover`, `onCompletion` and every other named helper register
+ * against the inner protocol connection captured in their closure — not against
+ * the returned object's own `onRequest`. Langium registers exclusively through
+ * those helpers, so decorating the `Connection` reaches none of them and reports
+ * an empty LSP half no matter how much traffic ran. `handleMessage` sits on the
+ * dispatch path itself, which every request and notification crosses, so it also
+ * catches `initialize` — special-cased into `onInitialize` and invisible to any
+ * `onRequest` decoration.
+ *
+ * What it measures is **dispatch plus handler**, not handler alone: the wait a
+ * client actually experiences, including time queued behind other work.
+ *
+ * When `latency` is `undefined` the seam is off and this returns `undefined`, so
+ * a head can pass the result of an env-gated factory (`latencyFromEnv()`)
+ * straight through and pay nothing when timing is not enabled.
+ */
+export function lspLatencyOptions(latency: LatencyCollector | undefined): ConnectionOptions | undefined {
+   if (!latency) {
+      return undefined;
+   }
+   return {
+      messageStrategy: {
+         handleMessage: (message: Message, next: (message: Message) => void | Promise<void>) => {
+            // Responses to requests the SERVER sent carry no method and are not
+            // work this head performed; timing them would report the client's
+            // latency under a name this collector cannot supply.
+            if (!hasMethod(message)) {
+               return next(message);
+            }
+            return latency.time(message.method, () => next(message));
+         }
+      }
+   };
+}
+
+/** Narrow to the messages that name an operation — requests and notifications. */
+function hasMethod(message: Message): message is Message & { method: string } {
+   return typeof (message as { method?: unknown }).method === 'string';
+}

package/src/lsp/save-text-document.ts

@@ -0,0 +1,63 @@
+/********************************************************************************
+ * 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 { isResponseError, type SaveTextDocumentParams, SaveTextDocumentRequest } from '@hydranium/protocol';
+import {
+   combineWorkspaceFeatures,
+   type Connection,
+   type Disposable,
+   type Features,
+   ResponseError,
+   type ServerCapabilities,
+   type WorkspaceFeature
+} from 'vscode-languageserver';
+import { LANGUAGE_CLIENT_ID } from '../documents/client-ids.js';
+import type { ServerSharedServices } from '../langium/module.js';
+
+/**
+ * Advertise {@link SaveTextDocumentRequest} in the `initialize` answer, as
+ * `experimental[SaveTextDocumentRequest.method]`, LSP's place for a server
+ * feature it does not define. Supply it where the connection is created, with
+ * {@link listenToSaveTextDocument} on that connection: only a host whose files
+ * the server holds answers the request, and a client takes the entry as the
+ * promise that it does.
+ */
+export function withSaveTextDocumentCapability<T extends Features>(features: T): T {
+   const advertise: WorkspaceFeature<object> = Base =>
+      class extends Base {
+         override fillServerCapabilities(capabilities: ServerCapabilities): void {
+            super.fillServerCapabilities(capabilities);
+            capabilities.experimental = { ...capabilities.experimental, [SaveTextDocumentRequest.method]: true };
+         }
+      };
+   return { ...features, workspace: features.workspace ? combineWorkspaceFeatures(features.workspace, advertise) : advertise };
+}
+
+/**
+ * Answer {@link SaveTextDocumentRequest} on `connection`: persist the store's
+ * text once `TextDocuments.assertLanguageClientHolds` finds the editor's
+ * buffer holds it. The gate and the manager's taking of the text are one
+ * synchronous step, so no change can land between them.
+ *
+ * A refusal crosses the wire as the data head's do, its message rendered by
+ * `MessageRenderer` and rebuilt on the connection's copy of `vscode-jsonrpc`,
+ * which keeps the code only of its own copy's errors.
+ */
+export function listenToSaveTextDocument(connection: Connection, shared: ServerSharedServices): Disposable {
+   return connection.onRequest(SaveTextDocumentRequest.method, async (params: SaveTextDocumentParams) => {
+      const { uri, version } = params.textDocument;
+      try {
+         shared.workspace.TextDocuments.assertLanguageClientHolds(uri, version);
+         await shared.workspace.AstDocumentManager.save(uri, LANGUAGE_CLIENT_ID);
+      } catch (error: unknown) {
+         throw isResponseError(error) ? new ResponseError(error.code, shared.MessageRenderer.renderError(error), error.data) : error;
+      }
+      return null;
+   });
+}

package/src/lsp/semantic-token-provider.ts

@@ -14,11 +14,27 @@ import {
    CstUtils,
    GrammarAST,
    interruptAndCheck,
+   isLeafCstNode,
    type LangiumDocument,
+   type LeafCstNode,
    type ReferenceInfo
 } from '@hydranium/langium';
+import { STALE_VERSION, UNRECORDED_VERSION } from '@hydranium/protocol';
 import { AbstractSemanticTokenProvider, type SemanticTokenAcceptor } from '@hydranium/langium/lsp';
-import { type CancellationToken, SemanticTokenModifiers, SemanticTokenTypes } from 'vscode-languageserver';
+import {
+   type CancellationToken,
+   LSPErrorCodes,
+   ResponseError,
+   SemanticTokenModifiers,
+   type SemanticTokens,
+   type SemanticTokensDelta,
+   type SemanticTokensDeltaParams,
+   type SemanticTokensParams,
+   type SemanticTokensRangeParams,
+   SemanticTokenTypes
+} from 'vscode-languageserver';
+import { type HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
+import { type ModelLedger } from '../documents/model-ledger.js';
 import { type NameProvider } from '../langium/naming/name-provider.js';
 import { type ServerLanguageServices } from '../langium/language-module.js';
 
@@ -54,6 +70,23 @@ export interface HydraniumSemanticTokenProviderOptions {
     * render in the editor's default foreground.
     */
    readonly highlightKeywords?: boolean;
+
+   /**
+    * Also emit a `comment` token for every comment leaf of the CST.
+    *
+    * OFF by default for the same reason as {@link highlightKeywords}, and the
+    * loss is larger: a TextMate grammar distinguishes `comment.line` from
+    * `comment.block` and scopes the delimiters separately, where a semantic
+    * token carries one flat `comment` that overrides all of them. It exists
+    * for the host that ships no client-side grammar, where a comment otherwise
+    * renders in the editor's default foreground.
+    *
+    * What counts as a comment is every hidden terminal the lexer retains,
+    * which is every hidden terminal whose pattern is not whitespace. A grammar
+    * whose hidden non-whitespace terminal means something other than a comment
+    * is miscoloured, and this option is the place to say no.
+    */
+   readonly highlightComments?: boolean;
 }
 
 /**
@@ -96,6 +129,8 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
    protected readonly nameProvider: NameProvider;
    protected readonly reflection: AstReflection;
    protected readonly options: HydraniumSemanticTokenProviderOptions;
+   protected readonly textDocuments: HydraniumTextDocuments;
+   protected readonly modelLedger: ModelLedger;
 
    /**
     * Modifier added to every declaration token. `declaration` is what themes
@@ -109,6 +144,61 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
       this.nameProvider = services.references.NameProvider;
       this.reflection = services.shared.AstReflection;
       this.options = options;
+      this.textDocuments = services.shared.workspace.TextDocuments;
+      this.modelLedger = services.shared.workspace.ModelLedger;
+   }
+
+   override async semanticHighlight(
+      document: LangiumDocument,
+      params: SemanticTokensParams,
+      cancelToken?: CancellationToken
+   ): Promise<SemanticTokens> {
+      this.assertEditorHoldsParse(document, params.textDocument.uri);
+      return super.semanticHighlight(document, params, cancelToken);
+   }
+
+   override async semanticHighlightRange(
+      document: LangiumDocument,
+      params: SemanticTokensRangeParams,
+      cancelToken?: CancellationToken
+   ): Promise<SemanticTokens> {
+      this.assertEditorHoldsParse(document, params.textDocument.uri);
+      return super.semanticHighlightRange(document, params, cancelToken);
+   }
+
+   override async semanticHighlightDelta(
+      document: LangiumDocument,
+      params: SemanticTokensDeltaParams,
+      cancelToken?: CancellationToken
+   ): Promise<SemanticTokens | SemanticTokensDelta> {
+      this.assertEditorHoldsParse(document, params.textDocument.uri);
+      return super.semanticHighlightDelta(document, params, cancelToken);
+   }
+
+   /**
+    * Refuse with `ContentModified` while the editor of `uri` holds text older
+    * than the parse the tokens are computed from, e.g. while the push of
+    * another client's write is still in flight. Tokens carry no text version,
+    * so the editor applies them to the text it holds, and Monaco rejects them
+    * as invalid or colours the wrong ranges. Once the push changes the
+    * editor's text, the editor requests the tokens again. Encoding the text
+    * version in `resultId` instead would require every client to compare it.
+    *
+    * An editor ahead of the parse, as after a keystroke that waits for a
+    * debounced build, still gets its tokens. It maps them over its own changes
+    * since the request, and LSP leaves a result on an older state to the
+    * client. The check runs before the token walk, so a refused delta request
+    * keeps the result named by `previousResultId` as the base of the next one.
+    */
+   protected assertEditorHoldsParse(document: LangiumDocument, uri: string): void {
+      const parsedFrom = this.modelLedger.versionOf(document.parseResult.value);
+      // Neither is a version of the store's text, so there is nothing to compare.
+      if (parsedFrom === UNRECORDED_VERSION || parsedFrom === STALE_VERSION) {
+         return;
+      }
+      if (this.textDocuments.isLanguageClientBehind(uri, parsedFrom)) {
+         throw new ResponseError(LSPErrorCodes.ContentModified, 'The editor does not have the parsed text yet');
+      }
    }
 
    /**
@@ -133,7 +223,9 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
       cancelToken: CancellationToken
    ): Promise<void> {
       await super.computeHighlighting(document, acceptor, cancelToken);
-      if (this.options.highlightKeywords !== true) {
+      const keywords = this.options.highlightKeywords === true;
+      const comments = this.options.highlightComments === true;
+      if (!keywords && !comments) {
          return;
       }
       const root = document.parseResult.value.$cstNode;
@@ -142,14 +234,60 @@ export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSem
       }
       for (const cst of CstUtils.streamCst(root)) {
          await interruptAndCheck(cancelToken);
-         // The grammar source is the whole filter. A keyword is always a leaf,
-         // and the hidden leaves a comment or a run of whitespace contributes
-         // are sourced from a terminal rule rather than a `Keyword` — so
-         // neither a composite-node check nor a hidden-token check adds
-         // anything here.
-         if (GrammarAST.isKeyword(cst.grammarSource)) {
+         // A keyword is always a leaf with a `Keyword` grammar source, so that
+         // check alone separates it from everything else in the walk.
+         if (keywords && GrammarAST.isKeyword(cst.grammarSource)) {
             acceptor({ cst, type: SemanticTokenTypes.keyword });
          }
+         // A comment leaf cannot be recognised the same way — the CST builder
+         // adds hidden nodes from the token alone, so `grammarSource` is
+         // undefined, which is also why the keyword filter never matches one.
+         //
+         // `hidden` alone IS the comment test, and nothing narrower is needed:
+         // the token builder groups a hidden terminal as `Lexer.SKIPPED` when
+         // its pattern matches whitespace and as `hidden` otherwise, so the
+         // lexer discards whitespace before a CST node is ever built and every
+         // hidden leaf that survives is a comment. Classifying the terminal
+         // again here would be a second guard for the same property, which no
+         // test could then distinguish. An adopter whose token builder RETAINS
+         // whitespace breaks that equivalence and would colour its gaps.
+         if (comments && isLeafCstNode(cst) && cst.hidden) {
+            this.acceptComment(cst, acceptor);
+         }
+      }
+   }
+
+   /**
+    * Emit a comment as ONE TOKEN PER LINE, never as one multi-line range.
+    *
+    * A block comment is the first token this provider emits that can span
+    * lines, and the upstream encoder mishandles that for a client which does
+    * not advertise `multilineTokenSupport` — the split path computes the first
+    * line's length as `nextLineOffset - range.start.character - 1`, subtracting
+    * a COLUMN from a document OFFSET, so the length is right only for a token
+    * starting on line 0 and overruns its line everywhere else. No client in
+    * this repository advertises that capability, so the broken path is the one
+    * taken. Splitting here means every range handed over starts and ends on one
+    * line and the arithmetic is never reached.
+    *
+    * Lines come from the leaf's own text rather than from the document, so
+    * nothing has to re-derive where the comment ends.
+    */
+   protected acceptComment(cst: LeafCstNode, acceptor: SemanticTokenAcceptor): void {
+      const lines = cst.text.split('\n');
+      for (let index = 0; index < lines.length; index++) {
+         // A `\r\n` document leaves the carriage return on the line's end;
+         // colouring it would extend the token past the visible text.
+         const length = lines[index].replace(/\r$/, '').length;
+         const character = index === 0 ? cst.range.start.character : 0;
+         if (length === 0) {
+            continue;
+         }
+         const line = cst.range.start.line + index;
+         acceptor({
+            range: { start: { line, character }, end: { line, character: character + length } },
+            type: SemanticTokenTypes.comment
+         });
       }
    }
 

package/src/lsp/shared-module.ts

@@ -28,14 +28,10 @@ import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-hand
  *   (an output channel, a structured logger) override the slot after this
  *   module.
  *
- * - {@link HydraniumDocumentUpdateHandler} wraps `didChangeWatchedFiles` to
- *   suppress echo events for the server's own writes via the shared
- *   `SelfSaveRegistry` slot, debounces `didChangeContent`, stamps build
- *   reasons through `markNextReason`, and dispatches a rebuild when the last
- *   client closes a document.
- *   Adopters with their own update-handler subclass should extend
- *   `HydraniumDocumentUpdateHandler` (not Langium's
- *   `DefaultDocumentUpdateHandler`) to preserve those behaviours.
+ * - {@link HydraniumDocumentUpdateHandler} carries the framework's handling of
+ *   the LSP document events. Adopters with their own update-handler subclass
+ *   should extend it (not Langium's `DefaultDocumentUpdateHandler`) to keep
+ *   that handling.
  *
  * **Why this is a shared slot and not a per-language one.** Langium declares
  * `DocumentUpdateHandler` in `LangiumSharedLSPServices` — there is exactly one

package/src/lsp/start-language-server.ts

@@ -13,6 +13,8 @@ import {
    type ServiceRequirements
 } from '@hydranium/langium/lsp';
 import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-handler.js';
+import { guardDiagnosticsConnection } from './diagnostics-connection.js';
+import { installConsoleTee } from '../langium/diagnostics/console-tee.js';
 
 /**
  * Fail the LSP head's start when its shared module was never composed.
@@ -21,10 +23,9 @@ import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-hand
  * SHARED slot, so the head binds it in `createLspServerSharedModule` — a
  * separate module from `createLspServerLanguageModule`. An adopter who adds
  * only the language module gets a server that boots, links and serves
- * completion, and quietly runs Langium's `DefaultDocumentUpdateHandler`: echo
- * suppression for the server's own writes, the `didChangeContent` debounce,
- * `markNextReason` stamping and the last-client-close rebuild are all absent,
- * with nothing in the log to say so.
+ * completion, and quietly runs Langium's `DefaultDocumentUpdateHandler`: every
+ * behaviour `HydraniumDocumentUpdateHandler` adds, the editor save gate
+ * included, is absent, with nothing in the log to say so.
  *
  * The type system does not catch it. `createIntegrationServices` returns
  * `inject(...) as unknown as TShared`, so widening `TShared` with
@@ -58,11 +59,21 @@ export function assertLspHeadComposed(services: LangiumSharedServices): void {
 
 /**
  * The framework's LSP server entry point: {@link assertLspHeadComposed}, then
- * Langium's `startLanguageServer` unchanged. Signature-compatible with
- * Langium's, so it is a drop-in for adopters importing from
- * `@hydranium/core/lsp`.
+ * {@link guardDiagnosticsConnection} on the tree's connection, then the
+ * console's wrapping for the log file, then Langium's `startLanguageServer`.
+ * Signature-compatible with Langium's, so it is a drop-in for adopters
+ * importing from `@hydranium/core/lsp`. Calling Langium's directly skips the
+ * composition check, the guard without which a publish racing teardown fails
+ * the build that validated the document, and the wrapping, which a stdio
+ * connection discards where a logger was built before it (see
+ * `installConsoleTee`).
  */
 export function startLanguageServer(services: LangiumSharedServices, serviceRequirements: Partial<ServiceRequirements> = {}): void {
    assertLspHeadComposed(services);
+   const connection = services.lsp.Connection;
+   if (connection) {
+      guardDiagnosticsConnection(connection);
+   }
+   installConsoleTee();
    startLangiumLanguageServer(services, serviceRequirements);
 }

package/src/messages/carriers.ts

@@ -36,11 +36,9 @@ import { Diagnostic } from 'vscode-languageserver-protocol';
  * put it: an encoder projecting that payload reads `diagnostic.data`, so the
  * narrower type made the identity and the companion mutually exclusive.
  *
- * The identity lands in both `code` and `data.hydranium` on purpose. `code` is
- * what survives to the editor surface; Theia's converter drops `data` before the
- * squiggle, so a parameterised diagnostic falls back to the server's English
- * there while any adopter-owned surface can still render the parameterised form
- * from the marker store.
+ * The identity lands in both `code` and `data.hydranium` on purpose: Theia's
+ * converter drops `data` before the squiggle, so `code` is what survives to the
+ * editor surface.
  *
  * `DiagnosticInfo` must be Langium's own type: a `Parameters<ValidationAcceptor>[2]`
  * shortcut compiles but loses the `property?: Properties<N>` relation. The `data`

package/src/messages/index.ts

@@ -22,6 +22,15 @@ 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 { LEXING_ERROR, UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.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 } from '../langium/workspace/in-memory-file-system-provider.js';
+export { NO_SUCH_FILE, NO_SUCH_PATH, UNSUPPORTED_DELETE, UNSUPPORTED_WRITE } from '../langium/workspace/in-memory-file-system-provider.js';

package/src/messages/renderer.ts

@@ -12,6 +12,8 @@ import {
    renderFrameworkMessage,
    resolve,
    resolvedFromResponseError,
+   type Locale,
+   type MessageCatalogue,
    type MessageDefinition,
    type ParamsArg,
    type ResolvedMessage,
@@ -25,8 +27,28 @@ 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 ServerMessageRenderer}. */
-export type ServerMessageRendererOptions = LogNameOptions;
+/** 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
@@ -41,7 +63,7 @@ export type ServerMessageRendererOptions = LogNameOptions;
  * single `render(text)` would force an adopter to match English prose, which
  * breaks on the first Langium reword.
  */
-export class ServerMessageRenderer {
+export class DefaultMessageRenderer implements MessageRenderer {
    protected readonly tracer: Tracer;
    protected readonly serverLocale: ServerLocale;
    /**
@@ -56,9 +78,9 @@ export class ServerMessageRenderer {
     * locale arrives once per process. A subclass whose catalogue can change
     * clears it.
     */
-   protected readonly catalogues = new SimpleCache<string | undefined, Record<string, string> | undefined>();
+   protected readonly catalogues = new SimpleCache<Locale | undefined, MessageCatalogue | undefined>();
 
-   constructor(services: ServerSharedServicesMinimal, options: ServerMessageRendererOptions = {}) {
+   constructor(services: ServerSharedServicesMinimal, options: MessageRendererOptions = {}) {
       this.serverLocale = services.ServerLocale;
       this.tracer = services.Tracer.for(options.logName ?? 'MessageRenderer').trace('instantiated');
    }
@@ -141,11 +163,17 @@ export class ServerMessageRenderer {
     * corollary is that a catalogue mutated in place afterwards is not seen;
     * clear {@link catalogues} to invalidate.
     *
+    * **An override merges its entries over the inherited answer rather than
+    * replacing it.** Returning only its own map shadows every entry a base
+    * class supplies, and a shadowed entry renders the English — byte-identical
+    * to a code deliberately left untranslated, so neither the render path nor a
+    * catalogue audit can report it.
+    *
     * An adopter wanting Langium's own uncoded sentences instead matches
     * `Diagnostic.data.code` from an overridden {@link renderDiagnostic}, never
     * the sentence.
     */
-   protected translationsFor(_locale: string | undefined): Record<string, string> | undefined {
+   protected translationsFor(_locale: Locale | undefined): MessageCatalogue | undefined {
       return undefined;
    }
 

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/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}`];
+}