@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,215 @@
+/********************************************************************************
+ * 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 AstNode,
+   type AstReflection,
+   AstUtils,
+   CstUtils,
+   GrammarAST,
+   interruptAndCheck,
+   type LangiumDocument,
+   type ReferenceInfo
+} from '@hydranium/langium';
+import { AbstractSemanticTokenProvider, type SemanticTokenAcceptor } from '@hydranium/langium/lsp';
+import { type CancellationToken, SemanticTokenModifiers, SemanticTokenTypes } from 'vscode-languageserver';
+import { type NameProvider } from '../langium/naming/name-provider.js';
+import { type ServerLanguageServices } from '../langium/language-module.js';
+
+/**
+ * What a node or reference should be coloured as. The bare string form is the
+ * common case (`SemanticTokenTypes.class`); the object form is for the
+ * minority that also need modifiers, or that need to suppress the
+ * declaration modifier this provider adds by default (pass `modifier: []`).
+ */
+export type SemanticTokenKind = string | { readonly type: string; readonly modifier?: string | string[] };
+
+/** Normalise both {@link SemanticTokenKind} forms to the acceptor's shape. */
+function toAcceptorFields(kind: SemanticTokenKind, fallbackModifier?: string): { type: string; modifier?: string | string[] } {
+   if (typeof kind === 'string') {
+      return fallbackModifier === undefined ? { type: kind } : { type: kind, modifier: fallbackModifier };
+   }
+   return kind.modifier === undefined && fallbackModifier !== undefined ? { type: kind.type, modifier: fallbackModifier } : { ...kind };
+}
+
+/** Behaviour switches for {@link AbstractHydraniumSemanticTokenProvider}. */
+export interface HydraniumSemanticTokenProviderOptions {
+   /**
+    * Also emit a `keyword` token for every keyword leaf of the CST.
+    *
+    * OFF by default, and the default is not timidity: semantic tokens OVERRIDE
+    * a client-side TextMate grammar, and such a grammar classifies keywords
+    * with far finer scopes (`keyword.control`, `storage.type`,
+    * `keyword.operator`) than the one flat `keyword` a legend can carry — so
+    * turning this on in a host that ships a grammar makes its editor *less*
+    * coloured, not more. It exists for the host that ships NO client-side
+    * grammar at all (a plain-Monaco page, a minimal web client), where the
+    * server's tokens are the only source of colour and keywords otherwise
+    * render in the editor's default foreground.
+    */
+   readonly highlightKeywords?: boolean;
+}
+
+/**
+ * Semantic-token provider that derives highlighting from ONE adopter-supplied
+ * map of AST type → token kind, instead of a hand-written walk.
+ *
+ * **What it replaces.** Langium's {@link AbstractSemanticTokenProvider} hands
+ * you every node and asks you to emit tokens for it, so a grammar-specific
+ * provider becomes a chain of typeguards, each repeating two mechanical
+ * steps: emit the declaration name with `property: 'name'`, then emit one
+ * acceptor call per cross-reference property, remembering `index` for the
+ * multi-valued ones. Both steps are derivable, and getting the second one
+ * wrong is silent — a forgotten reference property simply renders uncoloured.
+ *
+ * **How the derivation works.**
+ * - The declaration name's PROPERTY comes from {@link NameProvider.getNameProperty},
+ *   so an `id`-keyed grammar works without the provider hardcoding `'name'`.
+ * - Cross-references are discovered with Langium's `streamReferences`, which
+ *   yields every reference on the node with its property and index already
+ *   filled in — so multi-valued references cannot be missed or mis-indexed.
+ * - A reference's kind is resolved from the reference's DECLARED target type
+ *   (`AstReflection.getReferenceType`), NOT from `ref.ref.$type`. That is
+ *   deliberate: the declared type is available whether or not the reference
+ *   resolves, so a broken or half-typed document keeps its colouring instead
+ *   of flickering as links come and go.
+ *
+ * The net effect is that {@link getTokenKind} — a `$type` string in, a token
+ * kind out — is usually the only member an adopter writes.
+ *
+ * Anything the map cannot express stays overridable: {@link getDeclarationKind}
+ * and {@link getReferenceKind} for per-node or per-property decisions,
+ * {@link highlightElement} for tokens that are neither a declaration nor a
+ * cross-reference (a sub-range, a single keyword of one rule). Returning
+ * `'prune'` from an override still skips the subtree, as upstream. Colouring
+ * EVERY keyword is not one of those cases — that is
+ * {@link HydraniumSemanticTokenProviderOptions.highlightKeywords}, which walks
+ * the CST once instead.
+ */
+export abstract class AbstractHydraniumSemanticTokenProvider extends AbstractSemanticTokenProvider {
+   protected readonly nameProvider: NameProvider;
+   protected readonly reflection: AstReflection;
+   protected readonly options: HydraniumSemanticTokenProviderOptions;
+
+   /**
+    * Modifier added to every declaration token. `declaration` is what themes
+    * key on to render a definition differently from a use; override to
+    * `undefined` to add none.
+    */
+   protected readonly declarationModifier: string | undefined = SemanticTokenModifiers.declaration;
+
+   constructor(services: ServerLanguageServices, options: HydraniumSemanticTokenProviderOptions = {}) {
+      super(services);
+      this.nameProvider = services.references.NameProvider;
+      this.reflection = services.shared.AstReflection;
+      this.options = options;
+   }
+
+   /**
+    * The AST pass, then — when asked for — one CST pass over the keywords.
+    *
+    * **The keyword pass belongs here and not in {@link highlightElement}**,
+    * which is called once per AST node: a node reaching its own keyword leaves
+    * has to descend its CST subtree, and every node repeating that visits each
+    * leaf once per ancestor, so the AST-hosted version is O(leaves × depth)
+    * against this one's O(leaves). It also cannot be written correctly with a
+    * `prune`, because a keyword leaf's nearest AST node is not always the one
+    * whose rule contributed it.
+    *
+    * Emitting out of positional order is safe: `SemanticTokensBuilder` sorts
+    * before it encodes the deltas, so the two passes need not interleave. The
+    * range form of the request needs no accommodation either — the acceptor
+    * drops anything outside `currentRange` on its own.
+    */
+   protected override async computeHighlighting(
+      document: LangiumDocument,
+      acceptor: SemanticTokenAcceptor,
+      cancelToken: CancellationToken
+   ): Promise<void> {
+      await super.computeHighlighting(document, acceptor, cancelToken);
+      if (this.options.highlightKeywords !== true) {
+         return;
+      }
+      const root = document.parseResult.value.$cstNode;
+      if (root === undefined) {
+         return;
+      }
+      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)) {
+            acceptor({ cst, type: SemanticTokenTypes.keyword });
+         }
+      }
+   }
+
+   protected override highlightElement(node: AstNode, acceptor: SemanticTokenAcceptor): void | undefined | 'prune' {
+      this.highlightDeclaration(node, acceptor);
+      this.highlightReferences(node, acceptor);
+      return undefined;
+   }
+
+   /** Colour the node's own name, at whichever property the NameProvider reads it from. */
+   protected highlightDeclaration(node: AstNode, acceptor: SemanticTokenAcceptor): void {
+      const kind = this.getDeclarationKind(node);
+      if (kind === undefined) {
+         return;
+      }
+      const property = this.getNameProperty(node);
+      if (property === undefined) {
+         return;
+      }
+      acceptor({ node, property, ...toAcceptorFields(kind, this.declarationModifier) });
+   }
+
+   /** Colour every cross-reference the node carries, including multi-valued ones. */
+   protected highlightReferences(node: AstNode, acceptor: SemanticTokenAcceptor): void {
+      for (const info of AstUtils.streamReferences(node)) {
+         const kind = this.getReferenceKind(info);
+         if (kind === undefined) {
+            continue;
+         }
+         acceptor({ node: info.container, property: info.property, index: info.index, ...toAcceptorFields(kind) });
+      }
+   }
+
+   /**
+    * The adopter's map: an AST `$type` in, the token kind its declarations and
+    * the references pointing at it should render as. `undefined` leaves the
+    * type uncoloured.
+    *
+    * What uncoloured means depends on the host, and this map cannot see which:
+    * a host shipping a TextMate grammar keeps that grammar's colour, a host
+    * shipping none renders the default foreground. So `undefined` says only
+    * "not a name worth a kind of its own" — never "someone else will colour
+    * it". Keywords in particular are not left to this map at all; they are
+    * {@link HydraniumSemanticTokenProviderOptions.highlightKeywords}, because
+    * they have no AST type to key on.
+    */
+   protected abstract getTokenKind(type: string): SemanticTokenKind | undefined;
+
+   /** Kind for `node`'s own declaration. Defaults to {@link getTokenKind} on its `$type`. */
+   protected getDeclarationKind(node: AstNode): SemanticTokenKind | undefined {
+      return this.getTokenKind(node.$type);
+   }
+
+   /** Kind for a cross-reference. Defaults to {@link getTokenKind} on the reference's DECLARED target type. */
+   protected getReferenceKind(info: ReferenceInfo): SemanticTokenKind | undefined {
+      return this.getTokenKind(this.reflection.getReferenceType(info));
+   }
+
+   /** Property holding `node`'s name. Defaults to the language's {@link NameProvider}. */
+   protected getNameProperty(node: AstNode): string | undefined {
+      return this.nameProvider.getNameProperty(node);
+   }
+}

package/src/lsp/shared-module.ts

@@ -0,0 +1,88 @@
+/********************************************************************************
+ * 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 Module } from '@hydranium/langium';
+import { type PartialLangiumSharedServices } from '@hydranium/langium/lsp';
+import { LspLogger } from '../langium/diagnostics/lsp-logger.js';
+import { type ServerModuleContext, type ServerSharedServices } from '../langium/module.js';
+import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-handler.js';
+
+/**
+ * Shared-tier slots contributed by the LSP-textual protocol head. Bound by
+ * {@link createLspServerSharedModule}; consumer modules layered after it can
+ * override any slot.
+ *
+ * - {@link LspLogger} replaces the shared tier's `NoopLogger` on the `Logger` slot,
+ *   so a head composing this module actually emits. It routes through the LSP
+ *   `window/logMessage` channel once a `Connection` is bound and to `stderr`
+ *   before that (or in a headless head that never binds one), and its
+ *   constructor is what applies the `HYDRANIUM_LOG_LEVEL` / `HYDRANIUM_LOG_FILE`
+ *   env baselines — so binding it here is also what makes `hydranium-cli
+ *   --log-level` reach the spawned server. Adopters wanting a different sink
+ *   (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.
+ *
+ * **Why this is a shared slot and not a per-language one.** Langium declares
+ * `DocumentUpdateHandler` in `LangiumSharedLSPServices` — there is exactly one
+ * per server, and `startLanguageServer` reads it off the shared tree. It is
+ * parameterised by the CLIENT PROTOCOL (which LSP notifications arrive), not
+ * by the grammar — the rule for which DI scope a service belongs to. Binding
+ * it per language is inert: nothing reads a per-language
+ * `lsp.DocumentUpdateHandler`, and under a multi-grammar composition a
+ * per-language binding would attach N listener sets to the one document store.
+ */
+export interface LspServerAddedSharedServices {
+   /* override */ Logger: LspLogger;
+   lsp: {
+      /* override */ DocumentUpdateHandler: HydraniumDocumentUpdateHandler;
+   };
+}
+
+/**
+ * Full shared-service surface visible to consumers that compose this head:
+ * `@hydranium/core`'s shared bindings plus the LSP-textual additions. Use as
+ * the `T` type parameter for the consumer's own
+ * `Module<LspServerSharedServices, ...>` if its overrides depend on any
+ * LSP-only shared slot.
+ */
+export type LspServerSharedServices = ServerSharedServices & LspServerAddedSharedServices;
+
+/**
+ * The LSP-textual protocol head's default shared module. Composes on top of
+ * `createServerSharedModule` — as a later `inject(...)` argument, or as
+ * `sharedModules.extra` when composing through `createIntegrationServices`;
+ * the adopter's own shared module goes after it either way.
+ *
+ * `createServerSharedModule` MUST be merged before this one — the lsp-server
+ * head only contributes LSP-textual-specific slots and relies on
+ * `@hydranium/core`'s `SelfSaveRegistry` / `TextDocuments` / `DocumentBuilder`
+ * bindings being present.
+ *
+ * Returned as a function (not a constant) so head defaults can read from the
+ * construction context, mirroring `createLspServerLanguageModule`.
+ */
+export function createLspServerSharedModule(
+   _context: ServerModuleContext
+): Module<LspServerSharedServices, PartialLangiumSharedServices & LspServerAddedSharedServices> {
+   return {
+      Logger: services => new LspLogger(services),
+      lsp: {
+         DocumentUpdateHandler: services => new HydraniumDocumentUpdateHandler(services)
+      }
+   };
+}

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

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * 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 {
+   startLanguageServer as startLangiumLanguageServer,
+   type LangiumSharedServices,
+   type ServiceRequirements
+} from '@hydranium/langium/lsp';
+import { HydraniumDocumentUpdateHandler } from './hydranium-document-update-handler.js';
+
+/**
+ * Fail the LSP head's start when its shared module was never composed.
+ *
+ * **The composition mistake this catches.** `lsp.DocumentUpdateHandler` is a
+ * 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.
+ *
+ * The type system does not catch it. `createIntegrationServices` returns
+ * `inject(...) as unknown as TShared`, so widening `TShared` with
+ * `LspServerAddedSharedServices` while omitting the module type-checks and
+ * leaves the slot holding Langium's default.
+ *
+ * Checked with `instanceof`, so an adopter subclass of
+ * {@link HydraniumDocumentUpdateHandler} — the documented way to extend the
+ * handler — passes.
+ *
+ * Skips silently when no connection is bound: that is a more fundamental
+ * misconfiguration, and Langium reports it immediately afterwards in its own
+ * vocabulary. Reporting it here as a missing module would misname it.
+ */
+export function assertLspHeadComposed(services: LangiumSharedServices): void {
+   if (!services.lsp?.Connection) {
+      return;
+   }
+   const handler = services.lsp.DocumentUpdateHandler;
+   if (!(handler instanceof HydraniumDocumentUpdateHandler)) {
+      throw new Error(
+         '[hydranium] the LSP head is starting without its shared module: `lsp.DocumentUpdateHandler` holds ' +
+            `'${handler?.constructor?.name ?? 'nothing'}' rather than a HydraniumDocumentUpdateHandler. Echo suppression for ` +
+            "the server's own writes, the didChangeContent debounce, build-reason stamping and the last-client-close rebuild " +
+            'are all inert in that state. Add `createLspServerSharedModule(context)` to the shared tier — as ' +
+            '`sharedModules.extra` when composing through `createIntegrationServices`, or as an `inject(...)` argument ' +
+            'after `createServerSharedModule(context)`.'
+      );
+   }
+}
+
+/**
+ * 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`.
+ */
+export function startLanguageServer(services: LangiumSharedServices, serviceRequirements: Partial<ServiceRequirements> = {}): void {
+   assertLspHeadComposed(services);
+   startLangiumLanguageServer(services, serviceRequirements);
+}

package/src/node/ast-ground-truth.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * 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 { AstUtils } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { buildWorkspaceProgrammatically } from '../langium/workspace/initialize-workspace.js';
+
+/** Options for {@link collectAstGroundTruth}. */
+export interface AstGroundTruthOptions {
+   /**
+    * Create the language's shared services in-process. This is the only
+    * language-specific input — a head passes its own `create<Lang>Services(fileSystem)`.
+    */
+   createServices: () => { shared: ServerSharedServicesMinimal };
+   /** Workspace root (filesystem path or file URI) to build. */
+   workspace: string;
+}
+
+/**
+ * Live-model `$type` tally — the ground truth an offline heap snapshot is
+ * validated against (the analyzer's `--validate <gt.json>` input). The shape is
+ * deliberately the JSON contract the analyzer reads: a per-`$type` count plus the
+ * document and node totals used to assert the snapshot was captured on the same
+ * workspace.
+ */
+export interface AstGroundTruth {
+   /** Number of `LangiumDocument`s in the built workspace. */
+   documents: number;
+   /** Total AST nodes across all documents (root included). */
+   totalAstNodes: number;
+   /** Count of AST nodes per `$type`. */
+   byType: Record<string, number>;
+}
+
+/**
+ * Headless live-model `$type` census — the browser-/socket-free counterpart to
+ * walking the AST in the running server. Boots a head's Langium services
+ * in-process via {@link AstGroundTruthOptions.createServices}, builds the
+ * workspace, then streams every AST node and tallies it by `$type`.
+ *
+ * The result is the ground truth the offline heap analyzer validates a snapshot's
+ * `$type` classification against (`hydranium-cli analyze-heap --validate`): the
+ * snapshot is captured on a workspace, this census is run on the *same* workspace,
+ * and matching counts confirm the classifier read the heap correctly. Pure
+ * framework code: the only language-specific input is the service factory.
+ */
+export async function collectAstGroundTruth(options: AstGroundTruthOptions): Promise<AstGroundTruth> {
+   const { shared } = options.createServices();
+   await buildWorkspaceProgrammatically(shared, options.workspace);
+   return tallyAstGroundTruth(shared);
+}
+
+/**
+ * Tally the `$type` census over an ALREADY-built services tree — the pure core of
+ * {@link collectAstGroundTruth}, split out so a harness that has already built the
+ * workspace (e.g. `measureModelMemory`) can fold the ground truth into its bundle
+ * without a second build.
+ */
+export function tallyAstGroundTruth(shared: ServerSharedServicesMinimal): AstGroundTruth {
+   const documents = shared.workspace.LangiumDocuments.all.toArray();
+   const byType: Record<string, number> = {};
+   let totalAstNodes = 0;
+   for (const document of documents) {
+      for (const node of AstUtils.streamAst(document.parseResult.value)) {
+         byType[node.$type] = (byType[node.$type] ?? 0) + 1;
+         totalAstNodes += 1;
+      }
+   }
+   return { documents: documents.length, totalAstNodes, byType };
+}

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

@@ -0,0 +1,89 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { monitorEventLoopDelay } from 'node:perf_hooks';
+import { formatMemory } from '../langium/diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { formatServerState } from './server-state-snapshot.js';
+
+export const DEFAULT_EVENT_LOOP_THRESHOLD_MS = 100;
+export const DEFAULT_EVENT_LOOP_INTERVAL_MS = 1000;
+export const DEFAULT_EVENT_LOOP_SNAPSHOT_ABOVE_MS = 500;
+
+export interface EventLoopMonitorOptions {
+   /** Stalls >= this within the sample window log a warning. */
+   thresholdMs?: number;
+   /** Sample window in ms. */
+   intervalMs?: number;
+   /** Stalls >= this trigger {@link onStallSnapshot} in addition to the warning. */
+   snapshotAboveMs?: number;
+   /** Log-name label derived from `shared.Logger`. Default `'EventLoop'`. */
+   logName?: string;
+   /**
+    * Fires after a stall >= {@link snapshotAboveMs}; the on-demand command rides
+    * the same path. Defaults to a full {@link formatServerState} — process /
+    * heap state **plus** per-document detail (`shared.workspace.LangiumDocuments`),
+    * logged under the `'Process'` component (matching the on-demand dump). Pass
+    * a custom callback to change it, or a no-op to suppress it.
+    */
+   onStallSnapshot?: (maxMs: number) => void;
+}
+
+/**
+ * Logs a warning when the event loop is blocked longer than the threshold.
+ *
+ * Follows the framework `(services, options)` shape: derives its own
+ * `'EventLoop'` component logger from `shared.Logger`, and the default
+ * stall snapshot reaches `shared.workspace.LangiumDocuments` for per-document
+ * detail.
+ */
+export function startEventLoopMonitor(shared: ServerSharedServicesMinimal, options: EventLoopMonitorOptions = {}): () => void {
+   const logger = shared.Logger.for(options.logName ?? 'EventLoop');
+   const thresholdMs = options.thresholdMs ?? DEFAULT_EVENT_LOOP_THRESHOLD_MS;
+   const intervalMs = options.intervalMs ?? DEFAULT_EVENT_LOOP_INTERVAL_MS;
+   const snapshotAboveMs = options.snapshotAboveMs ?? DEFAULT_EVENT_LOOP_SNAPSHOT_ABOVE_MS;
+   const onStallSnapshot =
+      options.onStallSnapshot ??
+      ((maxMs: number) =>
+         shared.Logger.for('Process').info(
+            formatServerState(shared.workspace.LangiumDocuments, `auto: event-loop stall ${Math.round(maxMs)}ms`)
+         ));
+   const histogram = monitorEventLoopDelay({ resolution: 10 });
+   histogram.enable();
+   const interval = setInterval(() => {
+      const maxMs = histogram.max / 1e6;
+      if (maxMs >= thresholdMs) {
+         const p99Ms = histogram.percentile(99) / 1e6;
+         const meanMs = histogram.mean / 1e6;
+         // Always include heap/rss: stalls are the moment to correlate with memory pressure.
+         logger.warn(
+            `Event-loop stall up to ${Math.round(maxMs)}ms ` +
+               `in last ${intervalMs}ms ` +
+               `(p99 ${Math.round(p99Ms)}ms, ` +
+               `mean ${meanMs.toFixed(1)}ms, ` +
+               `${formatMemory()})`
+         );
+         if (maxMs >= snapshotAboveMs) {
+            // Defensive: a snapshot failure must not silence subsequent stall warnings.
+            try {
+               onStallSnapshot(maxMs);
+            } catch (error) {
+               logger.warn(`Stall snapshot failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+         }
+      }
+      histogram.reset();
+   }, intervalMs);
+   // Do not keep the process alive solely for the monitor.
+   interval.unref?.();
+   return () => {
+      clearInterval(interval);
+      histogram.disable();
+   };
+}

package/src/node/index.ts

@@ -0,0 +1,53 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Server-only entry (`@hydranium/core/node`). Everything reachable from here may
+// pull `node:*`; the portable `.` barrel must NOT. Anything exported here is
+// "server-only" by contract — adopters building for the browser import `.` only.
+//
+// Node hosts get the log file-tee for free: importing this entry installs the
+// `node:fs`-backed sink (see `installNodeLogFileSink`) at module load, before
+// the first logger is constructed. The function is re-exported for explicit
+// control / tests.
+// Node hosts also get workspace-write-lock reentrancy detection for free, by the
+// same mechanism and for the same reason: the check needs `node:async_hooks`, so
+// the neutral tree can only declare the seam.
+import { installNodeLogFileSink } from './log-file-sink.js';
+import { installNodeWriteLockScope } from './write-lock-scope-node.js';
+
+export * from './node-file-system-provider.js';
+export * from './log-file-sink.js';
+export * from './write-lock-scope-node.js';
+export * from './log-preamble-node.js';
+export * from './server-diagnostics.js';
+
+// Node-only headless tools, diagnostics and launchers — pure `node:*` modules
+// that physically live under `src/node/` (the server-only tree). The real-path
+// document-identity policy is deliberately NOT among them: the `realpath`
+// syscall is delegated to the Node `FileSystemProvider`, which leaves
+// `RealpathDocumentUriPolicy` browser-neutral, so it ships from the portable
+// entry alongside the default policy.
+export * from './ast-ground-truth.js';
+export * from './event-loop-monitor.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';
+export * from './reflect-grammar.js';
+export * from './server-state-snapshot.js';
+export * from './socket-launcher.js';
+export * from './stdio-launcher.js';
+export * from './validate-workspace.js';
+
+installNodeLogFileSink();
+installNodeWriteLockScope();

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

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type Clock, LatencyCollector } from '@hydranium/protocol';
+
+/**
+ * Env flag that installs the per-method latency seam. Its presence (any
+ * non-empty value) is the switch; unset means {@link latencyFromEnv} returns
+ * `undefined` and the head never wires the collector — so the RPC binder, the
+ * data-server and the LSP decorator all stay on their zero-cost paths.
+ *
+ * The {@link LatencyCollector} keeps every sample for exact percentiles, sized
+ * for a bounded diagnostics window rather than always-on production telemetry;
+ * gating it behind an explicit flag keeps a long-lived head from accumulating
+ * samples it will never read. Mirrors `HYDRANIUM_PROFILE_E2E`.
+ */
+export const DEFAULT_LATENCY_ENV = 'HYDRANIUM_LATENCY';
+
+/** True when the latency env flag is set to a non-empty value. */
+export function isLatencyEnabled(): boolean {
+   return !!process.env[DEFAULT_LATENCY_ENV];
+}
+
+/**
+ * A {@link LatencyCollector} when {@link DEFAULT_LATENCY_ENV} is set, otherwise
+ * `undefined`. Heads pass the result straight to `instrumentLspConnection`, 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.
+ */
+export function latencyFromEnv(clock?: Clock): LatencyCollector | undefined {
+   return isLatencyEnabled() ? new LatencyCollector(clock) : undefined;
+}