@hydranium/core 1.0.0-next.28 → 1.0.0-next.280

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,7 @@ import {
    type ServiceRequirements
 } from '@hydranium/langium/lsp';
 import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-handler.js';
+import { guardDiagnosticsConnection } from './diagnostics-connection.js';
 
 /**
  * Fail the LSP head's start when its shared module was never composed.
@@ -21,10 +22,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 +58,17 @@ 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 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 both: the composition check, and the guard without which a
+ * publish racing teardown fails the build that validated the document.
  */
 export function startLanguageServer(services: LangiumSharedServices, serviceRequirements: Partial<ServiceRequirements> = {}): void {
    assertLspHeadComposed(services);
+   const connection = services.lsp.Connection;
+   if (connection) {
+      guardDiagnosticsConnection(connection);
+   }
    startLangiumLanguageServer(services, serviceRequirements);
 }

package/src/messages/carriers.ts

@@ -16,7 +16,7 @@ import {
    type ResolvedMessage
 } from '@hydranium/protocol';
 import type { AstNode, DiagnosticData, DiagnosticInfo, Properties, ValidationAcceptor } from '@hydranium/langium';
-import type { Diagnostic } from 'vscode-languageserver-protocol';
+import { Diagnostic } from 'vscode-languageserver-protocol';
 
 /**
  * Raise a validation diagnostic from a declaration, so the call site never
@@ -29,11 +29,16 @@ import type { Diagnostic } from 'vscode-languageserver-protocol';
  * be able to request a quick fix. The identity is merged OVER whatever they
  * pass, which makes the two conventions co-exist rather than compete.
  *
- * 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.
+ * `data` admits adopter-owned keys beside Langium's, which is why the index
+ * signature is there rather than a bare `Partial<DiagnosticData>`. Langium's
+ * shape is closed, and a diagnostic that carries a COMPANION payload for its own
+ * surface to read — the field a form must highlight, say — has nowhere else to
+ * 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: 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`
@@ -44,25 +49,28 @@ export function acceptMessage<S extends string, N extends AstNode, P extends Pro
    accept: ValidationAcceptor,
    severity: 'error' | 'warning' | 'info' | 'hint',
    message: MessageDefinition<S>,
-   info: Omit<DiagnosticInfo<N, P>, 'code' | 'data'> & { data?: Partial<DiagnosticData> },
+   info: Omit<DiagnosticInfo<N, P>, 'code' | 'data'> & { data?: Partial<DiagnosticData> & Record<string, unknown> },
    ...params: ParamsArg<S>
 ): void {
-   const data: HydraniumMessageData & Partial<DiagnosticData> = { ...info.data, ...messageData(message, ...params) };
+   const data: HydraniumMessageData & Partial<DiagnosticData> & Record<string, unknown> = {
+      ...info.data,
+      ...messageData(message, ...params)
+   };
    accept(severity, message.format(...params), { ...info, code: message.code, data });
 }
 
 /**
- * Recover the identity from a published diagnostic, for a surface that renders
- * diagnostics itself.
+ * Recover the identity from a published diagnostic, for a surface that
+ * identifies or renders diagnostics itself.
  *
- * The `MarkupContent` narrowing is not padding: `Diagnostic.message` is
- * `string | MarkupContent` in LSP 3.17+ and this does not compile without it.
- * Only the string form is a resolved English sentence.
+ * `Diagnostic.message` is `string | MarkupContent` in LSP 3.17+, so the text
+ * comes from upstream's own `Diagnostic.getMessageString` rather than a
+ * hand-rolled narrowing — consuming the library in its style, and one fewer
+ * place restating the union.
  */
 export function resolvedFromDiagnostic(diagnostic: Diagnostic): ResolvedMessage | undefined {
    if (!hasMessageIdentity(diagnostic.data)) {
       return undefined;
    }
-   const text = typeof diagnostic.message === 'string' ? diagnostic.message : diagnostic.message.value;
-   return { ...diagnostic.data.hydranium, text };
+   return { ...diagnostic.data.hydranium, text: Diagnostic.getMessageString(diagnostic) };
 }

package/src/messages/index.ts

@@ -18,7 +18,19 @@
  */
 
 export * from './carriers.js';
+export * from './renderer.js';
 
+export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
 export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
+export {
+   INVALID_DEDENT,
+   UNEXPECTED_CHARACTER,
+   MISSING_ITERATION,
+   NO_VIABLE_ALTERNATIVE,
+   TRAILING_INPUT,
+   UNEXPECTED_TOKEN,
+   UNPOPPABLE_LEXER_MODE,
+   UNRESOLVED_REFERENCE
+} from '../langium/validation/document-validator.js';
 export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
-export { NO_SUCH_FILE, NO_SUCH_PATH } 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

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

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

package/src/node/index.ts

@@ -35,11 +35,11 @@ export * from './server-diagnostics.js';
 // entry alongside the default policy.
 export * from './ast-ground-truth.js';
 export * from './event-loop-monitor.js';
+export * from './heap-ceiling.js';
 export * from './latency-from-env.js';
 export * from './measure-memory.js';
 export * from './memory-monitor.js';
 export * from './lint-grammar.js';
-export * from './process-memory.js';
 export * from './profile-capture.js';
 export * from './profile-digest.js';
 export * from './profiling-run.js';

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

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

package/src/node/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/measure-memory.ts

@@ -8,10 +8,9 @@
  ********************************************************************************/
 
 import * as fs from 'node:fs';
-import { performance } from 'node:perf_hooks';
 import * as path from 'node:path';
 import * as v8 from 'node:v8';
-import { Format } from '@hydranium/protocol';
+import { Format, SystemClock } from '@hydranium/protocol';
 import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
 import { buildWorkspaceProgrammatically } from '../langium/workspace/initialize-workspace.js';
 import { tallyAstGroundTruth } from './ast-ground-truth.js';
@@ -120,10 +119,11 @@ export async function measureModelMemory(options: MeasureModelMemoryOptions): Pr
    const { shared } = options.createServices();
    const empty = report('after-services-empty');
 
-   const start = performance.now();
+   // Not `shared.Clock`, which the service factory may fake: the build time is reported as measured.
+   const sinceBuildStart = new SystemClock().stopwatch();
    const build = (): Promise<void> => buildWorkspaceProgrammatically(shared, options.workspace);
    await (profilingRun ? profilingRun.window('build', build) : build());
-   const buildMs = performance.now() - start;
+   const buildMs = sinceBuildStart.elapsedMs;
    const docs = shared.workspace.LangiumDocuments.all.toArray();
    const settleMs = options.settleMs ?? 0;
    if (settleMs > 0) {
@@ -174,6 +174,7 @@ export async function measureModelMemory(options: MeasureModelMemoryOptions): Pr
       result.churnGrowthBytes = growth;
       const verdict = growth > 5 * 1024 * 1024 ? 'POSSIBLE RETENTION' : 'stable (no leak)';
       log(`Rebuild churn growth ${Format.bytes(growth)} over ${editCycles} cycles - ${verdict}`);
+      log(`Documents after churn: ${shared.workspace.LangiumDocuments.all.toArray().length}`);
    }
 
    if (options.writeSnapshot) {